TypeScript Plugin for Nx

The TypeScript plugin for Nx, @nx/js, provides generators for creating TypeScript and JavaScript projects, and the @nx/js/typescript plugin automatically infers typecheck and build tasks for your projects using package manager workspaces and TypeScript project references. Maintaining TypeScript project references in a monorepo can be cumbersome, the @nx/js plugin comes with a sync generator to automatically upkeep these references.

You don't need the plugin to use TypeScript with Nx, any project already benefits from caching, task orchestration, and the project graph. The plugin can help simplify setups and maintenance of TypeScript projects at scale.

See the TypeScript compatibility matrix for supported TypeScript versions.

Setting Up @nx/js plugin

Add to an Existing Nx Workspace

nx add @nx/js

Verify the plugin is setup:

Check for the @nx/js listed as a plugin:
Terminal window
```
nx report
```
Ensure inferred project targets are working:
Terminal window
```
nx show projects --with-target=typecheck
```
Inspect a specific project configuration for the typecheck/build target, depending on your project configuration:
Terminal window
```
nx show project <ts-project-name>
```

If your TypeScript projects aren't showing up with the right targets, then view read how @nx/js infers projects

Create a New TypeScript Monorepo

npx create-nx-workspace my-org --template nrwl/typescript-template

yarn create nx-workspace my-org --template nrwl/typescript-template

pnpm create nx-workspace my-org --template nrwl/typescript-template

This creates a monorepo configured with TypeScript Project References and your package manager's workspaces feature. Nx automatically maintains the project references as you add and remove projects.

The --template nrwl/typescript-template uses the modern setup with workspaces and project references as of Nx 20. You can migrate an existing workspace from path aliases to the modern setup.

If you want to keep using the older style of setups with compilerOptions.paths, use create-nx-workspace --preset=apps.

Add Build Support to an Existing Project

If you have a TypeScript project that doesn't have a build target, you can use the setup-build generator to add one:

nx g @nx/js:setup-build my-lib

You'll be prompted to choose a bundler. This configures the project for compilation without recreating it from scratch.

Generate and Manage TypeScript Libraries

Create a Library

Quickly scaffold out a new typescript library. You'll be prompted for common options like test runner and linter. See all the library generator options for more customization.

nx g @nx/js:lib libs/my-lib

Create a Buildable or Publishable Library

To create a library that can be compiled and published to npm, specify a bundler:

# Using TSC (default compiler)
nx g @nx/js:lib libs/my-lib --bundler=tsc

# Using SWC (faster compilation)
nx g @nx/js:lib libs/my-lib --bundler=swc

# Using Rollup (to output in multiple formats)
nx g @nx/js:lib libs/my-lib --bundler=rollup

If you plan to publish your library to npm, then you can pass in the --publishable flag to automatically setup Nx Release to manage the releasing process.

nx g @nx/js:lib libs/my-lib --bundler=tsc --publishable

By default, @nx/js uses TSC to compile libraries. You can convert to use SWC for faster compilation at any time with the convert-to-swc generator:

nx g @nx/js:convert-to-swc my-lib

SWC dependencies are installed automatically the first time the generator is ran.

Build TypeScript Libraries

nx build my-lib

The output location is controlled by outDir in your build tsconfig (defaults to tsconfig.lib.json):

{
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

The plugin reads outDir automatically and sets the correct task outputs for caching.

If you're manually defining the build targets, make sure to keep the target configuration outputs in sync with where typescript is outputting the built artifacts. This ensures Nx properly restores the cache for your build tasks.

Run Typechecking

nx typecheck my-lib

The typecheck task is automatically inferred for any project with a tsconfig.json.

If you're not using inferred plugins, then you can manually define a typecheck target in your projects configuration.

Configure `@nx/js` TypeScript Inference

By default, when you add the @nx/js the plugin will be configured to use project and target inference.

Otherwise you can manually add the plugin to your nx.json#plugins to enable it

How the TypeScript Plugin Infers Tasks

The @nx/js/typescript plugin adds tasks based on the files it finds in your project:

The @nx/js/typescript plugin will add a typecheck task to any project that has a tsconfig.json.

The plugin also adds a build task for projects that meet both of the following conditions:

Have a runtime tsconfig file (defaults to tsconfig.lib.json)
Have a package.json with entry points that reference compiled output (not source files)

For example, this project will get a build task because its exports point to dist/:

{
  "name": "@my-org/my-lib",
  "exports": {
    "./package.json": "./package.json",
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  }
}

This project will not get a build task because its exports point directly to source:

{
  "name": "@my-org/my-lib",
  "exports": {
    "./package.json": "./package.json",
    ".": "./src/index.ts"
  }
}

This distinction is important in monorepos — not all libraries need to be compiled. Libraries consumed only within the monorepo can point directly to source for faster development, while libraries published to npm need a build step. See TypeScript Project Linking for more on how projects reference each other.

Plugin Options

Configure @nx/js/typescript in the plugins array in nx.json:

{
  "plugins": [
    {
      "plugin": "@nx/js/typescript",
      "options": {
        "typecheck": {
          "targetName": "typecheck"
        },
        "build": {
          "targetName": "build",
          "configName": "tsconfig.lib.json",
          "buildDepsName": "build-deps",
          "watchDepsName": "watch-deps"
        }
      }
    }
  ]
}

Option	Description	Default
`typecheck.targetName`	Name of the typecheck task	`typecheck`
`build.targetName`	Name of the build task	`build`
`build.configName`	The tsconfig file used for builds	`tsconfig.lib.json`
`build.buildDepsName`	Name of the task for building all dependencies	`build-deps`
`build.watchDepsName`	Name of the task for watching and rebuilding dependencies	`watch-deps`

Set typecheck or build to false to disable that task entirely.

Exclude or Include Specific Projects

You can control which projects the plugin applies to at three levels:

Plugin-level: Use include/exclude glob patterns to scope the plugin to specific projects:

{
  "plugins": [
    {
      "plugin": "@nx/js/typescript",
      "include": ["packages/**/*"],
      "exclude": ["packages/legacy-app/**/*"],
      "options": { ... }
    }
  ]
}

Project-level: To opt a specific project out of the typecheck task, set nx.addTypecheckTarget to false in that project's tsconfig.json:

{
  "extends": "../../tsconfig.base.json",
  "files": [],
  "include": [],
  "references": [{ "path": "./tsconfig.lib.json" }],
  "nx": {
    "addTypecheckTarget": false
  }
}

View Inferred Tasks

To see what tasks Nx inferred for a project:

nx show project <my-project>

Or open the project details view in Nx Console.

CI Considerations for TypeScript Projects

See Set Up CI for a complete CI configuration guide.

Build and Test Only What Changed

nx affected -t build test typecheck lint

This uses the project graph to determine which projects are affected by your changes and only runs tasks for those. Read more about the benefits of nx affected.

Remote Caching

Share build and typecheck cache results across your team and CI with remote caching:

nx connect

Batch Mode

For large monorepos with many TypeScript projects, TSC batch mode can improve build performance by batching compilation across projects.

What's Next

TypeScript Packages Tutorial Build a TypeScript monorepo step-by-step with Nx.

Switch to Workspaces & Project References Migrate from path aliases to the modern monorepo setup.

Compile to Multiple Formats Build libraries to both ESM and CommonJS with Rollup.

Generators Reference Full API reference for @nx/js generators.

Executors Reference Full API reference for @nx/js executors.

Migrations Reference Full reference for @nx/js migrations.