How do Turborepo tasks map to Nx targets?
Turborepo and Nx both run the same package.json scripts, but they store configuration in different places. Turborepo describes tasks once, globally, in turbo.json. Nx attaches targets to individual projects. A project gets its targets either by inference (from package.json scripts or from plugins that read tool config files) or from explicit declarations in project.json or the nx field of package.json. Settings shared across projects go in targetDefaults in nx.json.
The core rule follows from this: a turbo.json task entry usually becomes a targetDefaults entry keyed by the same target name. Both are global, name-matched defaults, so most of the migration consists of moving dependsOn, outputs and caching settings from one file to the other. Per-package overrides (app#build in Turborepo) are the exception. They belong in that project's own configuration, because Nx applies project-level settings over targetDefaults.
| Turborepo | Nx | Notes |
|---|---|---|
| Task | Target | Both normally wrap a package.json script |
tasks (pipeline in older configs) |
targetDefaults in nx.json |
Global defaults matched by name |
pkg#task override |
Project-level target config | Overrides targetDefaults |
| Package (workspace) | Project | Discovered from workspace globs or project.json |
--filter |
nx affected, nx run-many --projects |
Affected detection uses the project graph and git |
//#task |
Root project target | Script in the root package.json or project.json |
Resolution flows in one direction:
turbo.jsontasks →nx.jsontargetDefaults→ project targets (inferred or explicit) → resolved target config
If a migrated target behaves unexpectedly, inspect the resolved config before you change targetDefaults. The cause is often a project-level setting or a plugin-inferred value taking precedence over the default.
+---------------------------+ +-------------------------------+
| turbo.json | | nx.json |
| tasks.build | ----> | targetDefaults.build |
| dependsOn, outputs, | name | dependsOn, outputs, cache |
| cache | match | |
+---------------------------+ +-------------------------------+
| app#build override | |
+---------------------------+ |
| | defaults applied
| moved to project v
| +-------------------------------+
+-------------------->| project target 'build' |
| inferred: package.json |
| scripts or plugins |
| explicit: project.json or |
| package.json nx field |
+-------------------------------+
|
| project config wins
| over targetDefaults
v
+-------------------------------+
| resolved target config |
| inspect this when debugging |
+-------------------------------+
Global turbo.json tasks become nx.json targetDefaults matched by name, while pkg#task overrides move into project config, which wins when Nx resolves each target.
How does Nx work once it replaces Turborepo?
Knowing what Nx does at run time makes the rest of the migration easier to reason about. Running a command such as nx run-many -t build goes through these stages:
- Build the project graph. Nx discovers projects from your workspace configuration,
package.jsonfiles,project.jsonfiles and any plugins. It then records the dependencies between them, using declaredpackage.jsondependencies and, for supported languages, source imports. This is the step that Turborepo's package discovery corresponds to. - Resolve targets. For each project, Nx merges inferred targets,
targetDefaultsand project-level configuration into one resolved target. This is the resolution chain shown above. - Build the task graph. Nx expands each requested target into tasks, one per project, and follows
dependsOnedges (^build, same-project targets, explicit project references) to order them. Independent tasks run in parallel. - Hash each task. Before running a task, Nx computes a hash from its declared inputs: matched files, declared environment variables, runtime commands, and the hashes of dependency tasks when
^inputs are used. - Check the cache. If the hash matches a stored entry in the local cache, or in a remote cache if you have configured one, Nx restores the declared outputs to disk and replays the terminal output instead of running the script. On a miss, it runs the script and stores the outputs under that hash.
The Nx daemon is a background process that keeps the project graph in memory and updates it as files change, so repeated commands don't recompute the graph from scratch. It is an extra moving part to account for when you debug. If the graph looks stale, restarting the daemon is a common first step.
The model is close to Turborepo's: both hash inputs, look up a cache and restore outputs. The practical differences are where configuration lives, how output paths resolve, and which inputs are hashed by default. The later sections cover each of these.
Should you migrate from Turborepo to Nx, and when should you stay?
Teams usually move for capabilities beyond task running. Turborepo can filter runs to changed packages, but in Nx the affected computation comes from the same project graph that drives plugins, generators and the daemon. Plugins infer targets from tool config files, so you maintain fewer hand-written pipeline entries. nx import brings other repositories in with their history, which matters when several repos are being consolidated. These benefits grow with scale. The best fit is a platform team running a large multi-language or multi-repo estate.
Who should use Nx
Nx is a good fit for these teams:
- Platform or developer-experience teams that own the build for many product teams and want one project graph to drive CI, code generation and dependency rules.
- Large workspaces with many projects, where hand-maintaining a pipeline entry for each tool becomes a burden and plugin-inferred targets remove that work.
- Teams consolidating repositories, who can use
nx importto keep history while they merge. - Workspaces mixing languages or toolchains, where plugins can infer targets from each tool's own config files.
- Teams that want generators to scaffold new libraries and apps consistently, instead of copying an existing package and editing it by hand.
When should you avoid migrating
If you only want a cached task runner and won't use the daemon, graph, plugins or generators, the migration adds operational surface area for no gain. Staying on Turborepo is a legitimate outcome. Avoid or postpone the migration in these cases:
- The repository is small and current CI times are acceptable. The parallel-run window and cold-cache period cost more than you will recover.
- Nobody can own the tooling. Nx plugins and the daemon need upgrades and occasional debugging. Without an owner, problems will surface as unexplained CI failures.
- You rely on Turborepo's environment filtering in strict mode as a correctness guardrail and aren't ready to build an equivalent check, because Nx generally passes the full environment through.
- You are in a release freeze or a period of heavy pipeline churn. The validation window depends on keeping both configs in sync, which is hard when task config changes every week.
- The motivation is only "Nx is faster." Both tools cache and parallelize. Without a specific gap, such as plugin inference, generators or repo consolidation, there is little to gain.
What are the alternatives
You have four realistic options:
| Option | What you get | What you take on |
|---|---|---|
| Keep Turborepo | Existing cache and pipelines | Nothing new |
| Package-manager workspace scripts | Minimal tooling | No caching or task graph |
nx init without plugins |
Nx caching and task running | Hand-written targets |
| Full Nx with plugins | Inferred targets, affected runs, generators | Daemon, plugin upgrades, graph debugging |
nx init without plugins is a useful middle step. You get Nx's task runner and cache on top of your existing scripts, validate them, and add plugins later, one tool at a time, once the baseline is trusted.
How can it save engineering time?
The time savings come from work that no longer happens, not from tasks running faster:
- Affected runs. CI builds and tests only the projects a change can reach through the project graph, so a change to one leaf library doesn't trigger the whole workspace.
- Cache hits. Tasks whose inputs haven't changed are restored instead of re-run, locally and in CI if a remote cache is shared.
- Less pipeline maintenance. Plugin-inferred targets read existing tool config files, so adding a project or changing a tool's output directory doesn't require a matching edit in a central pipeline file.
- Generators. Scaffolding new projects from a generator removes the manual setup and the inconsistencies that come from copying an existing package.
- Consolidation. Merging repositories with
nx importmeans fewer separate CI configurations and dependency upgrade cycles to maintain.
Turborepo already provides caching and filtered runs, so the savings relative to a working Turborepo setup come mainly from the last three items. Measure your own CI minutes and time spent on pipeline config before and after rather than assuming a gain.
What the migration costs
The cost is real. Caches start cold at cutover, so CI runs slower until they warm up. During the parallel-run window you also maintain two configurations.
Illustrative estimate, not a measured result. These inputs are assumed:
- 150 projects and about 600 cacheable tasks.
- 40 CI pipelines per day.
- 20 minutes per warm run and 45 minutes per cold run.
If half of the first day's runs miss the cache, that adds about 500 CI minutes. A two-week parallel window at roughly three engineer-hours per week for keeping both configs in sync adds about six hours of upkeep. Substitute your own numbers before you commit to a schedule.
Should you use nx init or nx import?
The choice depends on where the code lives today, not on how large the repo is.
nx init: adopt Nx in place
Run npx nx init from the root of your existing Turborepo repository. It adds Nx alongside your current package manager workspaces and leaves your package.json scripts where they are. Nx treats each workspace package as a project and each script as a runnable target, so nx run api:build calls the same build script that turbo run build calls today. Nothing moves and no history is rewritten. That property is what makes the parallel validation window possible: both tools read the same scripts, so a difference in output points to configuration, not to changed build logic.
nx import: consolidate repositories
nx import covers a different case. You already have an Nx workspace and want to bring in a separate repository with its git history intact. You run it from the destination workspace and give it the source repository and a target directory. It suits teams merging several Turborepo or polyrepo projects into one workspace, where losing git blame and commit history would be a real cost. It is not the right tool for converting a single Turborepo repo in place.
Check what Nx inferred
Both commands can prompt for choices, and their flags and plugin inference change between releases. Check the documentation for your installed Nx version rather than relying on remembered options. After either path, run nx show project <name> for a few representative packages. It shows the resolved targets, inputs, outputs, and dependencies, which is the baseline you compare against turbo.json in the next section.
cd ~/code/acme-monorepo
npx nx init # answer the prompts; package.json scripts stay where they are
npx turbo run build --filter=api
npx nx run api:build
cd ~/code/acme-nx-workspace
npx nx import ~/code/billing-service apps/billing-service
npx nx show project api # resolved targets, inputs, outputs, dependencies
npx nx show project api --json # machine-readable form, useful for diffing against turbo.json
npx nx --version
npx nx import --help
Basic invocations for adopting Nx in place with nx init, consolidating a separate repository with nx import, and inspecting the inferred project configuration with nx show project.
How do you translate dependsOn, outputs and cache settings?
dependsOn carries over almost unchanged, because both tools use the same convention. ^build means "run build in every dependency first," and a bare name such as codegen refers to a target in the same project. Copy those strings into targetDefaults in nx.json as they are. The one syntax that changes is Turborepo's package#task reference. In Nx it becomes an object with a projects array and a target field, for example projects: ["shared-config"] and target: "build". Root tasks written as //#task usually become a target on a root project, defined by a project.json or package.json at the workspace root.
Outputs need more attention. Turborepo resolves globs relative to the package, so dist/** already means "this package's dist." Nx resolves outputs from the workspace root, so the same output becomes {projectRoot}/dist. If an output path is missing or wrong, Nx still records a cache hit, but it restores nothing, and downstream targets fail or run against stale files. To check a target, run it once, delete its artifacts, run it again, and confirm that the files reappear on disk, not only that the log reports a cache hit.
cache: false maps directly to cache: false. Dev servers and watchers that Turborepo marks persistent also need to be non-cacheable. They carry a further risk: a target that never exits can block every target that depends on it. Nx support for continuous or long-running tasks has changed between releases, so check the docs for your Nx version before you rely on it. The before/after turbo.json and nx.json pair below shows each mapping.
// turbo.json (before)
{
"tasks": {
"build": {
// deps' build, same-package codegen, and one specific package's build
"dependsOn": ["^build", "codegen", "shared-config#build"],
"outputs": ["dist/**"] // relative to each package
},
"codegen": { "outputs": ["src/generated/**"] },
"dev": { "cache": false, "persistent": true },
"//#lint:root": { "cache": false } // root task
}
}
// nx.json (after)
{
"targetDefaults": {
"build": {
"dependsOn": [
"^build", // unchanged
"codegen", // unchanged
{ "projects": ["shared-config"], "target": "build" } // was pkg#task
],
"outputs": ["{projectRoot}/dist"], // tokens resolve from workspace root
"cache": true
},
"codegen": {
"outputs": ["{projectRoot}/src/generated"],
"cache": true
},
// Never exits: keep it out of the cache and out of other targets' dependsOn.
// Check your Nx version's docs for continuous-task support before relying on it.
"dev": { "cache": false }
}
}
// //#lint:root becomes a "lint:root" target in the root project.json,
// with "cache": false set on that target.
A before/after pair showing how turbo.json dependsOn strings, package#task references, package-relative output globs, cache: false, persistent tasks and a //#task root task map onto Nx targetDefaults and a root project target.
How do you map Turborepo inputs and environment hashing to Nx namedInputs?
Turborepo hashes a task's files under the package (minus gitignored files) unless you set inputs. When you do set it, $TURBO_DEFAULT$ adds that default set back so you can extend it. Nx has no placeholder. You define reusable namedInputs once in nx.json and reference them from targetDefaults.
A common setup uses two named inputs:
defaultcovers{projectRoot}/**/*plus shared globals.productionextendsdefaultwith negations such as!{projectRoot}/**/*.spec.ts, so editing a test doesn't invalidate a build.
The ^ prefix pulls dependency inputs into the hash. With ["production", "^production"], a build re-runs when an upstream library's source changes.
| Turborepo | Nx |
|---|---|
inputs with $TURBO_DEFAULT$ |
namedInputs.default |
globalDependencies |
{workspaceRoot}/path file inputs |
globalEnv, task env |
{ "env": "VAR" } inputs |
| Tool version in hash | { "runtime": "node --version" } |
Environment variables need the most care. Nx hashes only the variables you declare. An undeclared variable that changes output therefore gives you a wrong artifact served from cache. That is a correctness bug, not a cache miss.
Turborepo's strict mode can also filter which variables a task sees. Nx generally passes the whole environment through, so that guardrail is gone unless you add your own check.
Calibrate inputs in both directions:
- Too broad: inputs that include docs or lockfiles you don't consume cause constant misses.
- Too narrow: inputs that leave out files or variables the task reads cause stale hits.
Turborepo's defaults don't match Nx's default exactly, so don't assume parity.
Inferred targets from plugins add their own inputs. Run nx show project <name> to see the resolved inputs for each target. Compare them against the old turbo.json before you trust the cache.
cat > nx.json <<'EOF'
{
"namedInputs": {
"sharedGlobals": [
"{workspaceRoot}/tsconfig.base.json",
{ "runtime": "node --version" }
],
"default": ["{projectRoot}/**/*", "sharedGlobals"],
"production": [
"default",
"!{projectRoot}/**/*.spec.ts",
"!{projectRoot}/jest.config.ts"
]
},
"targetDefaults": {
"build": {
"cache": true,
"dependsOn": ["^build"],
"inputs": ["production", "^production", { "env": "API_URL" }]
},
"test": {
"cache": true,
"inputs": ["default", "^production"]
}
}
}
EOF
npx nx show project my-app --json | jq '.targets.build.inputs'
An nx.json that defines default and production namedInputs, maps globalDependencies, env and tool-version hashing to file, env and runtime inputs, and then uses nx show project to check the inputs Nx actually resolved for a build target.
How do you validate the migration by running both tools in parallel?
Keep turbo.json in place and run both tools side by side in CI for a fixed window, such as two weeks or a set number of merged PRs. Turborepo stays authoritative. Nx runs in a non-blocking job, and you compare the two on identical commits.
Compare the task graphs first
For each commit, export Turborepo's planned tasks with turbo run build --dry=json and Nx's plan with nx graph or nx show projects --affected. Diff the project and task lists:
- A task Nx runs that Turborepo skips usually points to an overly broad input or an extra
dependsOnedge. - A task Nx skips that Turborepo runs is the more dangerous case. It means Nx can't see a dependency, which leads to stale builds.
Then compare cache behavior
On the same commit, check which tasks each tool reports as cache hits. Every mismatch tells you something:
- A Nx miss where Turborepo hit suggests noisy inputs, such as an unfiltered environment variable or a generated file.
- A Nx hit where Turborepo missed suggests an input Nx isn't hashing.
Investigate both kinds before you trust the new config.
Freeze task config during the window
If someone edits turbo.json but not project.json or nx.json, the comparison stops meaning anything. You end up chasing differences you introduced yourself. Freeze pipeline changes during this period, or require every task-config PR to tick a checklist item confirming both files were updated.
Remove Turborepo only after the results match
Delete turbo.json once graphs and cache results agree across a representative spread of commits, including dependency bumps and changes to shared libraries. Fixing a missing input now is a config edit. Finding it after cutover usually means a production artifact built from stale cache, a cache purge, and hours of work to trace which hash was wrong.
Rewriting CI and cutting over the remote cache
With the inputs verified, CI is mostly a translation exercise. Replace each turbo run build --filter=...[origin/main] invocation with nx affected -t build --base=<base> --head=<head>. Replace unfiltered runs, such as nightly full builds, with nx run-many -t build. Pass several targets in one call, for example -t lint test build, so Nx schedules them together.
On pull requests, set base to the merge-base with the target branch and head to the PR commit. On main, set base to the last commit that passed CI, not HEAD~1. A failed run then cannot silently drop changes from the next comparison. Nx also reads these values from NX_BASE and NX_HEAD if you prefer environment variables.
The comparison runs git locally, so the checkout must contain both commits. Most CI systems clone shallowly by default. With a depth of 1, the base commit is missing, and the affected calculation either errors or falls back to treating everything as changed. Fetch full history, or fetch enough depth to reach the merge-base.
A generic step does four things in order:
- Check out with full history.
- Install dependencies from the lockfile.
- Resolve the base and head SHAs.
- Run
nx affectedwith both SHAs.
Turborepo artifacts are useless to Nx. The two tools compute hashes differently and store outputs in different formats. Expect cold builds after cutover until the cache warms. Budget extra runner capacity for that period, and tell teams before they notice slower CI.
Treat cache credentials as a security boundary. A poisoned entry is replayed into every build whose hash matches it, so it can spread with no visible source change. Give pull request jobs read-only credentials. Restrict write access to trusted branches running in protected CI.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to migrate turborepo to nx, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.