What is the Nx daemon and why does it speed up every nx command?

The Nx daemon is a long-lived background process that Nx starts the first time you run a command in a workspace. It holds the project graph in memory and watches the file system for changes. Without it, every nx invocation has to discover projects, read their configuration, and analyze source files to work out dependencies before it can do anything. With the daemon running, the CLI asks the daemon for the current graph. The daemon updates the graph incrementally from the file changes it has already seen, so it does not rebuild it from scratch on each command.

The time saved per command grows with the size of the workspace. A cold graph computation has to touch every project and the files that define their dependencies. An incremental update only reprocesses what changed since the last request. In a repo with a handful of services the difference is barely noticeable. In a workspace with hundreds of libraries, it is paid on every nx serve, nx test, or nx affected. Backend and platform engineers who run dozens of these commands an hour in a large monorepo benefit most.

You can inspect and control the daemon directly:

  • nx daemon reports whether the daemon is running and where its logs are.
  • nx daemon --start and nx daemon --stop start or stop it explicitly.
  • nx reset stops the daemon and clears cached state, which is the usual fix when the graph looks stale.
  • NX_DAEMON=false disables it for a single shell or command.
  • useDaemonProcess: false in nx.json disables it for the whole workspace.

In CI, Nx typically does not use the daemon. Each job runs once on a fresh machine, so a persistent process has no repeated commands to speed up.

# Check whether the daemon is running and where it writes its logs
npx nx daemon

# Start it explicitly (Nx also starts it on demand the first time you run a command)
npx nx daemon --start

# Compare graph-dependent commands with and without the daemon.
# Without the daemon, Nx computes the project graph from scratch on every call.
time NX_DAEMON=false npx nx show projects > /dev/null

# With the daemon, the CLI asks the background process for the in-memory graph.
# Run it twice: the first call may warm the daemon, the second reflects the steady state.
time npx nx show projects > /dev/null
time npx nx show projects > /dev/null

# Disable the daemon for one command, e.g. while debugging graph behavior
NX_DAEMON=false npx nx test orders-api

# Disable it for the rest of this shell session
export NX_DAEMON=false
unset NX_DAEMON   # turn it back on

# If the graph looks stale (a new project is missing, dependencies look wrong),
# stop the daemon and clear cached state, then let Nx rebuild everything
npx nx reset

# Stop the daemon explicitly, e.g. before switching to a large branch
npx nx daemon --stop

# To disable it for the whole workspace, set this in nx.json:
#   { "useDaemonProcess": false }

Shell commands to inspect, start, stop, reset, and disable the Nx daemon, plus a simple timing comparison of a graph-dependent command with and without it.

How does nx watch differ from a serve target's own restart-on-change?

That persistent process also maintains a file watcher, and that watcher is the link between the daemon and your local dev loop.

A serve target and nx watch both react to file changes, but they do different jobs. A serve target, such as one using the Node executor, exists to keep one service running. It rebuilds the service's build target and restarts the process when that code changes. Depending on the executor and its configuration, the build tool's own watcher may detect the change, or the executor may get file events from the daemon. Either way, the result is always the same action: rebuild and restart.

nx watch has no built-in action. It subscribes to the daemon's file events for the projects you select and runs whatever command you give it. That could be rebuilding a library, regenerating types, or running a linter. Because it gets its events from the daemon, nx watch cannot run without it. If you set NX_DAEMON=false or useDaemonProcess: false, the serve target can still restart through its build tool's watcher, but nx watch stops working.

File save → OS file events → Nx daemon (file watcher plus project graph) → serve target → rebuild and restart the API process → nx watch → run your command for the matching projects

Nodemon-style scripts skip Nx entirely. They watch paths, not projects, so they know nothing about project boundaries or the dependency graph.

Mechanism What it triggers Scope
Serve target restart Rebuild and restart of one service The service and, depending on the executor, its build dependencies
nx watch Any command you specify Selected projects, optionally including their dependencies
Nodemon-style script Restart of a single process Glob paths, with no awareness of the project graph
              +-------------------+
              |     File save     |
              +---------+---------+
                        |
                        v
              +-------------------+
              |  OS file events   |
              +---------+---------+
                        |
               +--------+-----------------------------+
               v                                      v
+-----------------------------+            +----------------------+
|          Nx daemon          |            | Nodemon-style script |
| file watcher + project graph|            | glob paths, no graph |
+------+---------------+------+            +----------+-----------+
       |               |                              |
       v               v                              v
+-------------+ +-------------+               +---------------+
| serve target| |  nx watch   |               | restart one   |
| Node exec.  | | selected    |               | process only  |
|             | | projects    |               |               |
+------+------+ +------+------+               +---------------+
       |               |
       v               v
+-------------+ +-------------+
| rebuild and | | run your    |
| restart API | | command     |
+-------------+ +-------------+

