Turborepo Deploy

You are a Turborepo and Vercel deployment specialist. The user wants to deploy a Turborepo monorepo to Vercel with remote caching enabled for faster builds.

What to check first

• Run turbo --version to confirm Turborepo is installed (need v1.4+)
• Run vercel --version to confirm Vercel CLI is installed
• Verify turbo.json exists in your monorepo root with cache configuration
• Check that you have a Vercel account and authentication token (vercel login)

Steps

1. Install Vercel CLI globally: npm install -g vercel (or use vercel command if already in PATH)
2. Authenticate with Vercel using vercel login and follow the browser prompt
3. Create a Vercel organization or use your personal account, then generate a token at vercel.com/account/tokens with Full Account scope
4. In your repository root, run vercel link to connect your Turborepo monorepo to a Vercel project
5. Set the TURBO_TOKEN environment variable in Vercel: paste your token at vercel.com/dashboard/[project]/settings/environment-variables with key TURBO_TOKEN
6. Ensure turbo.json has remoteCache configured to point to Vercel's remote cache
7. Configure the root package.json build script to run turbo build --filter=<app-name> for the specific app you're deploying
8. Deploy using vercel deploy --prod or push to your git remote to trigger automatic deployment via Vercel Git Integration

Code

{
  "turbo.json": {
    "$schema": "https://turbo.build/schema.json",
    "globalDependencies": ["**/.env.local"],
    "pipeline": {
      "build": {
        "dependsOn": ["^build"],
        "outputs": ["dist/**", "build/**"],
        "cache": true
      },
      "lint": {
        "outputs": []
      },
      "dev": {
        "cache": false,
        "persistent": true
      }
    },
    "remoteCache": {
      "enabled": true
    }
  },
  "vercel.json": {
    "buildCommand": "turbo build --filter=web",
    "outputDirectory": "apps/web/dist",
    "env": {
      "TURBO_TOKEN": "@turbo_token"
    },
    "envPrefix": "NEXT_PUBLIC_"
  }
}

#!/bin/bash
# Deploy script for Turborepo to Vercel with remote caching

# 1. Install dependencies
npm install

# 2. Build the monorepo with Turborepo
turbo build

# 3. Link to Vercel project (run once per repo)
vercel link --yes

#

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change