@nx/js - Migrations

The @nx/js plugin provides various migrations to help you migrate to newer versions of js projects within your Nx workspace. Below is a complete reference for all available migrations.

23.0.x

23-0-0-rewrite-internal-subpath-imports

Version: 23.0.0-beta.14

Rewrites @nx/js/src/* subpath imports to the new @nx/js/internal entry. The ./src/* wildcard has been removed from @nx/js’s exports map; @nx/js/src/release/version-actions is preserved as a non-wildcard entry for back-compat with existing nx.json release configs. If a rewritten import resolves to a symbol that lives on the public @nx/js entry (e.g. libraryGenerator, extractTsConfigBase, resolvePathsBaseUrl), change the specifier to @nx/js.

update-23-0-0-migrate-create-nodes-v2-import

Version: 23.0.0-beta.24

Rename imports of createNodesV2 from @nx/js/typescript to the canonical createNodes export.

Rename createNodesV2 imports to createNodes

@nx/js renamed its primary inferred-plugin export from createNodesV2 to createNodes. The createNodesV2 name is preserved as a deprecated alias for now, but new code should use createNodes.

This migration scans every .ts, .tsx, .cts, and .mts file in your workspace and rewrites named imports and re-exports of createNodesV2 from @nx/js/typescript to createNodes.

Sample Code Changes

Before

import { createNodesV2 } from '@nx/js/typescript';

After

import { createNodes } from '@nx/js/typescript';

Aliases are preserved (createNodesV2 as cn becomes createNodes as cn), and if a file already imports both names ({ createNodes, createNodesV2 }) the redundant binding is dropped.

What is not rewritten

Only static import/export named bindings from @nx/js/typescript are rewritten. Namespace imports, dynamic import(...), require(...) destructuring, and property access such as plugin.createNodesV2 are left untouched — they keep working through the createNodesV2 runtime alias. Update those by hand if you want to drop the deprecated name everywhere.

23.0.0-swc-cli-package-updates

Version: 23.0.0-beta.17

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@swc/cli	~0.8.0	Updated only

22.6.x

22.6.4-package-updates

Version: 22.6.4

Packages

The following packages will be updated:

Name	Version	Always add to package.json
verdaccio	^6.3.2	Updated only

22.5.x

22.5.0-package-updates

Version: 22.5.0-beta.1

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@swc/core	^1.15.5	Updated only
@swc/helpers	^0.5.18	Updated only
@swc-node/register	^1.11.1	Updated only

22.5.0-swc-cli-package-updates

Version: 22.5.0-beta.1

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@swc/cli	^0.7.10	Updated only

22.1.x

remove-redundant-ts-project-references

Version: 22.1.0-rc.1

Removes redundant TypeScript project references from project’s tsconfig.json files when runtime tsconfig files (e.g., tsconfig.lib.json, tsconfig.app.json) exist.

Removes Redundant TypeScript Project References from tsconfig.json Files

Removes redundant TypeScript project references from tsconfig.json files when runtime tsconfig files (e.g., tsconfig.lib.json, tsconfig.app.json) exist. Previously, external project references were duplicated in both the project’s tsconfig.json and runtime tsconfig files. This migration syncs the TypeScript project references to match the project graph, ensuring that external references only appear in runtime tsconfig files when they exist.

Examples

When a project has runtime tsconfig files like tsconfig.lib.json, the migration will remove external project references from the project’s tsconfig.json file:

Before

libs/my-lib/tsconfig.json

{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "../other-lib",
    },
  ],
}

After

libs/my-lib/tsconfig.json

{
  "compilerOptions": {
    "composite": true,
  },
  "references": [],
}

The external references remain in the runtime tsconfig file where they belong:

Before

libs/my-lib/tsconfig.lib.json

{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "../other-lib/tsconfig.lib.json",
    },
  ],
}

After

libs/my-lib/tsconfig.lib.json

{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "../other-lib/tsconfig.lib.json",
    },
  ],
}

For projects without runtime tsconfig files, the project’s tsconfig.json file will continue to contain external project references:

Before

libs/legacy-lib/tsconfig.json

{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "../other-lib",
    },
  ],
}

After

libs/legacy-lib/tsconfig.json

{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "../other-lib",
    },
  ],
}

Internal project references (references within the same project directory) are preserved in the project’s tsconfig.json:

Before

libs/my-lib/tsconfig.json

{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "./tsconfig.lib.json",
    },
    {
      "path": "./tsconfig.spec.json",
    },
  ],
}

After

libs/my-lib/tsconfig.json

{
  "compilerOptions": {
    "composite": true,
  },
  "references": [
    {
      "path": "./tsconfig.lib.json",
    },
    {
      "path": "./tsconfig.spec.json",
    },
  ],
}

22.0.x

remove-external-options-from-js-executors

Version: 22.0.0-beta.0

Remove the deprecated external and externalBuildTargets options from the @nx/js:swc and @nx/js:tsc executors.

Remove the external and externalBuildTargets Options from the @nx/js:swc and @nx/js:tsc Executors

Remove the deprecated external and externalBuildTargets options from the @nx/js:swc and @nx/js:tsc executors. These options were used for inlining dependencies, which was an experimental feature and has been deprecated for a long time. The migration only removes the options from the project configuration and target defaults. If you rely on inlining dependencies, you need to make sure they are all buildable or use a different build tool that supports bundling.

Sample Code Changes

Remove external and externalBuildTargets from the @nx/js:swc or @nx/js:tsc executor options in project configuration.

Before

libs/my-lib/project.json

{
  "targets": {
    "build": {
      "executor": "@nx/js:swc",
      "options": {
        "main": "libs/my-lib/src/index.ts",
        "outputPath": "dist/libs/my-lib",
        "tsConfig": "libs/my-lib/tsconfig.lib.json",
        "external": ["react", "react-dom"],
        "externalBuildTargets": ["build"]
      }
    }
  }
}

After

libs/my-lib/project.json

{
  "targets": {
    "build": {
      "executor": "@nx/js:swc",
      "options": {
        "main": "libs/my-lib/src/index.ts",
        "outputPath": "dist/libs/my-lib",
        "tsConfig": "libs/my-lib/tsconfig.lib.json"
      }
    }
  }
}

Remove external and externalBuildTargets from the @nx/js:swc or @nx/js:tsc executor target defaults in nx.json.

Before

nx.json

{
  "targetDefaults": {
    "@nx/js:swc": {
      "options": {
        "main": "{projectRoot}/src/index.ts",
        "outputPath": "dist/{projectRoot}",
        "tsConfig": "{projectRoot}/tsconfig.lib.json",
        "external": "all",
        "externalBuildTargets": ["build"]
      }
    }
  }
}

After

nx.json

{
  "targetDefaults": {
    "@nx/js:swc": {
      "options": {
        "main": "{projectRoot}/src/index.ts",
        "outputPath": "dist/{projectRoot}",
        "tsConfig": "{projectRoot}/tsconfig.lib.json"
      }
    }
  }
}

21.5.x

migrate-development-custom-condition

Version: 21.5.0-beta.2

Migrate the legacy ‘development’ custom condition to a workspace-unique custom condition name.

Migrate development custom condition to unique workspace-specific name

Replace the TypeScript development custom condition with a unique workspace-specific name to avoid conflicts when consuming packages in other workspaces.

Examples

The migration will update the custom condition name in both tsconfig.base.json and all workspace package.json files that use the development custom condition:

Before

tsconfig.base.json

{
  "compilerOptions": {
    "customConditions": ["development"]
  }
}

After

tsconfig.base.json

{
  "compilerOptions": {
    "customConditions": ["@my-org/source"] // assuming the root package.json name is `@my-org/source`
  }
}

The migration also updates package.json files that use the development condition in their exports field and point to TypeScript files:

Before

libs/my-lib/package.json

{
  "name": "@myorg/my-lib",
  "exports": {
    ".": {
      "development": "./src/index.ts",
      "default": "./dist/index.js"
    }
  }
}

After

libs/my-lib/package.json

{
  "name": "@myorg/my-lib",
  "exports": {
    ".": {
      "@my-org/source": "./src/index.ts",
      "default": "./dist/index.js"
    }
  }
}

If the custom condition is not set to ["development"] or the package.json’s exports field doesn’t point to TypeScript files, the migration will not modify the configuration:

Before

libs/my-lib/package.json

{
  "name": "@myorg/my-lib",
  "exports": {
    ".": {
      "development": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}

After

libs/my-lib/package.json

{
  "name": "@myorg/my-lib",
  "exports": {
    ".": {
      "development": "./dist/index.js",
      "default": "./dist/index.js"
    }
  }
}

21.5.0-package-updates

Version: 21.5.0-beta.2

Packages

The following packages will be updated:

Name	Version	Always add to package.json
typescript	~5.9.2	Updated only

21.2.x

21.2.0-package-updates

Version: 21.2.0-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
typescript	~5.8.2	Updated only