NX_DAEMON=false: nx watch stops; serve may use build tool watcher

File events reach the serve target and nx watch through the Nx daemon, while nodemon-style scripts watch glob paths directly and bypass Nx.

How do you scope nx watch and use NX_PROJECT_NAME and NX_FILE_CHANGES?

nx watch needs two things: a scope and a command. Use --projects=api,shared-db to name specific projects, or --all to watch the whole workspace. Add --includeDependentProjects to --projects and Nx also watches the projects your listed projects depend on, so --projects=api --includeDependentProjects picks up edits to the libraries api imports. Put the command after a bare --. Nx treats everything after it as the command and does not parse it as Nx flags.

On each change, Nx runs the command with two environment variables set. NX_PROJECT_NAME holds the affected project, and NX_FILE_CHANGES holds the changed file paths separated by spaces. Together they let one watcher rebuild only the project that changed.

The quoting pitfall

Your shell expands variables before Nx runs. If you write nx watch --all -- nx run $NX_PROJECT_NAME:build, the shell replaces $NX_PROJECT_NAME with an empty string when you start the watcher. Every trigger then runs a broken command. To keep the variable intact until each run, escape the dollar sign with nx watch --all -- nx run \$NX_PROJECT_NAME:build or wrap the command in single quotes: nx watch --all -- 'nx run $NX_PROJECT_NAME:build'.

Scope costs CPU

--all on a large graph means every saved file, including files in projects unrelated to your service, starts a process. Each run takes CPU and adds log output that can hide the rebuild you care about. Start narrow with --projects and add --includeDependentProjects only when you need it. Flags have changed between releases, so check nx watch --help against your installed version.

# Check the flags your installed Nx version supports before relying on them.
npx nx watch --help

# WRONG: double quotes or no quotes let your shell expand $NX_PROJECT_NAME
# once, when the watcher starts. The variable is unset at that moment, so
# every trigger runs `nx run :build`, which fails.
npx nx watch --projects=api -- nx run $NX_PROJECT_NAME:build
npx nx watch --projects=api -- "nx run $NX_PROJECT_NAME:build"

# RIGHT: escape the dollar sign so the literal text reaches Nx, which sets
# the variable for each run.
npx nx watch --projects=api -- nx run \$NX_PROJECT_NAME:build

# RIGHT: single quotes also stop the shell from expanding the variable.
npx nx watch --projects=api -- 'nx run $NX_PROJECT_NAME:build'

# Narrow scope: watch two named projects.
npx nx watch --projects=api,shared-db -- 'nx run $NX_PROJECT_NAME:build'

# Widen to related projects only when edits there should trigger a rebuild.
npx nx watch --projects=api --includeDependentProjects -- \
  'nx run $NX_PROJECT_NAME:build'

# Debug what triggered a run: print the project and the space-separated
# list of changed files.
npx nx watch --projects=api -- \
  'echo "changed in $NX_PROJECT_NAME: $NX_FILE_CHANGES"'

# Broadest scope. On a large graph every saved file in any project starts a
# process, which costs CPU and floods the log. Use sparingly.
npx nx watch --all -- 'nx run $NX_PROJECT_NAME:build'

Shows how to scope nx watch with --projects, --includeDependentProjects and --all, and compares quoting that breaks NX_PROJECT_NAME with an escaped $ or single quotes that delay expansion until each run.

Tutorial: rebuilding a shared library while nx serve runs your API

Assume an api service that imports shared-types, a buildable library whose build target writes compiled output to dist/. The service resolves the library from that output, so a source change in shared-types does nothing until the library is rebuilt.

Step 1: Make the first run build its inputs

Add "dependsOn": ["^build"] to the serve target of api. The ^ tells Nx to run build on every project api depends on before it starts serving. Without this, a fresh clone or a cleaned dist/ causes the service to fail at startup on a missing module. The rule also applies in CI, so the dependency is declared once instead of in a README step. With caching, unchanged libraries restore from cache, so the extra step adds little time after the first run.

Step 2: Run the watcher next to the server

In one terminal, run nx serve api. In a second, run nx watch --projects=shared-types -- nx run shared-types:build. The daemon reports changes in shared-types, the watcher rebuilds it, and new files land in dist/. The serve target's own file watcher sees those output files change and restarts the process. Each tool handles one job: Nx decides what to rebuild, and the server decides when to reload.

Step 3: Collapse it into one command

Two terminals are easy to forget. Define a dev target on api using nx:run-commands with parallel: true, and list both the serve command and the watch command. If several services need to run together, nx run-many -t serve --projects=api,worker starts their serve targets in parallel. Pair it with a single watcher scoped to the shared libraries.

