When to Split Your Turborepo Config into Package-Level Configs

November 20, 2026 | 8 minutes

A root turbo.json is easy to understand when every package builds the same way, but becomes harder to maintain when the Next.js app, API, and shared library all need different outputs and environment variables. Eventually, changing one package means reading through everyone else's build settings.

Package-level configs let you keep shared defaults in the root and put exceptions next to the code that needs them. So when does this split makes the repository easier to maintain and how do we check that it still builds and caches correctly? Let's refactor a small monorepo and inspect the results.

Package-level configuration has existed since Turborepo 1.8. The examples use the 2.x tasks syntax, though, and the optional array-extension and shared-config examples require 2.7 or later.

Start with the Packages, Not the Config Files

Our workspace contains three packages:

Package nameDirectoryBuild outputBuild-time environment variables
webapps/web.next/BUILD_MODE, NEXT_PUBLIC_API_URL
apiapps/apibuild/BUILD_MODE, API_SCHEMA_VERSION
@example/sharedpackages/shareddist/BUILD_MODE

Both applications declare @example/shared in their package.json dependencies. Each package has a build script. For this example, all three builds use BUILD_MODE, and the API build uses API_SCHEMA_VERSION to select generated schema content. These are inputs to the build, not just variables the deployed application reads at runtime.

Those package relationships matter: dependsOn: ["^build"] schedules builds of package dependencies first. It doesn't infer dependencies from directory names or import statements, and a turbo.json task definition doesn't create a missing package.json script.

Here's a crowded but valid starting point in the root turbo.json:

1{
2  "$schema": "https://turborepo.dev/schema.json",
3  "tasks": {
4    "build": {
5      "dependsOn": ["^build"],
6      "outputs": ["dist/**", "build/**", ".next/**", "!.next/cache/**", "!.next/dev/**"],
7      "env": ["BUILD_MODE", "API_SCHEMA_VERSION", "NEXT_PUBLIC_API_URL"]
8    },
9    "lint": {}
10  }
11}

Every package inherits every listed build variable. One side effect of this is that changing API_SCHEMA_VERSION changes the build hash for the web app and shared library too, even though their builds don't use it. The output patterns also describe three different kinds of packages at once.

You could keep everything in the root using package-specific tasks, such as web#build, which is a reasonable option for a few exceptions. We'll use package configs here, though, so that each application's settings live beside its code.

Keep Shared Defaults in the Root

Replace the root turbo.json with:

1{
2  "$schema": "https://turborepo.dev/schema.json",
3  "tasks": {
4    "build": {
5      "dependsOn": ["^build"],
6      "outputs": ["dist/**"],
7      "env": ["BUILD_MODE"]
8    },
9    "lint": {}
10  }
11}

The shared library already fits these defaults, so it doesn't need a turbo.json. Next, create apps/web/turbo.json:

1{
2  "$schema": "https://turborepo.dev/schema.json",
3  "extends": ["//"], // workspace root
4  "tasks": {
5    "build": {
6      "outputs": [".next/**", "!.next/cache/**", "!.next/dev/**"],
7      "env": ["BUILD_MODE", "NEXT_PUBLIC_API_URL"]
8    }
9  }
10}

And apps/api/turbo.json:

1{
2  "$schema": "https://turborepo.dev/schema.json",
3  "extends": ["//"], // workspace root
4  "tasks": {
5    "build": {
6      "outputs": ["build/**"],
7      "env": ["BUILD_MODE", "API_SCHEMA_VERSION"]
8    }
9  }
10}

"//" refers to the workspace root. Each application inherits the root task properties it doesn't override, including dependsOn: ["^build"]. The web app now caches its Next.js output while excluding the framework's cache and development output directories; the API caches build/.

The explicit NEXT_PUBLIC_API_URL entry documents a build input. Turborepo also has framework inference, which automatically accounts for NEXT_PUBLIC_* variables when it detects Next.js.

Understand What's Inherited and What's Replaced

Overriding a task property does not replace the entire task. For the web config above, the important results are:

PropertyPackage settingEffective value
dependsOnOmitted["^build"], inherited from root
outputsNext.js patternsPackage array replaces ["dist/**"]
envTwo variablesPackage array replaces ["BUILD_MODE"]

This is why both package configs repeat BUILD_MODE: a new env array replaces the inherited array. If you removed BUILD_MODE from the package array, the root entry wouldn't be retained automatically.

Starting in Turborepo 2.7, you can preserve inherited array entries with $TURBO_EXTENDS$. For example, this is an alternative complete apps/api/turbo.json:

1{
2  "extends": ["//"],
3  "tasks": {
4    "build": {
5      "outputs": ["build/**"],
6      "env": ["$TURBO_EXTENDS$", "API_SCHEMA_VERSION"]
7    }
8  }
9}

Put the marker first. Here it retains BUILD_MODE and adds API_SCHEMA_VERSION. This is useful if the shared list may grow. The same mechanism works for arrays such as dependsOn, inputs, and outputs; see the package configuration reference.

