What are Nx continuous tasks and why does dependsOn need them?
An Nx target normally represents work that ends: a build, a lint run, a test suite. When one target lists another in dependsOn, Nx runs the dependency first and starts the dependent target only after the dependency exits successfully. That ordering is correct for build before test, but it breaks for dev servers, file watchers and local APIs. Those processes are supposed to run until you stop them. If your frontend's serve target depends on an API's serve target, the frontend would wait for an exit that never comes.
A continuous task is a target marked as long-running. When a target depends on a continuous task, Nx starts that dependency, keeps it running, and moves on without waiting for it to exit. The dependency edge stays in the task graph, so nx serve web can start the API and anything the API depends on.
Teams without this usually choose one of these workarounds:
| Approach | What you lose |
|---|---|
| Separate terminals | You have to remember the start order, and nothing records it |
Backgrounded shell commands (&) |
Output is mixed together, cleanup is manual, and dependencies are invisible to Nx |
run-many with high parallelism |
Everything starts at once, so the graph's ordering is ignored |
| Continuous tasks | Nx still derives order and scope from dependsOn |
Each workaround restates, by hand, dependency information that the project graph already contains. Backend and platform engineers feel this most because they maintain local stacks with several APIs, workers and proxies, where startup order matters.
The continuous property exists only in recent Nx versions. Check the documentation for the version you run before you rely on it.
How do you mark a target as continuous?
Take a two-project workspace: api is a backend with a long-running serve target, and web is a frontend whose dev server proxies requests to it. Mark the API target as continuous, then have the web target depend on it.
In apps/api/project.json, add "continuous": true to the serve target, next to its executor or command. In apps/web/project.json, give the serve target a dependsOn array that lists api:serve. You can also write that entry in object form, with projects set to ["api"] and target set to "serve".
If a project defines its targets in package.json, the same keys go under the nx field: nx.targets.serve.continuous set to true for the API, and nx.targets.serve.dependsOn containing api:serve for the web app. Nx merges both sources into one project configuration, so the scheduler treats them the same way.
The flag changes how Nx reads the dependency edge. A normal dependsOn entry means "run this to completion first." A continuous target never completes, so without the flag web:serve would never start. With the flag, Nx starts api:serve, does not wait for it to exit, and then starts web:serve. Running nx serve web brings up both processes from one command.
Stopping that command should stop both processes, so you don't leave an orphaned API holding its port. Signal handling and child-process cleanup can differ between Nx versions, so check the shutdown behavior against the documentation for the version you run.
# apps/api/project.json: the API dev server never exits, so mark it continuous
cat > apps/api/project.json <<'EOF'
{
"name": "api",
"targets": {
"serve": {
"command": "node apps/api/src/server.js",
"continuous": true
}
}
}
EOF
# apps/web/project.json: depend on api:serve.
# Nx starts api:serve, does not wait for it to exit, then starts web:serve.
cat > apps/web/project.json <<'EOF'
{
"name": "web",
"targets": {
"serve": {
"command": "vite --config apps/web/vite.config.ts",
"dependsOn": [{ "projects": ["api"], "target": "serve" }]
}
}
}
EOF
# Same keys under the package.json "nx" field, if a project uses that instead:
# apps/api/package.json: { "nx": { "targets": { "serve": { "continuous": true } } } }
# apps/web/package.json: { "nx": { "targets": { "serve": { "dependsOn": ["api:serve"] } } } }
# One command brings up both processes.
# Ctrl+C should stop both; verify shutdown behavior for your Nx version.
npx nx serve web
A continuous api:serve target and a web:serve target that depends on it, in project.json and package.json form, started together with nx serve web.
Why does 'started' not mean 'ready', and how do you handle it?
When a target depends on a continuous task, Nx launches the dependency and then moves on to the dependents. Nx only knows that it spawned a process. It has no view into whether that process has bound its port, finished running migrations, or warmed a connection pool. So "started" really means "the process exists." Your frontend dev server can be up and proxying requests while the API is still booting. The first few requests then fail with connection refused, or a dependent that connects eagerly at startup exits outright.
There are three ways to handle this, and they can be combined:
- Retry in the dev proxy. If the frontend's dev server proxies API calls, configure it to retry, or at least handle a failed upstream connection cleanly instead of surfacing a hard error. This addresses the symptom where developers actually see it, and it costs nothing once the API is up.
- Wait for readiness in the dependent's command. Before the dependent target starts its real process, its command polls the API's health endpoint until it gets a successful response, then hands off. This approach is deterministic. Put a timeout on the poll so that a broken API fails loudly instead of hanging forever.
- Tolerate late dependencies by design. Services that reconnect with backoff, rather than crashing on a failed first connection, are more robust locally and in production.
Readiness waits cost something. Every dependent blocks until the slowest health check passes, and that delay compounds across a deep task graph. To keep it small, use a short poll interval and make the health endpoint cheap to serve.
#!/usr/bin/env bash
# wait-for-api.sh: block until the API health endpoint responds, then exec the real command.
# Usage in the dependent target's command:
# ./tools/wait-for-api.sh -- npx vite
set -euo pipefail
URL="$1"; shift
[ "${1:-}" = "--" ] && shift
TIMEOUT_SECONDS="${WAIT_TIMEOUT:-60}" # fail loudly instead of hanging forever
INTERVAL_SECONDS="${WAIT_INTERVAL:-0.5}" # short interval keeps added startup latency small
SECONDS=0
# --fail treats HTTP 4xx/5xx as failure, so a booting API that answers 503 keeps us waiting.
# --max-time bounds each probe so one stuck request cannot eat the whole budget.
until curl --silent --fail --output /dev/null --max-time 2 "$URL"; do
if (( SECONDS >= TIMEOUT_SECONDS )); then
echo "wait-for-api: $URL not ready after ${TIMEOUT_SECONDS}s" >&2
exit 1
fi
sleep "$INTERVAL_SECONDS"
done
echo "wait-for-api: $URL is ready after ${SECONDS}s" >&2
# exec replaces this shell so signals from Nx reach the dev server directly.
exec "$@"
A readiness wait for a dependent target's command: it polls the API's health endpoint with a short interval and a hard timeout, then execs the real dev server.
How does Nx compose a full local stack of continuous and discrete tasks?
Consider a typical stack: web:serve depends on api:serve, and api:serve depends on auth-mock:serve and db:up, a target that starts a local database container. All four are marked continuous. When you run nx serve web, Nx walks the graph from the bottom. It starts the database and the mock auth service, then the API, then the web dev server. One command brings up the whole stack, and stopping it tears everything down together.
Nx identifies each task by project and target, so a dependency that several apps share appears in the task graph only once. If you serve web and admin together and both depend on api:serve, Nx starts one API process and both frontends use it. This matters for continuous tasks in a way it doesn't for builds. Two API instances would compete for the same port, and two database containers would compete for the same volume.
A single dependsOn list can also mix the two kinds of task, and Nx handles each kind differently:
api:serve(continuous)shared-lib:codegen: discrete, so Nx blocks until it exits successfullyshared-lib:watch: continuous, so Nx waits only for it to startdb:up: continuous, so Nx waits only for it to start
The rule follows from what each kind of task produces. Codegen produces files that the API needs before it can compile, so the API has to wait for it to finish. A watcher never finishes, so the API can only wait for it to start. Any readiness check beyond that is the job of the health-check approach covered earlier.
{
"name": "api",
"targets": {
"serve": {
"continuous": true,
"executor": "nx:run-commands",
"options": {
"command": "node --watch src/main.js",
"cwd": "apps/api"
},
"dependsOn": [
{ "projects": ["shared-lib"], "target": "codegen" },
{ "projects": ["shared-lib"], "target": "watch" },
{ "projects": ["auth-mock"], "target": "serve" },
{ "projects": ["db"], "target": "up" }
]
}
}
}
An api project.json whose continuous serve target mixes kinds in dependsOn: Nx blocks on the discrete shared-lib:codegen until it exits, and only waits for the continuous watch, auth-mock:serve and db:up tasks to start.
Wrapping non-Node services, caching rules and CI safety
Any process Nx supervises as a continuous task must stay in the foreground until it is told to stop. For containers, that means running docker compose up without -d. Detached mode returns immediately, so Nx records the task as done while the containers keep running outside its control. Go and Python servers, and message broker emulators, follow the same rule. Wrap each one in an nx:run-commands target or a plain package.json script, and mark the target continuous.
The process also has to exit cleanly on SIGINT and SIGTERM, because those signals are how Nx shuts the stack down. Wrapper shells cause most failures here. A command run through sh -c makes the shell the parent process, and if the shell does not forward the signal, the child survives as an orphan and keeps its port. On the next run, the new process fails with "address already in use". You can avoid this by using exec inside the shell command so the server replaces the shell. For Go, run a built binary rather than go run, which starts the binary as a separate child process.
In targetDefaults, set cache: false on every serve target. A cached "success" for a server that never exits has no meaning. Keep build and serve as separate targets, so that builds stay cacheable and serve targets only start processes.
In CI, a serve target that gets picked up by run-many or affected will run until the job times out. Pass explicit target lists such as build, test and lint, and do not use broad patterns. Serve targets should start in CI only when an e2e target declares them in dependsOn.
// apps/orders-api/project.json (Nx accepts comments in project.json)
{
"name": "orders-api",
"targets": {
// Cacheable build, kept separate from serve so it never starts a process.
"build": {
"executor": "nx:run-commands",
"cache": true,
"outputs": ["{projectRoot}/dist"],
"options": { "cwd": "apps/orders-api", "command": "go build -o dist/orders-api ./cmd/server" }
},
// Foreground compose (no -d). exec replaces the shell so SIGINT/SIGTERM reach compose directly.
"serve-deps": {
"executor": "nx:run-commands",
"continuous": true,
"cache": false,
"options": { "cwd": "apps/orders-api", "command": "exec docker compose up postgres pubsub-emulator" }
},
// Run the built binary, not `go run`, so no extra child process can be orphaned holding :8080.
"serve": {
"executor": "nx:run-commands",
"continuous": true,
"cache": false,
"dependsOn": ["build", "serve-deps"],
"options": { "cwd": "apps/orders-api", "command": "exec ./dist/orders-api --port 8080" }
},
// The only way serve starts in CI: an e2e target that depends on it.
// CI runs `nx affected -t build test lint` and `nx run orders-api:e2e` explicitly,
// never a pattern that would also match serve.
"e2e": {
"executor": "nx:run-commands",
"cache": false,
"dependsOn": ["serve"],
"options": { "cwd": "apps/orders-api", "command": "go test ./e2e/..." }
}
}
}
A Go service wired as Nx targets. The build target is cacheable. The serve-deps and serve targets are continuous and uncached, use exec so the process stays in the foreground and receives signals directly, and are started only through an e2e target's dependsOn.
When should you avoid Nx continuous tasks, and what are the alternatives?
Continuous dependencies are convenient, but they make the full stack the default. A frontend engineer who runs serve on the web app also starts the API, the worker and anything those depend on, even when a shared staging backend would do. That coupling is hidden in project.json and only shows up as a slow start or a hot laptop. Heavy services such as containers or JVM runtimes make this worse. Nx schedules processes, not memory or CPU, so it will start everything the graph asks for regardless of what the machine can handle.
Observability also suffers. Logs from several long-running processes are interleaved in one terminal, and a dependency that crashes early can scroll out of view while the dev server keeps running against a dead backend.
| Approach | Dependency awareness | Shutdown | Networking | Environment parity |
|---|---|---|---|---|
| Nx continuous tasks | Project graph | Stops with the parent task | Host ports | Host runtime |
| Separate terminals | None, manual order | Manual, per terminal | Host ports | Host runtime |
| Backgrounded shell scripts | Whatever you script | Easy to leak orphans | Host ports | Host runtime |
nx run-many --parallel |
None between serve targets | Stops with the command | Host ports | Host runtime |
| Docker Compose | depends_on, health checks |
docker compose down |
Isolated network, DNS by service name | Close to production images |
Compose orchestrates infrastructure. Nx orchestrates workspace processes. They work well together: give stateful services such as databases and queues an Nx target that invokes Compose, and let application dev servers run natively with fast reloads and depend on that target.
How can continuous tasks save engineering time day to day?
Most of the daily benefit comes from how you read and steer output, not from the task graph itself. With several continuous tasks running, logs interleave. Nx prefixes each line with the project and target name, so search or filter on that prefix instead of scrolling. Newer Nx versions include a terminal UI that gives each task its own pane, which you can focus while the others keep running. If your version lacks it, or you are piping output to a file, use the output-style options your version documents. When one service is noisy, run it in its own terminal and leave the rest to the composed target.
Define two entry points per app. Keep the full-stack target for work that touches the API and database. Also add an escape-hatch target or configuration that serves the frontend alone against a remote or staging backend, with no dependsOn. UI-only changes then skip local infrastructure entirely, and a broken local database cannot block you.
Be honest about the cost. One command replaces hand-maintained startup scripts and the "which terminal runs what" ritual. You pay some of that time back on readiness waits and per-task startup overhead.
Illustrative estimate (assumed numbers, not a benchmark). Daily savings = restarts × (manual setup time − (readiness wait + overhead)). Assume 4 restarts a day, 3 minutes of manual setup, a 40-second readiness wait, and 20 seconds of overhead: 4 × (180 − 60) = 480 seconds, or about 8 minutes per developer per day. If your readiness wait approaches your manual setup time, the savings disappear.
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.