Managing configuration files

An Nx workspace contains configuration for Nx and for the tools used by each project. Nx plugins read both sources and combine them into resolved project configuration. You can inspect or override that configuration when a project needs different behavior.

Kinds of configuration

Configuration varies along two dimensions:

• Type: Nx configuration controls task orchestration and caching, while tool configuration controls tools such as Vite, ESLint, and TypeScript.
• Scope: Workspace configuration applies broadly, while project configuration applies to one project.

A workspace might contain these files:

Scope	Nx configuration	TypeScript configuration
Workspace	/nx.json	/tsconfig.base.json
Project	/packages/myapp/package.json	/packages/myapp/tsconfig.json

Projects can store Nx-specific settings in the nx section of package.json. project.json is also supported for project configuration, but most task settings don't need to be defined in either file when a plugin can infer them.

How plugins reduce configuration

A plugin reads existing tool configuration and adds the Nx metadata required to run and cache tasks. For example, @nx/vite/plugin reads vite.config.ts, infers the vite build command, and derives the build output path from the Vite configuration.

Use targetDefaults in nx.json for settings shared by matching targets. Project-level configuration should contain only exceptions or tasks that no plugin can infer.

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
    },
  },
}

{
  "name": "myapp",
  "nx": {
    "targets": {
      "build": {
        "inputs": ["production", "^production", "{workspaceRoot}/brand/**"],
      },
    },
  },
}

The project-level inputs value overrides the corresponding inferred or default value for myapp:build.

Resolve a target configuration

Nx merges target configuration in this order, from least specific to most specific:

1. Configuration inferred by plugins listed in nx.json.
2. Matching targetDefaults from nx.json.
3. Project configuration from package.json or project.json.

Tool configuration remains the source of truth for the tool itself. A plugin translates relevant values from that file into Nx target metadata before Nx applies the Nx-specific overrides.

Run nx show target <project>:<target> to inspect the resolved target. Add --verbose to see which file or plugin contributed each value:

nx show target myapp:build --verbose

Learn by doing

Follow the configuring tasks tutorial to inspect and override inferred configuration.

For configuration schemas, see nx.json reference and project configuration.