What are Nx continuous tasks and how do they differ from regular tasks?
A regular Nx task is expected to finish. A build compiles and exits, a lint run reports and exits, and Nx treats that exit as the signal that the task's outputs are ready. A continuous task is a target that is expected to keep running until you stop it, such as a dev server, a file watcher, or a mock API. It has no natural "done" moment.
That difference changes how dependents are scheduled. If target A depends on a regular target B, Nx waits for B to exit successfully before starting A. Applying that rule to a dev server would mean waiting for something that never finishes. When B is marked continuous, Nx starts B and then starts A alongside it, and keeps B running while A runs. This lets one command bring up a frontend together with the API it calls, or start an e2e suite against a live server.
| Aspect | Regular task | Continuous task |
|---|---|---|
| Expected lifetime | Runs, then exits | Runs until stopped |
| Dependents start | After it exits successfully | Alongside it |
| Typical examples | build, lint, test | serve, watch, mock services |
This matters most to backend and platform engineers who run multi-service local dev workflows, maintain e2e suites, or own long running targets that other projects depend on.
Behaviour and configuration differ between Nx versions and plugins. Check the documentation for the version you run. Do not assume that every executor or inferred target supports continuous semantics in the same way.
Who should use Nx continuous tasks?
Continuous tasks fit teams whose local or test workflow needs more than one long-running process at the same time, and who already use Nx to describe how projects depend on each other.
- Application engineers working on a frontend that calls one or more APIs. Instead of opening a terminal per service, they run one
servecommand and get the API and its compiled libraries along with it. - Engineers who own e2e suites. The e2e target can declare the server it needs, so the suite runs against a server that Nx started, deduplicated, and will stop.
- Platform and developer-experience engineers who maintain the scripts that start local stacks. Continuous tasks let them replace a hand-written concurrency script with dependency definitions that live next to each project's other targets.
- Teams that want local runs to match CI. When CI and laptops run the same
nx e2eornx servecommand, the same graph decides what starts and in what order.
They are a weaker fit for a single app with no backing services, where nx serve already does everything needed, and for very large graphs where serving one app would fan out into many services. The section on when to avoid continuous tasks covers that trade-off.
How do continuous tasks work?
Nx builds a task graph for every command. Each node is a task ID such as api:serve or shared-types:build, and each edge comes from a dependsOn entry, after targetDefaults and inferred targets are merged in. Marking a target with continuous: true changes what an edge pointing at that task means to the scheduler.
- Graph construction. Nx resolves
dependsOnfor the requested target.^buildexpands to thebuildtarget of every project the current project depends on. Object entries withprojectsandtargetadd explicit edges. A task ID appears once in the graph, so if two dependents both needapi:serve, there is oneapi:serveprocess, not two. - Finite dependencies run first. Tasks without the continuous flag are scheduled as usual: dependencies before dependents, independent tasks in parallel, cached results restored where caching is enabled. A dependent does not start until all of its finite dependencies have exited successfully.
- Continuous dependencies are launched, not awaited. When the scheduler reaches a continuous task, it spawns the process and treats that edge as satisfied right away. Tasks that depend on it can start in the same run while it keeps running.
- Lifetime is tied to the dependents. A continuous dependency keeps running while the tasks that need it run. When those dependents finish, as an e2e suite does, Nx stops the continuous tasks it started. When the dependent is itself continuous, as with
web:serve, everything runs until you stop the command. - Readiness is not part of the contract. "Satisfied" means "spawned", not "listening on its port". The dependent has to wait for readiness itself, as described in the readiness section below.
The flag belongs on the target that is depended on. A dependent that waits on a target without the flag waits for it to exit, which for a server means forever.
How do you mark a target as continuous and wire nx serve dependencies?
Take three projects: web (frontend), api (backend), and shared-types (a library both consume). Running nx serve web should give you a working stack: the library compiled, the API listening, and the frontend dev server up.
On api, the serve target gets continuous: true and a dependsOn entry for ^build. That entry means "run build on the projects I depend on first," which covers shared-types. On web, the serve target also gets continuous: true, plus a dependsOn entry that names the api project's serve target explicitly, using the object form with projects and target. An explicit reference is needed because the frontend usually has no import-level dependency on the API, so ^ would not find it.
The resulting graph mixes both kinds of task. shared-types:build is finite: it must exit successfully before api:serve starts, because the API needs compiled output. api:serve and web:serve are continuous. Nx starts them and keeps them running alongside each other without waiting for either to exit. The continuous flag sits on the target being depended on. A dependsOn reference to a non-continuous target would block forever on a server that never exits.
Set cache: false on both serve targets, or confirm your executor or plugin already disables it. A dev server produces no artifact and no exit status that could be stored and reused. Restoring a "successful" serve from cache would print old logs and start nothing. Keep caching on shared-types:build, where reuse is the point.
// apps/api/project.json
{
"name": "api",
"targets": {
"serve": {
"executor": "nx:run-commands",
"options": { "command": "node --watch src/main.js", "cwd": "apps/api" },
// Long-running: Nx starts it and does not wait for it to exit
"continuous": true,
// A dev server has no reusable output, so never cache or replay it
"cache": false,
// Finite dependency: build shared-types (and any other deps) first, wait for success
"dependsOn": ["^build"]
}
}
}
// apps/web/project.json
{
"name": "web",
"targets": {
"serve": {
"executor": "nx:run-commands",
"options": { "command": "npm run dev", "cwd": "apps/web" },
"continuous": true,
"cache": false,
// web does not import api, so '^' cannot find it; reference it explicitly.
// api:serve is continuous, so Nx runs it alongside web:serve instead of blocking.
"dependsOn": [
{ "projects": ["api"], "target": "serve" }
]
}
}
}
// libs/shared-types/project.json: build stays a normal, cacheable one-shot task
// "build": { "executor": "nx:run-commands", "cache": true,
// "outputs": ["{workspaceRoot}/dist/libs/shared-types"], ... }
Configuration for the api and web serve targets, which run nx serve web as a mixed graph: the finite shared-types:build runs first, then the continuous api:serve and web:serve run side by side with caching disabled. Nx accepts // comments in project.json, but strict JSON parsers do not.
How does Nx order finite and continuous work in the task graph?
Nx splits the dependency edges of a task into two kinds and treats each kind differently. A finite dependency has to exit successfully before anything that depends on it can start. A continuous dependency only has to be launched. Nx starts the process and then moves on, because a dev server never exits and waiting for it would block the run forever.
Running nx serve frontend against the shared library shared-types, a backend api, and the frontend app produces this graph:
frontend:serve
├── api:serve (continuous: started, not awaited)
│ └── shared-types:build (finite: must exit 0)
└── shared-types:build (finite: must exit 0, runs once)
The two edges into shared-types:build both block. Nx runs that build once, or restores it from cache, before either server starts, so both servers see the same compiled output. The edge from frontend:serve to api:serve does not block. Nx launches the API and then starts the frontend almost immediately, and from then on both processes run side by side. If a finite build fails, Nx starts neither server. If the API crashes later, the frontend keeps running.
Don't rely on reading project.json to work out this ordering. Run nx serve frontend --graph to open the task graph for that exact invocation, or use --graph=tasks.json to write it to a file you can diff in review. The task graph shows the real task IDs and their dependencies after target defaults and inferred targets are merged in. That merged result is where surprises tend to show up, such as a codegen step you didn't know was there or a missing build edge.
nx serve frontend --graph
nx serve frontend --graph=tasks.json
grep -c '"shared-types:build"' tasks.json
cp tasks.json tasks.before.json
nx serve frontend --graph=tasks.json
git diff --no-index tasks.before.json tasks.json
Shows how to inspect the resolved task graph for nx serve frontend in the browser or as a JSON file, and how to diff it after a config change so the finite and continuous edges can be verified directly.
Why doesn't Nx know when a service is ready, and how do you handle it?
When Nx launches a continuous task, it considers that dependency satisfied once the process has been spawned. It doesn't check whether the process has bound a port, finished its first compile, run migrations, or connected to a database. A dependent task can start while the API is still building, so its first requests reach a port with nothing listening on it.
This causes two common failures. Locally, the frontend dev server loads and its first few API calls fail with connection refused, which looks like a bug and isn't one. In e2e runs, the test runner sends its first request before the backend is listening, and the suite fails on whichever spec runs first. These failures are timing-dependent. They pass on a fast laptop with a warm cache and fail on a cold CI runner.
Because Nx won't handle readiness for you, the consumer has to. The task that depends on a service is the right place for that logic.
- Retrying clients. HTTP clients and database drivers that retry with backoff on connection errors absorb startup delay without any orchestration. Many database drivers already do this.
- Wait steps in the dependent's script. Before starting the e2e runner, poll a health endpoint until it responds, and give up after a fixed timeout. With standard shell tools, that means a loop that calls
curl -sfagainst the health URL, sleeps a second between attempts, and exits non-zero after a set number of tries. Exiting with an error makes a backend that never comes up fail fast in CI instead of hanging. - Tolerant dev proxies. Configure the frontend's dev proxy to return a clear error or retry while the backend is starting, rather than surfacing raw socket errors in the browser.
#!/usr/bin/env bash
set -euo pipefail
HEALTH_URL="${HEALTH_URL:?Set HEALTH_URL to the API health endpoint}"
MAX_ATTEMPTS="${MAX_ATTEMPTS:-60}" # roughly 60 seconds at 1s per attempt
attempt=1
until curl -sf --max-time 2 "$HEALTH_URL" > /dev/null; do
if [ "$attempt" -ge "$MAX_ATTEMPTS" ]; then
# Fail fast with a clear message instead of letting the first spec fail.
echo "API not ready at $HEALTH_URL after $MAX_ATTEMPTS attempts" >&2
exit 1
fi
echo "Waiting for API ($attempt/$MAX_ATTEMPTS)..."
attempt=$((attempt + 1))
sleep 1
done
echo "API is ready at $HEALTH_URL"
A tool-agnostic shell script for the e2e task that polls the API health endpoint with curl, sleeps between attempts, and exits non-zero after a fixed number of tries so a backend that never starts fails fast.
When should you use continuous dependencies for e2e tests and local backing services?
The strongest case for continuous dependencies is the e2e target. Give app-e2e:e2e a dependsOn entry pointing at app:serve, mark serve as continuous, and one command builds what serve needs, starts the server, runs the suite, and stops the server when the tests finish. The alternative is to have the test runner start its own server through a web-server block in its config or an executor option naming a dev server target. That keeps working, but the runner then owns a process that Nx can't see. Nx can't deduplicate it if another task already started the same server, and it can't show it in the task graph.
CI adds three requirements:
- Readiness. Nx only knows when a process started, not when it's ready, so the test side has to poll a health endpoint before running specs.
- Timeouts. That poll needs its own deadline, well below the job limit, so a server that never binds fails in seconds rather than at the CI-level timeout.
- Teardown. Nx stops continuous dependencies once their dependents finish, but the server still has to exit promptly on SIGTERM. Watchers and child processes that ignore the signal will keep the job open.
You can model a database container, message broker, or mock server the same way, as a continuous target that wraps a container run. This puts infrastructure in the same graph as application code, so nx e2e brings up everything it needs. The costs are real, though:
- Local topology becomes coupled to the build graph.
- Container settings often get duplicated between project config and compose files.
- Local setup can quietly diverge from how CI or staging provisions the same services.
// apps/app/project.json (excerpt)
{
"targets": {
"serve": {
// Long-running: Nx starts it and does not wait for it to exit
"continuous": true,
"executor": "nx:run-commands",
"options": { "command": "node dist/apps/app/main.js" }
},
"db": {
// Backing service in the same graph. --rm cleans up the container on stop
"continuous": true,
"executor": "nx:run-commands",
"options": {
"command": "docker run --rm --name app-e2e-db -p 5432:5432 -e POSTGRES_PASSWORD=example-only postgres:16"
}
}
}
}
// apps/app-e2e/project.json (excerpt)
{
"targets": {
"e2e": {
// One command brings up db + serve, runs the suite, then Nx stops both
"dependsOn": [
{ "projects": ["app"], "target": "db" },
{ "projects": ["app"], "target": "serve" }
],
"executor": "nx:run-commands",
"options": {
// Nx only knows the server started, not that it is ready.
// Poll health with a 60s deadline so a server that never binds
// fails fast instead of at the CI job timeout.
// HEALTH_URL must be set to the app's health endpoint.
"command": "npx wait-on --timeout 60000 \"$HEALTH_URL\" && npx playwright test"
}
}
}
}
An e2e target that depends on continuous serve and db targets, with a bounded readiness poll before tests run.
How can continuous tasks save engineering time?
The time savings come from removing manual steps and failure modes that recur every day, not from making any single process faster.
- Fewer manual startup steps. One command replaces opening several terminals, remembering the order to start them in, and rebuilding shared libraries by hand before starting a server. New team members don't need a written runbook to bring up a working stack.
- Correct ordering by construction. Because finite builds must succeed before continuous servers start, nobody spends time debugging a server that started against stale or missing compiled output.
- Cached prerequisites.
shared-types:buildand similar finite dependencies still use the Nx cache, so repeat runs restore their outputs instead of rebuilding when inputs haven't changed. - No duplicate servers. A server needed by several dependents runs once, which avoids port collisions and the time spent tracking them down.
- Automatic teardown in e2e runs. Nx stops the continuous dependencies when the suite finishes, which cuts down on orphaned processes holding ports, as long as each process handles termination signals.
- One definition for local and CI. The startup logic lives in project configuration rather than in a shell script plus a separate CI script, so there is one place to update when a service is added or renamed.
Illustrative estimate (all inputs assumed, not measured): assume a team of 8 engineers, each starting a local stack of three services twice a day. Assume manual startup in separate terminals, including rebuilding a shared library and occasionally fixing a wrong start order, takes about 3 minutes per start, and the single continuous-task command takes about 1 minute of attention. That is 2 minutes saved × 2 starts × 8 engineers = 32 minutes per working day across the team. Add an assumed one hour per week spent investigating stray processes or ordering bugs, and the assumed total is roughly 3.5 to 4 hours per week. Replace these assumed inputs with your own observations. Teams with one service and a fast startup will see little difference, and teams whose graphs fan out into many services may lose time to slower full restarts, as the next section explains.
When should you avoid continuous tasks, and what are the alternatives?
Continuous dependencies have runtime costs that only show up once a graph grows. Serving one app can fan out into every API, worker and emulator it transitively depends on. On a laptop, each one takes memory, CPU and startup time, even when you are only changing a single frontend route. Restarting one crashed or edited service usually means stopping the whole parent command and starting everything again. Output from several processes shares one stream, so when startup fails you have to work out which service produced the stack trace. Teardown also depends on every child handling termination signals. A server that ignores them can keep holding its port after the parent exits.
| Approach | Setup effort | Restart ergonomics | Log clarity | Teardown reliability | CI parity |
|---|---|---|---|---|---|
| Continuous tasks | Low once targets exist | Restart everything | Interleaved | Depends on children | High (same graph) |
| Separate terminals | None | Per service | Isolated | Manual | Low |
| Compose-style, started once | Moderate | Per service | Per container | Good | Medium to high |
| Scripts / ad-hoc parallel runners | Moderate, drifts | Varies | Usually interleaved | Often fragile | Low |
Use continuous tasks when the dependency set is small and stable and you want one command that matches CI. If the backing services rarely change, such as databases and queues, start them once with a compose-style workflow so they outlive individual dev sessions. A practical hybrid is to run stable dependencies through continuous tasks or compose, and run the service you are actively editing in its own terminal. That gives you fast restarts and readable logs where you need them most.
How do you write well-behaved long running targets and migrate to them?
Whichever processes Nx ends up orchestrating, each one should behave the same way under supervision as it does in a terminal.
Rules for targets under orchestration
- Read the port from an environment variable and fall back to a default. Two worktrees or an e2e run alongside a dev session will otherwise collide, and a hardcoded port forces someone to edit code to work around it.
- Keep logs line-oriented and identifiable. Interleaved output is only useful if each line says which service wrote it. Avoid progress bars and screen-clearing output, because both turn into noise when they are mixed with other streams.
- Never prompt when stdin is not a TTY. A "port in use, try another?" question waits forever with no one able to answer. Fail fast with a clear message instead.
- Handle SIGINT and SIGTERM. Stop the subprocesses you spawned, such as watchers and compilers, before exiting. If you skip this, Ctrl-C ends the parent and the children keep running and holding ports.
When a port stays occupied after shutdown, lsof -i :PORT or ss -ltnp shows the PID that owns it. Send that process a plain kill before you try kill -9, so it gets a chance to clean up.
Migration checklist
- Record which processes your current concurrency script starts, using
psor the listening ports fromss -ltn. - Mark long-running targets as continuous and add them as dependencies.
- Inspect the task graph with
nx graph. - Run the new command and compare the process list and listening ports against step 1.
- Press Ctrl-C and confirm that nothing is left listening.
- Delete the old script.
The payoff is qualitative but real. There is one dependency definition instead of a script that drifts out of date, and engineers spend fewer stray minutes hunting for zombie processes.
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 nx continuous tasks, 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.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
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.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- 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.