Choose replacement when the package needs a different list. The API should replace dist/** with build/**, for example, rather than keep an unused output directory just because appending is available.

Be Careful When Narrowing Inputs

It's tempting to list only src/** as an input to make builds miss cache less often. But an explicit inputs array opts out of default file tracking. You could accidentally leave out a configuration file that changes the build result.

If a package's README.md has no effect on its build, for example, preserve the default inputs and exclude that one file. For example, packages/shared/turbo.json could contain:

1{
2  "extends": ["//"],
3  "tasks": {
4    "build": {
5      "inputs": ["$TURBO_DEFAULT$", "!README.md"]
6    }
7  }
8}

$TURBO_DEFAULT$ restores Turborepo's default inputs. It serves a different purpose from $TURBO_EXTENDS$, which retains an array from the inherited configuration. If the root already has intentional custom inputs, consider extending those instead. The inputs reference explains the defaults and special syntax.

Only exclude files that cannot affect the task's result. Tests can still participate in type-checking during a build, and some builds include README content. A cache hit is useful only if the cached output is correct.

Verify the Refactor with a Dry Run

From the workspace root, using the project's installed Turborepo version, run:

1npx turbo run build --filter=web --dry-run=json

In the tasks array, find the entry whose taskId is web#build. Check:

  • resolvedTaskDefinition.dependsOn still includes ^build.
  • resolvedTaskDefinition.outputs contains the Next.js patterns, not dist/**.
  • resolvedTaskDefinition.env includes BUILD_MODE and NEXT_PUBLIC_API_URL.
  • dependencies includes @example/shared#build.

The last check verifies the actual task relationship, not just the presence of a configuration string. If the shared build is missing, inspect the application's package.json dependencies and the shared package's build script.

Then compare hashes with only the API variable changed. These commands use POSIX shell syntax and write outside the workspace so the reports don't become build inputs:

1BUILD_MODE=production NEXT_PUBLIC_API_URL=https://example.test API_SCHEMA_VERSION=v1 \
2  npx turbo run build --dry-run=json > /tmp/turbo-schema-v1.json
3
4BUILD_MODE=production NEXT_PUBLIC_API_URL=https://example.test API_SCHEMA_VERSION=v2 \
5  npx turbo run build --dry-run=json > /tmp/turbo-schema-v2.json

Compare each task's hash between the two reports. With this package graph and the refactored configs, api#build should change; web#build and @example/shared#build should stay the same. With the original broad env list, all three change.

This result depends on the graph. If the web build depended on the API build, the changed API task hash could affect the web task too. Files, dependencies, lockfile changes, global configuration, and other environment variables can also invalidate caches. Package configs don't isolate a task from its real dependencies.

Finally, run an actual build twice with identical inputs:

1BUILD_MODE=production NEXT_PUBLIC_API_URL=https://example.test API_SCHEMA_VERSION=v1 \
2  npx turbo run build
3
4BUILD_MODE=production NEXT_PUBLIC_API_URL=https://example.test API_SCHEMA_VERSION=v1 \
5  npx turbo run build

The second run should reuse cached results for these cacheable tasks. Delete only their generated output directories and run again to check that Turborepo restores the expected artifacts. Remember, though, that a dry run can show how a task is configured, but it can't prove that your output patterns capture everything the application needs.

For this post, I verified the configs with Turborepo 2.7.0 and 2.11.13 in an isolated npm workspace. Small Node build scripts wrote to the output directories shown above and read the declared environment variables. The checks covered inheritance, array replacement and extension, dependency ordering, hash changes, input exclusions, cache hits, and artifact restoration.

Share Repeated Configuration When You Need It

If a second Next.js app arrives, duplicating the web settings may be fine at first. When several applications share the same conventions, Turborepo 2.7 and later can extend another workspace package's configuration.

For example, add a workspace package at packages/turbo-config with this package.json:

1{
2  "name": "@example/turbo-config",
3  "version": "1.0.0",
4  "private": true
5}

Its turbo.json holds the shared Next.js outputs:

1{
2  "extends": ["//"],
3  "tasks": {
4    "build": {
5      "outputs": [".next/**", "!.next/cache/**", "!.next/dev/**"]
6    }
7  }
8}

The web app can then use this apps/web/turbo.json:

1{
2  "extends": ["//", "@example/turbo-config"],
3  "tasks": {
4    "build": {
5      "env": ["$TURBO_EXTENDS$", "NEXT_PUBLIC_API_URL"]
6    }
7  }
8}

The shared config package must be included by your package manager's workspace configuration and you'll need to run its install command after adding the package. extends uses the package's name, not its directory path. Keep "//" first because extended configruations are applied in the order they appear in within the extends array. The root is applied first, then the shared config, then the application's own settings.

This package has no build script, so it supplies configuration without creating another executable build. Sharing task configuration also doesn't replace declaring actual code dependencies in package.json.

When the Split Is Worth It

Add package configs when packages have meaningful differences and their maintainers benefit from owning those settings. Keep the root when the defaults already fit, or when a handful of package-specific entries are easier to see together. If every package repeats the same exception, reconsider the default or extract a shared config.

Moving the same settings into different files doesn't inherently improve caching. In this example, the improvement comes from removing unrelated environment variables from each task's inputs. The organizational benefit is that the API's build settings now live with the API, while shared dependency ordering stays in one place.

Start with one package, inspect its resolved task definition, and check the resulting cache behavior before moving the next one. For another way to avoid unnecessary work in CI, see Using Turborepo's --affected Flag in CI.

Related Posts