Skip to content
Nx Docs

nx Migrations

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

21.1.x

21-1-0-add-ignore-entries-for-nx-rule-files

Version: 21.1.0-beta.2

Adds **/nx-rules.mdc and **/nx.instructions.md to .gitignore if not present

21.0.x

remove-legacy-cache

Version: 21.0.0-beta.8

Removes the legacy cache configuration from nx.json

Use Legacy Cache

Removes useLegacyCache from nx.json as it is no longer functional in Nx 21

Sample Code Changes

{% tabs %} {% tab label=“Before” %}

{
  "targetDefaults": {},
  "useLegacyCache": true
}

{% /tab %} {% tab label=“After” %}

{
  "targetDefaults": {}
}

{% /tab %} {% /tabs %}

remove-custom-tasks-runner

Version: 21.0.0-beta.8

Removes the legacy cache configuration from nx.json

Remove Custom Tasks Runners

Removes tasksRunnerOptions entries from nx.json that contain custom tasks runners. In Nx 21, custom tasks runners are no longer functional. See /deprecated/custom-tasks-runner for more information.

Sample Code Changes

Removes custom task runner configuration from nx.json.

{% tabs %} {% tab label=“Before” %}

{
  "targetDefaults": {},
  "tasksRunnerOptions": {
    "default": {
      "runner": "custom-task-runner"
    }
  }
}

{% /tab %} {% tab label=“After” %}

{
  "targetDefaults": {}
}

{% /tab %} {% /tabs %}

release-version-config-changes

Version: 21.0.0-beta.11

Updates release version config based on the breaking changes in Nx v21

Nx Release Version Config Changes

In Nx v21, the implementation details of versioning were rewritten to massively enhance flexibility and lay the groundwork for future features.

As part of this, some elements of the release configuration were updated. During the lifecycle of Nx v21, you can still opt into the old versioning by setting release.version.useLegacyVersioning to true, in which case the release configuration should remain unchanged.

In Nx v22, the legacy versioning implementation will be removed entirely and the configuration will have to be updated to match what this migration does for you.

Sample Code Changes

“generatorOptions” is longer exists and most non-ecosystem specific options have moved to the top level of “version” and are therefore fully documented on the JSON schema as a core option.

“packageRoot: string” has been replaced by the more flexible concept of “manifestRootsToUpdate: string[]”, allowing for multiple manifest files (such as package.json in the JS/TS ecosystem) to be updated in a single versioning run.

Ecosystem specific options, such as “skipLockFileUpdate”, which is specific to the JS/TS ecosystem, are available via the new “versionActionsOptions” object, which is so named because of the new VersionActions abstraction introduced in Nx v21, which allows for different ecosystems and use-cases to be supported via very minimal implementation effort.

“preserveLocalDependencyProtocols” changed from false by default to true by default in Nx v21, so it can simply be removed from the configuration when set to true.

The migration will also update release groups version configuration, as well as project.json and package.json version configuration, if applicable.

{% tabs %} {% tab label=“Before” %}

{
  "release": {
    "version": {
      "generatorOptions": {
        "packageRoot": "build/packages/{projectName}",
        "currentVersionResolver": "registry",
        "skipLockFileUpdate": true,
        "preserveLocalDependencyProtocols": true
      }
    }
  }
}

{% /tab %} {% tab label=“After” %}

{
  "release": {
    "version": {
      "manifestRootsToUpdate": ["build/packages/{projectName}"],
      "currentVersionResolver": "registry",
      "versionActionsOptions": {
        "skipLockFileUpdate": true
      }
    }
  }
}

{% /tab %} {% /tabs %}

release-changelog-config-changes

Version: 21.0.0-beta.11

Updates release changelog config based on the breaking changes in Nx v21

Nx Release Changelog Config Changes

In Nx v21, the mapAuthorsToGitHubUsernames changelog “renderOption” for the default changelog renderer was renamed to applyUsernameToAuthors to reflect the fact that it is no longer specific to GitHub. Most people were not setting this option directly, but if you were, it will be automatically migrated by this migration.

The migration will also update release groups changelog configuration, if applicable.

Sample Code Changes

{% tabs %} {% tab label=“Before” %}

{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        "renderOptions": {
          "mapAuthorsToGitHubUsernames": true
        }
      },
      "projectChangelogs": {
        "renderOptions": {
          "mapAuthorsToGitHubUsernames": false
        }
      }
    }
  }
}

{% /tab %} {% tab label=“After” %}

{
  "release": {
    "changelog": {
      "workspaceChangelog": {
        "renderOptions": {
          "applyUsernameToAuthors": true
        }
      },
      "projectChangelogs": {
        "renderOptions": {
          "applyUsernameToAuthors": false
        }
      }
    }
  }
}

{% /tab %} {% /tabs %}

20.0.x

move-use-daemon-process

Version: 20.0.0-beta.7

Migration for v20.0.0-beta.7

Move useDaemonProcess

Move the useDaemonProcess to the root of nx.json

Sample Code Changes

{% tabs %} {% tab label=“Before” %}

{
  "tasksRunnerOptions": {
    "default": {
      "options": {
        "useDaemonProcess": false
      }
    }
  }
}

{% /tab %} {% tab label=“After” %}

{
  "useDaemonProcess": false
}

{% /tab %} {% /tabs %}

use-legacy-cache

Version: 20.0.1

Set useLegacyCache to true for migrating workspaces

Use Legacy Cache

Set useLegacyCache to true for migrating workspaces

Sample Code Changes

Add useLegacyCache to nx.json unless enableDbCache was set to true.

{% tabs %} {% tab label=“Before” %}

{
  "targetDefaults": {}
}

{% /tab %} {% tab label=“After” %}

{
  "targetDefaults": {},
  "useLegacyCache": true
}

{% /tab %} {% /tabs %}

19.2.x

19-2-0-move-graph-cache-directory

Version: 19.2.0-beta.2

Updates the default workspace data directory to .nx/workspace-data

19-2-2-update-nx-wrapper

Version: 19.2.2-beta.0

Updates the nx wrapper.

19-2-4-set-project-name

Version: 19.2.4-beta.0

Set project name in nx.json explicitly

18.1.x

move-default-base-to-nx-json-root

Version: 18.1.0-beta.3

Moves affected.defaultBase to defaultBase in nx.json

18.0.x

18.0.0-disable-adding-plugins-for-existing-workspaces

Version: 18.0.0-beta.2

Updates nx.json to disabled adding plugins when generating projects in an existing Nx workspace

17.3.x

17.3.0-update-nx-wrapper

Version: 17.3.0-beta.6

Updates the nx wrapper.

17.0.x

17.0.0-move-cache-directory

Version: 17.0.0-beta.1

Updates the default cache directory to .nx/cache

Sample Code Changes

Add .nx/cache to the .gitignore file.

{% tabs %} {% tab label=“Before” %}

node_modules

{% /tab %} {% tab label=“After” %}

node_modules
.nx/cache

{% /tab %} {% /tabs %}

Add .nx/cache to the .prettierignore file.

{% tabs %} {% tab label=“Before” %}

/dist

{% /tab %} {% tab label=“After” %}

/dist
.nx/cache

{% /tab %} {% /tabs %}

17.0.0-use-minimal-config-for-tasks-runner-options

Version: 17.0.0-beta.3

Use minimal config for tasksRunnerOptions

rm-default-collection-npm-scope

Version: 17.0.0-rc.1

Migration for v17.0.0-rc.1