Why is Nx ESLint slow in large backend workspaces?
This guide is for backend and platform engineers who run dozens or hundreds of Nx projects (services, shared libraries, generated clients) and have watched lint time grow faster than the codebase. It applies if nx affected -t lint takes longer every quarter even though individual projects stay small, or if the lint step now accounts for more CI time than build or test.
Most of the cost comes from typed linting. Rules such as @typescript-eslint/no-floating-promises or no-misused-promises cannot work from the syntax tree alone. They need to know what type an expression resolves to. To answer that, typescript-eslint asks the TypeScript compiler to build a program: it reads the tsconfig, resolves every included file and its imports, parses declaration files, and runs type checking on demand. For a large program, this setup can take longer than running the rules themselves.
Nx makes the problem worse through repetition. Each project's lint target runs as its own task, often in its own process, so each one builds its own TypeScript program. If parserOptions.project points at a root tsconfig, or uses a broad glob that matches every tsconfig.*.json in the workspace, every project's lint run loads type information for far more code than it lints. Path aliases make this worse, because they pull dependency source files into each program instead of prebuilt declarations. The total cost then grows with the number of projects multiplied by the size of what each program loads, not with the amount of code you actually changed.
nx affected -t lint
|
+---------------+---------------+
| | |
v v v
+-----------+ +-----------+ +-----------+
| lint: | | lint: | | lint: |
| orders | | billing | | shared-db |
| (process) | | (process) | | (process) |
+-----------+ +-----------+ +-----------+
| | |
v v v
parserOptions.project -> root tsconfig or broad tsconfig.*.json glob
| | |
v v v
+-----------+ +-----------+ +-----------+
| TS program| | TS program| | TS program|
| built #1 | | built #2 | | built #3 |
+-----------+ +-----------+ +-----------+
| | |
+---------------+---------------+
| each program loads
v
+-----------------------------------------------+
| Whole workspace: all services, libs, generated|
| clients, .d.ts files + path-alias sources |
+-----------------------------------------------+
cost ~ (number of projects) x (size of each program), not changed code
Each Nx lint task builds its own TypeScript program, and a root tsconfig or broad project glob makes every one of them load type information for the whole workspace.
How do you find where lint time actually goes?
That multiplication is why you should measure before changing anything. Each fix targets a different cost, and the wrong one can add complexity without saving time.
Start with Nx. Run the lint target across all projects with the cache bypassed (--skip-nx-cache), then sort projects by duration. A few slow outliers point to per-project configuration. Uniform slowness points to shared config or workspace-wide type loading.
For each slow project, run ESLint directly with the TIMING environment variable set (for example, TIMING=1). ESLint then prints the most expensive rules and their share of rule time. Parsing and TypeScript program construction happen outside rules, so they do not appear in this table. Compare the summed rule time against the run's total wall-clock time. The gap is mostly parse and program setup.
Expect the first type-aware rule to look expensive. It often absorbs the type checker's lazy work, so the cost is shared rather than caused by that one rule.
Illustrative estimate (assumed numbers, not a benchmark): overhead = wall time − Σ rule time. Suppose wall time is 90 s and rule time is 30 s, of which typed rules account for 24 s. Then overhead = 90 − 30 = 60 s. Program setup dominates, so removing rules would recover at most a third of the run.
| Finding | Likely cause | Act on | Avoid |
|---|---|---|---|
| Large overhead gap | Program creation | Type-info scoping | Dropping rules |
| Typed rules dominate rule time | Type checker queries | Typed/syntactic split | More parallelism |
| Time scales with file count | Volume | Caching, affected runs | Parser tuning |
#!/usr/bin/env bash
# Step 1: per-project lint duration through Nx, cache bypassed.
# Projects are linted one at a time so each timing is isolated.
# Each number includes Nx startup, so compare projects to each other
# rather than reading them as absolute ESLint cost.
set -euo pipefail
for project in $(npx nx show projects --with-target lint); do
start=$(date +%s)
npx nx run "$project:lint" --skip-nx-cache > /dev/null 2>&1 || true
end=$(date +%s)
echo "$((end - start))s $project"
done | sort -rn | tee lint-durations.txt
# A few slow outliers suggest per-project config.
# Uniform slowness suggests shared config or workspace-wide type loading.
# Step 2: per-rule cost for one slow project (placeholder path).
# Run ESLint directly so Nx overhead is excluded from the wall time.
# TIMING=1 prints the most expensive rules and their share of rule time.
# Parsing and TypeScript program setup do not appear in that table.
SLOW_PROJECT_DIR="libs/orders"
time TIMING=1 npx eslint "$SLOW_PROJECT_DIR"
# Step 3: compare the two numbers by hand.
# overhead = 'real' time - sum of the Time (ms) column
# Large overhead -> program creation: scope type info, keep the rules.
# Typed rules dominate -> split typed and syntactic linting.
# Time tracks file count -> use caching and affected runs.
Shows how to time each Nx lint target with the cache bypassed, then run ESLint with TIMING=1 on a slow project so you can compare total rule time against wall-clock time.
How should you scope type information with parserOptions.project or the project service?
The most common cause of slow typed linting is a single root tsconfig whose include covers the whole workspace. Nx runs lint per project, but if every project's ESLint config points parserOptions.project at that root file, every lint task builds a TypeScript program for the entire repository. You pay that cost once per project, and memory grows with it. Instead, point each project at its own tsconfig (usually the lib/app and spec configs it already has) and set tsconfigRootDir so relative paths resolve correctly. Keep include patterns tight. Broad globs can pull in build output, generated clients, and fixtures. Path mappings that resolve to other libraries' source files also add those files to the program, so a "small" project can still type-check half the workspace.
The project service option in typescript-eslint is the alternative. Rather than a list of tsconfigs, it uses TypeScript's own project service, the same mechanism editors use, to find the nearest tsconfig for each linted file. Files that belong to no tsconfig, such as root-level config scripts, must be allowed explicitly through its default-project settings. It removes most glob bookkeeping and the "file not included in any project" errors.
Explicit lists still make sense when you want a dedicated lint-only tsconfig that file discovery won't pick up. They also help when you need precise control over which program a file lands in.
Per-project configs carry an ongoing maintenance cost. Nx generators and a shared base config that projects extend keep new projects consistent. Hand edits still drift, so audit periodically.
// libs/orders/eslint.config.mjs (per-project flat config)
import tseslint from 'typescript-eslint';
// Shared base config at the workspace root. It holds rules, not type info.
import baseConfig from '../../eslint.config.mjs';
export default [
...baseConfig,
...tseslint.configs.recommendedTypeChecked,
{
files: ['**/*.ts'],
languageOptions: {
parserOptions: {
// Option A: explicit list. Only this project's configs, never the root
// tsconfig that includes the whole workspace.
project: ['./tsconfig.lib.json', './tsconfig.spec.json'],
// Resolve the paths above relative to this project, not the cwd
// that Nx happens to run ESLint from.
tsconfigRootDir: import.meta.dirname,
// Option B: project service. Remove `project` above and use this instead.
// TypeScript finds the nearest tsconfig for each file, as editors do.
// projectService: {
// // Files not covered by any tsconfig, such as this config file,
// // must be allowed here explicitly.
// allowDefaultProject: ['*.mjs'],
// },
},
},
},
];
// libs/orders/tsconfig.lib.json: keep include narrow so build output,
// generated clients and fixtures stay out of the program:
// "include": ["src/**/*.ts"],
// "exclude": ["src/**/*.spec.ts", "src/**/fixtures/**"]
This per-project flat ESLint config scopes typed linting to the project's own tsconfigs using tsconfigRootDir, and shows projectService as the commented-out alternative to the explicit list.
How do you split typed and syntactic rules in flat config?
The shared root config lives in eslint.config.mjs (or .js) at the workspace root and exports an array. Each project's own config imports that array, spreads it, and appends only project-specific entries. Flat config has no cascade: ESLint evaluates every object in order, and for a given file, later matching objects override earlier ones. Order and files globs are the whole mechanism, so treat them deliberately.
Put a global ignores object first, one containing only an ignores key, so build output, generated API clients, and migrations are never parsed. Then add syntactic rules that apply broadly. Add typed rule sets in a separate object scoped to source globs such as src/**/*.ts, with parser options that enable type information. After that, add an object matching tests, scripts, and config files that turns type checking off. typescript-eslint ships a disableTypeChecked config for this purpose. Those files then skip program creation entirely, and on a backend project with large test suites this is often where most of the savings come from.
The common mistake is spreading a type-checked preset as a top-level object with no files key. An object without files matches everything ESLint lints, so typed rules and the type-aware parser setup reach every JavaScript config file and script. Some of those files sit outside any tsconfig, and you either get errors for them or pay for type information you don't use.
Migrating from eslintrc takes real work:
- Some plugins don't export flat configs yet and need the
FlatCompatshim. .eslintignoreis no longer read.- Globs resolve relative to the config file's location rather than through
overridessemantics.
Because of these changes, compare the list of linted files before and after the migration.
// eslint.config.mjs at the workspace root; project configs import and spread this array
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import { defineConfig } from 'eslint/config';
export default defineConfig([
// 1. Global ignores: an object with only `ignores`, so these files are never parsed
{ ignores: ['**/dist/**', '**/generated/**', '**/migrations/**'] },
// 2. Syntactic rules for every linted file. These rules need no type information.
js.configs.recommended,
tseslint.configs.recommended,
// 3. Typed rules apply only to source files. Scoping with `files` keeps the
// type-aware parser away from scripts and config files.
{
files: ['**/src/**/*.ts'],
extends: [tseslint.configs.recommendedTypeChecked],
languageOptions: {
parserOptions: {
projectService: true,
tsconfigRootDir: import.meta.dirname,
},
},
},
// 4. Tests, scripts and config files come later and override step 3.
// Type checking is turned off, so no TypeScript program is created for them.
{
files: ['**/*.spec.ts', '**/*.test.ts', '**/scripts/**', '**/*.config.{js,mjs,ts}'],
extends: [tseslint.configs.disableTypeChecked],
},
// MISTAKE: spreading the typed preset at the top level with no `files` key
// matches everything, including JS config files outside any tsconfig.
// ...tseslint.configs.recommendedTypeChecked,
]);
A shared root flat config that first ignores build output, generated clients and migrations, then applies syntactic rules everywhere, scopes typed rules to source globs, and turns type checking off for tests, scripts and config files through a later matching object.
Nx task caching vs ESLint caching: which should you rely on?
Nx and ESLint each offer a cache, and they key results on different things.
| Nx task cache | ESLint --cache |
|
|---|---|---|
| Unit cached | Whole lint task for a project | Individual file result |
| Key | Hash of declared inputs | File content plus config |
| Sees cross-file type changes | Yes, if inputs include them | No |
| Safe with typed rules | Yes, with correct inputs | No |
ESLint's per-file cache assumes a file's lint result depends only on that file and the config. Typed rules break that assumption. If orders.ts imports a function whose return type changes from string to Promise<string>, no-floating-promises should now fail in orders.ts. But orders.ts itself is unchanged, so the cache replays its old pass and hides the violation. For typed linting, rely on Nx's task cache.
Nx is only as correct as the lint target's inputs. Those inputs should include:
- the project's source files
- the root and project ESLint config files
- every tsconfig in the
extendschain ^-prefixed inputs for upstream projects, so type changes in dependencies invalidate the cache
If the inputs are too broad, such as the whole workspace or test fixtures, nearly every commit misses the cache and you gain nothing. If they are too narrow, the cache returns stale passes. Stale passes do more damage. A cache miss only costs time. A stale pass lets a real bug merge, and nothing signals that it happened.
nx affected in CI depends on the same accuracy at the graph level. If the project graph misses a dependency, such as a codegen step, a dynamic import, or a shared config the graph can't infer, affected projects are skipped. Declare these with implicitDependencies and add shared config files to the inputs, so editing them marks every consuming project as affected.
When should you avoid raising parallelism or dropping expensive rules?
Parallelism is the last lever because typed linting is memory-bound before it is CPU-bound. Each ESLint process running type-aware rules builds and holds a TypeScript program for the project it is linting. Raising Nx's --parallel count multiplies that footprint. On a memory-limited CI runner, the result is swapping or OOM-killed tasks, and the run gets slower rather than faster.
Illustrative estimate. Use assumed inputs here and replace them with your own measurements:
- The runner has 16 GB of RAM.
- You reserve about 4 GB for the OS, the Nx process and anything else on the box.
- A typed-lint process for your largest backend project peaks at about 2.5 GB.
That leaves roughly 12 GB for lint workers, and 12 ÷ 2.5 = 4.8. A parallel value of 4 is the ceiling, not 8 because the runner has 8 cores. Measure peak resident memory per lint task on the real runner rather than guessing.
Laptops and CI runners differ in RAM, core count and what else is running, so measure each one separately. Set the CI value explicitly instead of inheriting the local default.
Dropping expensive rules needs the same care. The no-unsafe-* family and the promise rules are often the slowest type-aware checks. For each one, ask two questions:
- Has it caught real bugs in your history?
- Does the compiler or a
typechecktarget already cover the same ground? For example, strict compiler options reduce how muchanyenters your code in the first place.
Be careful with the promise rules. no-floating-promises and no-misused-promises exist to catch unawaited calls in request handlers and queue consumers. These bugs cause swallowed errors, partial writes and responses sent before work finishes, and they are expensive to diagnose in production. If one of these rules is slow, move it to a later lint stage instead of deleting it.
What are the alternatives, and how should lint stages split across editor, pre-commit, and CI?
That later stage should exist by design. The usual setup has three layers, each with a narrower promise than the one after it.
First, split lint and typecheck into separate Nx targets. The compiler already builds the full type graph. Running it as its own cacheable task means a type error doesn't invalidate lint results, and the reverse holds too. Each target's cache key also reflects only the inputs it actually depends on.
| Stage | What runs | What it guarantees |
|---|---|---|
| Editor | Syntactic rules, plus typed rules on the open file if the editor can keep up | Fast hints only. No guarantee across files |
| Pre-commit | Syntactic rules on staged files | Committed files meet style and basic correctness rules |
| CI | Full typed lint and typecheck on affected projects | The merged code passes every rule against the real type graph |
The gain is real. Local feedback drops to seconds, and CI spends fewer minutes because cached and unaffected projects are skipped. The cost is that code can pass locally and still fail in CI. Developers also hear about floating promises or unsafe any flows only after they push, and those are exactly the bugs typed rules exist to catch. To limit that gap, offer a local command that mirrors the CI lint step.
Checklist
- Measure: time per project and per rule before changing anything.
- Scope: limit type information to the tsconfig files each project actually needs.
- Split: separate typed from syntactic rules, and lint from typecheck.
- Cache: define correct Nx inputs so cache hits are safe.
- Affected: run only the projects a change touches.
- Tune parallelism: adjust last, against memory limits you have measured.
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 slow, 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.