turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "stream",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      // Turbo 2 runs tasks in strict env mode: a variable that is not declared
      // here never reaches the task process at all. Undeclared vars are not
      // merely uncached — they are absent, silently.
      //
      // `env` participates in the cache key (the value changes the output).
      // `passThroughEnv` reaches the process without busting the cache (the
      // value is needed at runtime but does not change what gets built).
      "env": [
        // Standard build-mode switch; read by sdk-next's MDX path.
        "NODE_ENV",
        // Baked into the Studio bundle by packages/studio/vite.config.ts.
        "GRAFT_STUDIO_ORIGIN"
      ],
      "passThroughEnv": [
        // Better Auth is constructed at module scope in examples/landing-page,
        // so `next build` evaluates it and warns when no secret is present.
        // Server-side only and never inlined, so it cannot change build output.
        "BETTER_AUTH_SECRET",
        "BETTER_AUTH_URL",
        // Read by the examples' graft/auth clients and API routes. Server-side
        // only (no NEXT_PUBLIC_ prefix), so Next will not inline it.
        "DATABASE_URL",
        "GRAFT_DEV_TOKEN",
        "GRAFT_MCP_ALLOW_ANONYMOUS",
        // Which accounts the landing-page example grants operator scopes to.
        "GRAFT_OPERATOR_EMAILS",
        // Deployment provenance, read per-request by the functions handler.
        "VERCEL_GIT_COMMIT_SHA",
        "GITHUB_SHA"
      ],
      // `.vercel/output` is the docs site's real build product — the artifact
      // Vercel uploads, and the one `pnpm check:site` reads. Undeclared, turbo
      // does not own it: a cache hit would restore `dist/**` and leave this
      // stale, or absent on a fresh runner, and the check would be reading
      // nothing while the build reported success.
      //
      // Not a live bug: docs-site currently misses cache on every run, and CI
      // configures no turbo cache at all. Both of those are circumstances
      // rather than guarantees, and the declaration is what makes the artifact
      // turbo's to restore when either changes.
      "outputs": ["dist/**", ".next/**", "!.next/cache/**", ".vercel/output/**"]
    },
    // The CLI reaches @usegraft/studio only through dynamic `import()`, and
    // only behind an opt-in: `graft studio`, or `graft serve --studio`
    // (commands/studio.ts:51, commands/serve.ts:262). There is no static
    // import, so tsup never reads studio's dist and the CLI builds fine
    // without it.
    //
    // The generic "^build" cannot know that. It walks package.json, where
    // studio is an ordinary dependency — and must stay one, because
    // `graft studio` resolves it at runtime and an optional peer would turn a
    // shipped feature into an install someone has to know about.
    //
    // Left implicit, the cost lands on every consumer of the CLI: building
    // examples/docs-site ran a full `vite build` of the Studio SPA so a static
    // docs site could execute one `graft compile`.
    //
    // This restates cli's workspace dependencies minus studio. It is a manual
    // list, which is the trade: a dependency added to packages/cli/package.json
    // must be added here too or it will not be built before the CLI.
    "@usegraft/cli#build": {
      "dependsOn": [
        "@usegraft/assets#build",
        "@usegraft/auth#build",
        "@usegraft/compiler#build",
        "@usegraft/content-api#build",
        "@usegraft/content-migrations#build",
        "@usegraft/contracts#build",
        "@usegraft/core#build",
        "@usegraft/db#build",
        "@usegraft/mcp#build",
        "@usegraft/mdx-safety#build",
        "@usegraft/registry#build",
        "@usegraft/sdk-core#build"
      ],
      // Package-scoped task config does not inherit the generic "build" entry,
      // so these are restated rather than omitted.
      "env": ["NODE_ENV"],
      "outputs": ["dist/**"]
    },
    "typecheck": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"],
      // All cache-keyed rather than passed through: these decide *which* tests
      // run, so a cached pass from a skipped run must never satisfy a real one.
      // Without RUN_INTEGRATION declared, `RUN_INTEGRATION=1 pnpm test` was
      // silently running the unit suite and reporting green.
      "env": [
        "RUN_INTEGRATION",
        "DATABASE_URL",
        "NEON_API_KEY",
        "GRAFT_NEON_PROJECT_ID",
        "S3_ENDPOINT",
        "S3_ACCESS_KEY"
      ]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}