Where does ESLint time actually go in an Nx monorepo?
This guide is for backend and platform engineers who own CI time in multi-project Nx workspaces. Before changing configuration, find out where lint time is actually spent.
Start with rule cost. Running ESLint with the environment variable TIMING=1 prints the slowest rules for that run. If type-aware rules such as those from typescript-eslint top the list, part of what you see is the cost of building a TypeScript program, not only the rule logic.
Next, time a single project's target (nx run my-api:lint) and compare it with nx run-many -t lint across the workspace. If the sum of per-project times roughly matches the total, the cost is per-project work. If the total is much larger, look at orchestration: parallelism limits, process startup, and repeated config loading.
In most workspaces, two costs dominate. The first is re-linting projects that haven't changed. The second is rebuilding a TypeScript program for each project that uses typed rules.
Illustrative estimate (assumed numbers, not a benchmark):
lint time ≈ projects linted × (program build + rule execution)
Assume 40 projects, 8 s per program build, and 4 s of rule execution: 40 × (8 + 4) = 480 s. If only 5 projects changed, the same run takes 5 × 12 = 60 s.
Measure cold runs as well, using --skip-nx-cache. Warm-cache timings look good but hide growth in your worst case: a full rebuild after a config change or cache eviction.
#!/usr/bin/env bash
# Baseline lint measurements for an Nx workspace before changing any config.
# Project names and paths are placeholders; substitute your own.
set -euo pipefail
PROJECT=my-api
PROJECT_DIR=apps/my-api
# 1. Rule cost: run ESLint directly so TIMING output is printed.
# If typed rules lead the list, part of that time is building the
# TypeScript program, not only the rule logic.
echo "== Slowest rules in $PROJECT =="
TIMING=1 npx eslint "$PROJECT_DIR" > /dev/null || true
# 2. Per-project cost, cold: bypass the Nx cache so ESLint actually runs.
echo "== Single project, cold =="
time npx nx run "$PROJECT:lint" --skip-nx-cache
# 3. Whole workspace, cold: this is the worst case CI hits after a config
# change or cache eviction. Compare it with the sum of per-project times;
# a much larger total points at orchestration overhead.
echo "== All projects, cold =="
time npx nx run-many -t lint --skip-nx-cache
# 4. Whole workspace, warm: run again with the cache enabled.
# Cache hits make this fast, which is why it should never be your only number.
echo "== All projects, warm =="
time npx nx run-many -t lint
A shell script that captures ESLint rule timings for one project, then measures cold and warm lint runs for that project and the whole workspace, so per-project cost, orchestration overhead and worst-case CI time can be compared.
How does Nx computation caching work for lint targets?
Nx treats lint like any other target: before running it, Nx computes a hash of everything the target declares as input, then asks the cache whether it has seen that hash before. For a lint target, the hash usually covers:
- the project's source files
- the project's ESLint config
- the root ESLint config
- the relevant tsconfig files
- the inputs of upstream projects, through
^-prefixed named inputs - the target's command and options
ESLint writes no build artifacts, so a cache hit replays the stored terminal output and exit code. The result looks exactly like a real run.
The decision flow
changed files → project graph (which projects are affected?) → hash declared inputs per lint target → local cache lookup → remote cache lookup on a local miss → hit: replay output and exit code / miss: run ESLint → ESLint's own
--cacheskips unchanged files inside that project → store the result under the hash
The two caches work at different levels. Nx decides whether a project lints at all. When a project does run, ESLint's file-level cache saves work on the files that did not change.
The trade-off: incomplete inputs
The cache is only as correct as its inputs. If the root config, a plugin version, or a dependency's type declarations are missing from the hash, changing them leaves the hash the same. Nx then replays an old "pass", and real violations stay hidden. Typed rules carry the most risk here. A type change in an upstream library can break no-unsafe-* checks in projects whose own files never changed.
Under-declared inputs fail silently. Over-declared inputs only cost cache misses. When in doubt, include the input.
changed files
v
+---------------------------------------------+
| Project graph: which projects are affected? |
+---------------------------------------------+
| one lint target per affected project
v
+----------------------------+ +--------------------------------+
| Hash declared inputs: | | NOT in declared inputs? |
| - project source files |<--X-| root config, plugin version, |
| - project ESLint config | | upstream type declarations |
| - root ESLint config | | -> change keeps the SAME hash |
| - relevant tsconfig files | | -> stale 'pass' is replayed, |
| - ^ upstream inputs | | real violations stay hidden |
| - command + options | +--------------------------------+
+----------------------------+
v
+--------------+ miss +---------------+
| local cache |------->| remote cache |
+--------------+ +---------------+
| hit | hit | miss
v v v
+------------------------------+ +------------------------------+
| REPLAY stored output and | | RUN ESLint on this project |
| exit code (looks identical | | --cache skips files that are |
| to a real run) | | unchanged inside the project |
+------------------------------+ +------------------------------+
v
store output + exit code under hash
Nx hashes each affected lint target's declared inputs and checks the local cache, then the remote cache, either replaying the stored output and exit code or running ESLint, whose own --cache skips unchanged files; anything left out of the inputs keeps the hash the same and replays a stale pass.
How do you configure cacheable lint targets and named inputs in nx.json?
Start with targetDefaults in nx.json. Set cache: true on the lint target so every project inherits it, rather than repeating the setting in each project.json. Then define a named input, for example lintInputs, that lists everything ESLint's result depends on beyond the project's own source:
- The root
eslint.config.*file. - Any shared config packages.
- The relevant
tsconfigfiles, at leasttsconfig.base.jsonand the project's owntsconfig*.json, because path aliases and compiler options change how typed rules resolve symbols. - An
externalDependenciesentry foreslint, the TypeScript parser and your rule plugins. With this entry, bumping a plugin version invalidates cached results. Otherwise you would keep replaying output from the old rules.
Build the project's file set from default, then add negated patterns for files ESLint never reads, such as Markdown docs and test-runner config. A README edit or a Jest config tweak then leaves the lint key unchanged. A root ESLint config change still invalidates every project. Spec files usually stay in the set because most setups lint them too.
To confirm the setup works, run lint twice with no changes in between. On the second run, cached tasks are annotated as coming from the local cache. The closing summary also reports how many tasks Nx read from cache. If a task you expected to be cached runs again, compare its resolved inputs (nx show project displays them) against the file you changed.
Add ^-prefixed inputs for typed linting. With them, a change in an upstream library becomes part of every dependent project's key. For a widely imported shared library, a single edit invalidates lint caches across much of the workspace. This lowers the hit rate, but it is the cost of not missing real errors.
{
"namedInputs": {
"default": ["{projectRoot}/**/*", "sharedGlobals"],
"sharedGlobals": [],
"lintInputs": [
"default",
"!{projectRoot}/**/*.md",
"!{projectRoot}/jest.config.[jt]s",
"{workspaceRoot}/eslint.config.mjs",
"{workspaceRoot}/tsconfig.base.json",
"{projectRoot}/tsconfig*.json",
{
"externalDependencies": [
"eslint",
"@typescript-eslint/parser",
"@typescript-eslint/eslint-plugin"
]
}
]
},
"targetDefaults": {
"lint": {
"cache": true,
"inputs": ["lintInputs", "^lintInputs"]
}
}
}
An nx.json that caches lint for all projects, keys it on the root ESLint config, tsconfig files and plugin versions, excludes docs and Jest config, and adds ^lintInputs so upstream library changes invalidate typed-lint caches.
When should you use affected runs, ESLint --cache, and remote caching together?
Each layer skips a different unit of work, so they stack rather than compete. In CI, nx affected -t lint compares the branch against a base commit and runs lint only for touched projects and the projects that depend on them. Dependents matter because typed rules such as no-unsafe-assignment or no-floating-promises read types across project boundaries. If a shared library changes a function to return Promise<void>, a consumer that never changed can still start failing.
Nx computation caching then skips whole projects whose inputs hash identically. ESLint's --cache covers the remaining case: a project that does run, where most files are unchanged. Give each project its own --cache-location inside its own directory or under a per-project path. A single shared cache file lets parallel lint processes overwrite one another's entries.
Remote caching extends Nx's project-level hits across machines. A developer who pulls main can reuse results that CI already computed, and CI can reuse results from other branches.
| Layer | Granularity | What it skips | Failure mode | When to avoid |
|---|---|---|---|---|
| Affected runs | Project graph | Projects untouched by the diff | Wrong base commit or missing implicit dependencies leave projects unlinted | Never rely on it alone. Keep a periodic full run on main |
| Nx cache | Project | Projects with identical input hashes | Incomplete named inputs replay stale results | When inputs aren't fully declared |
ESLint --cache |
File | Unchanged files | Doesn't fully track cross-file type changes | With typed configs, unless a periodic uncached run backs it up |
| Remote cache | Project, shared | Work done on other machines | A poisoned or tampered entry propagates to everyone | Without access control. Restrict write access to trusted CI and give developers read-only access |
#!/usr/bin/env bash
# CI lint entrypoint that stacks affected runs, Nx caching and ESLint --cache.
# Each project's lint target is assumed to run, from its own project root:
# eslint . --cache --cache-location .eslintcache --cache-strategy content
# so every project keeps a private ESLint cache and parallel tasks never
# overwrite each other's entries. Add .eslintcache to .gitignore.
set -euo pipefail
# Base commit for the diff. A wrong base silently skips projects,
# so default to the merge-base with main rather than HEAD~1.
BASE_SHA="${BASE_SHA:-$(git merge-base origin/main HEAD)}"
if [ "${LINT_MODE:-affected}" = "full" ]; then
# Scheduled full run on main. It backs up the cheaper paths:
# - catches projects missed by a bad base or missing implicit deps
# - catches stale type-aware results that ESLint's file cache missed
find . -name .eslintcache -not -path '*/node_modules/*' -delete
npx nx run-many -t lint --skip-nx-cache
else
# PR runs lint touched projects plus their dependents, so typed rules
# re-check consumers when a shared library's types change.
# Nx skips projects whose input hashes match a local or remote cache entry.
npx nx affected -t lint --base="$BASE_SHA" --head=HEAD
fi
A CI script that lints only affected projects on pull requests. Each project keeps its own ESLint cache file, and a scheduled full run clears the ESLint caches and bypasses the Nx cache to catch anything the faster layers missed.
How should you migrate a monorepo to ESLint flat config?
Flat config replaces cascading .eslintrc discovery with explicit composition, which suits a monorepo well. Keep one root eslint.config.js that holds shared language options, plugin registration, and workspace-wide rules, and export it as an array. Each project then gets a small eslint.config.js that imports the root array, spreads it, and appends only the overrides that project needs, such as file globs, environment globals, or a stricter rule. Because inheritance is now an ordinary module import, you can trace where a rule comes from by reading code rather than by reasoning about directory lookup order.
Update named inputs in the same change
Your lint target's cache key is only as accurate as its inputs. If nx.json still lists {workspaceRoot}/.eslintrc.json and {projectRoot}/.eslintrc.json, then editing the new files will not invalidate anything. Nx will replay old lint results that were produced under rules that no longer apply. Replace those entries with {workspaceRoot}/eslint.config.js and {projectRoot}/eslint.config.js. If you used .mjs or .cjs, use those extensions instead. Make this edit in the same pull request as the config conversion.
Budget for shims, or defer
Plugins and shared configs that still ship only eslintrc-style exports need adapters. FlatCompat from @eslint/eslintrc translates legacy shared configs, and @eslint/compat can wrap plugins that rely on removed context APIs. Each shim is another layer to debug when a rule behaves unexpectedly.
Defer the migration if a plugin you depend on heavily works only through these shims. Also defer it if you are in the middle of restructuring typed linting, since mixing two config changes makes cache misses and rule regressions harder to attribute.
How do you scope typed linting without losing important checks?
Rules that need type information, such as no-floating-promises or no-misused-promises from typescript-eslint, cannot run on a single file's syntax tree. The parser has to build a TypeScript program covering every file the referenced tsconfig includes, resolve imports, and compute types before any rule runs. In a large project that program build usually costs more than all the syntactic rules combined. It also grows with the size of the tsconfig, not with the number of files you actually lint.
Apply typed rules only where they pay off
In flat config, attach the typed rule set and its parser options to a narrow files glob, such as src/**/*.ts in service and library projects. Leave specs, scripts, generated clients, and config files on syntactic rules only. Point parserOptions.project at a lint-specific tsconfig, for example tsconfig.eslint.json, that includes only those sources. The application tsconfig often pulls in tests and declaration files that nothing in the lint pass needs to type-check.
Don't make lint repeat the compiler
Give each project a separate typecheck target that runs tsc --noEmit and has its own cache inputs. Type errors are the compiler's job. Typed lint rules should catch semantic bugs that compile cleanly. Don't enable rules that only restate errors tsc already reports.
Record what you narrowed
Narrowing coverage is a real trade-off, so write it down. Add a comment next to each glob that explains what is excluded and why. Also list the excluded paths in the workspace's lint documentation. When someone later wonders why a floating promise in a test helper went unflagged, the answer should be a deliberate decision they can revisit, not a gap nobody knew existed.
What are the alternatives, and how do these changes affect engineering cost?
| Option | Speed gain | Missed-violation risk | Setup effort | Maintenance |
|---|---|---|---|---|
| Tune or disable slow rules | Moderate | Medium, since the checks are gone | Low | Low |
| Split typed and untyped targets | High on untyped paths | Low if typed runs still gate merges | Medium | Medium |
Rely on tsc for type checks |
Moderate | Medium, because tsc does not catch floating promises or unsafe any flows |
Low | Low |
| Pre-commit or editor only | High in CI | High, because hooks can be skipped | Low | Low |
| Full uncached runs | None | Lowest | None | Low, but compute cost stays high |
| Caching, affected runs, remote cache | High | Low if inputs are correct | High | Medium to high |
Illustrative estimate (assumed numbers, not a benchmark). Assume:
- 200 projects at 30 s of lint each, so a full run is 100 CPU-minutes.
- A typical change affects 15 projects.
- 40% of those 15 hit the remote cache from an earlier pipeline.
- 80 CI runs per day.
Cost per run = affected × (1 − hit rate) × per-project time = 15 × 0.6 × 30 s = 4.5 minutes.
Daily savings = runs × (full − cached) = 80 × 95.5 ≈ 7,640 CPU-minutes.
Subtract a nightly full run of 100 minutes. Then add the costs that don't show up as compute: storage and access control for the remote cache, plus engineer time spent fixing named inputs when a stale cache hit lets a violation through. The developer-facing gain is lint feedback in minutes rather than a queued hour.
The investment usually isn't worth it in three cases:
- The workspace has fewer than about 20 projects and a full lint already finishes in a few minutes.
- Few typed rules are enabled, so per-project lint time is small.
- No one owns cache correctness. A cache with wrong inputs is worse than no cache, because it reports success it hasn't earned.
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 eslint performance, 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.