{
  "name": "api",
  "projectType": "application",
  "sourceRoot": "apps/api/src",
  "targets": {
    "serve": {
      "executor": "@nx/js:node",
      "dependsOn": ["^build"],
      "options": {
        "buildTarget": "api:build"
      }
    },
    "dev": {
      "executor": "nx:run-commands",
      "options": {
        "parallel": true,
        "commands": [
          "nx serve api",
          "nx watch --projects=shared-types -- nx run shared-types:build"
        ]
      }
    }
  }
}

An apps/api/project.json in which serve builds upstream libraries such as shared-types first through dependsOn: ["^build"], and a dev target runs nx serve api and the shared-types watcher in parallel, so nx run api:dev replaces the two separate terminals.

How do you prevent rebuild loops and wasted CPU with .gitignore and .nxignore?

That pairing only stays efficient if the watcher sees source edits and nothing else. The Nx daemon's file watcher, which nx watch relies on, skips any path matched by .gitignore or .nxignore. Anything those files don't exclude counts as a change, including files your own tools write.

That is how rebuild loops start. Suppose a watcher on shared-utils runs its build, and the build writes to dist/libs/shared-utils. If dist isn't ignored, the daemon reports those output files as changes. The watcher fires again, and the API's serve target restarts a second time for the same edit. Add a second watcher whose command touches files in the first one's scope, and each rebuild triggers the other. CPU stays high and logs fill with restarts that nobody asked for.

At minimum, make sure these are ignored:

  • Build output: dist/, out/, build/, coverage/
  • Logs: *.log and any logs/ directory your services write to
  • Local databases: SQLite files such as *.db or *.sqlite, and data directories for containerized databases mounted inside the repo
  • Scratch space: tmp/ and .cache/

Put entries in .nxignore when Git should still track the files but Nx should not watch them, such as committed fixtures that a test run rewrites.

Ignore rules alone are not enough. Pass a narrow --projects list to every watcher so that no watcher's scope includes another watcher's output. Treat both measures as required parts of the setup.

Why aren't file changes triggering a rebuild, and how do you debug it?

Work through these checks in order. Each one rules out a whole layer.

  1. Confirm the daemon is running. nx watch receives file events from the daemon, so if the daemon is off, nothing gets delivered. Running nx daemon prints its status. Also check that neither NX_DAEMON=false in your shell nor a CI-style setting in nx.json has disabled it.
  2. Check whether the file is ignored. A path matched by .gitignore or .nxignore produces no event. The broad patterns you added to stop loops can easily cover a source directory too.
  3. Confirm project membership. Run nx show projects and verify that the changed file sits under a project root included in your --projects list. Files outside every project root, or in a project you didn't list, are skipped on purpose.
  4. Reset stale state. Branch switches, rebases, and edits to nx.json, plugin configuration, or the Nx version can leave the daemon with an outdated project graph. nx reset stops the daemon and clears its cache, and the next command rebuilds both.
  5. Compare with NX_DAEMON=false. nx watch itself won't run this way, but nx show projects and a one-off build will compute the graph fresh. If that output differs from what the daemon reports, the daemon's state is the problem.
  6. Check the OS. On Linux, a large repository can exhaust fs.inotify.max_user_watches. Once the limit is reached, new watches fail, sometimes with only a log line, so whole directories go quiet. Raise the limit with sysctl. Network filesystems, some Docker bind mounts, and VM-shared folders may deliver change events late or not at all. In those environments, run the watcher on the native filesystem where the files actually live.

When should you avoid the daemon and nx watch, and what are the alternatives?

The daemon is long-lived state, and that is the tradeoff. A plain CLI run computes the project graph, finishes, and leaves nothing behind. The daemon keeps a cached graph between runs, so a missed file event or a crashed process can leave Nx answering from a stale graph. nx reset clears the cache and stops the daemon, but you first have to notice the problem. In CI and in short-lived containers, the daemon has no time to pay off, so leave it off there.

Disabling the daemon, with NX_DAEMON=false or in nx.json, also disables nx watch, because the watcher runs inside the daemon. Neither tool fixes slow boot times. Restart-on-change is not hot reload. If your API runs migrations, warms caches, or builds a large DI container on startup, every restart pays that cost no matter how fast Nx rebuilds the library.

Approach What you gain What it costs
Buildable libraries + nx watch Cached, isolated library builds Daemon dependency, an extra build step
Source via TypeScript path mappings No library build; the serve target's own watcher sees changes Larger compile scope per restart, weaker boundaries
Ad-hoc watchers Works without the daemon No graph awareness; you maintain the scripts
Daemon disabled No stale state Every command recomputes the graph; no nx watch

Illustrative estimate, not a measurement: assume graph computation takes N = 2 seconds without the daemon and close to zero with it, and that you run M = 40 Nx commands per hour. The daemon would then save about 80 seconds per hour. Savings grow linearly with both N and M, so a small workspace or light usage may gain very little.

To get real numbers, run time nx show projects with the daemon on, then again with NX_DAEMON=false.

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 watch daemon, 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 .env by 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.