Migrate to Inferred Tasks (Project Crystal)

In this recipe, you'll learn how to migrate an existing Nx workspace from using executors in project.json to using inferred tasks.

The main benefits of migrating to inferred tasks are

  • reducing the amount of configuration needed in project.json
  • inferring the correct cache settings based on the tool configuration files
  • splitting tasks (Atomizer) for plugins that support it

For the best experience, we recommend that you migrate to the latest Nx version before continuing. At minimum, you should be on Nx version 19.6.

❯

npx nx migrate latest

Migrate a Plugin

Most of the official plugins come with a convert-to-inferred generator. This generator will

  • register the inference plugin in the plugins section of nx.json
  • migrate executor options into the tool's configuration files (where applicable)
  • clean up project.json to remove targets and options that are unnecessary

To get started, run nx g convert-to-inferred, and you'll be prompted to choose a plugin to migrate.

❯

npx nx g convert-to-inferred

1? Which generator would you like to use? … 2@nx/eslint:convert-to-inferred 3@nx/playwright:convert-to-inferred 4@nx/vite:convert-to-inferred 5 6None of the above 7
Third-party plugins

For third-party plugins that provide convert-to-inferred generators, you should pick the None of the above option and type in the name of the package manually. Alternatively, you can also provide the package explicitly with nx g <plugin>:convert-to-inferred.

We recommend that you migrate the plugins one at a time, and check that the configurations are correct before continuing to the next plugin. If you only want to try it on a single project, pass the --project option.

Understand the Migration Process

The convert-to-inferred generator removes uses of executors from the corresponding plugin. For example, if @nx/vite is migrated, then uses of @nx/vite:build, @nx/vite:dev-server, @nx/vite:preview-server, and @nx/vite:test executors will be removed.

Target and configuration names are maintained for each project in their project.json files. A target may be removed from project.json if everything is inferred--that is, options and configurations are not customized. To get the full project details (including all inferred tasks), run:

❯

npx nx show project <project-name>

For example, if we migrated the @nx/vite plugin for a single app (i.e. nx g @nx/vite:convert-to-inferred --project demo), then running nx show project demo will show a screen similar to the following.

Test

demo

Root: apps/demo

Type:application

Targets

  • build

    vite build

  • serve

    vite dev

You'll notice that the serve and build tasks are running the Vite CLI and there are no references to Nx executors. Since the targets directly invoke the Vite CLI, any options that may be passed to it can be passed via Nx commands. e.g. nx serve demo --cors --port 8888 enables CORs and uses port 8888 using Vite CLI options The same CLI setup applies to other plugins as well.

Read the recipe on passing args to commands for more information.

Configuration File Changes

There may also be changes to the configuration files used by the underlying tool. The changes come with comments to explain them, and may also provide next steps for you to take. One common change is to add support for different configuration options. For example, if we have an existing Vite app with the following build target:

project.json
1"build": { 2 "executor": "@nx/vite:build", 3 "options": { 4 "mode": "development" 5 }, 6 "defaultConfiguration": "production", 7 "configurations": { 8 "development": {}, 9 "production": {}, 10 "ci": {} 11 } 12} 13

Where we have development, production, and ci configurations. Then running nx g @nx/vite:convert-to-inferred will result in these lines added to vite.config.ts.

vite.config.ts
1/// <reference types='vitest' /> 2import { defineConfig } from 'vite'; 3import react from '@vitejs/plugin-react'; 4import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin'; 5 6// These options were migrated by @nx/vite:convert-to-inferred from the project.json file. 7const configValues = { default: {}, development: {}, production: {}, ci: {} }; 8 9// Determine the correct configValue to use based on the configuration 10const nxConfiguration = process.env.NX_TASK_TARGET_CONFIGURATION ?? 'default'; 11 12const options = { 13 ...configValues.default, 14 ...(configValues[nxConfiguration] ?? {}), 15}; 16 17export default defineConfig({ 18 root: __dirname, 19 cacheDir: '../../node_modules/.vite/apps/demo', 20 // ... 21}); 22

The configuration changes ensure that passing --configuration still work for the target. Differences in options can be added to the configValues object, and the right value is determined using the NX_TASK_TARGET_CONFIGURATION environment variable. Again, there may be other types of changes so read the comments to understand them.

Register the Plugin with Nx

Lastly, you can inspect the nx.json file to see a new plugins entry. For @nx/vite, there should be an entry like this:

nx.json
1{ 2 "plugin": "@nx/vite/plugin", 3 "options": { 4 "buildTargetName": "build", 5 "serveTargetName": "serve", 6 "previewTargetName": "preview", 7 "testTargetName": "test", 8 "serveStaticTargetName": "serve-static" 9 } 10} 11

You may change the target name options to change how Nx adds them to the project. For example, if you use "serveTargetName": "dev" then you would run nx dev demo rather than nx serve demo for your Vite project.

Verify the Migration

The migrations maintain the same targets and configurations for each project, thus to verify it you should run the affected targets.

For example

  • for @nx/vite you should check the build, serve, and test targets
  • for @nx/playwright you should check the e2e targets
  • for @nx/eslint you should check the lint target
  • etc.

Remember that the target names are defined in the plugin configuration in nx.json.

Make sure that the tasks are all passing before migrating another plugin.

Enable Atomizer (task splitting)

These plugins come with the Atomizer feature.

  • @nx/cypress
  • @nx/jest
  • @nx/gradle
  • @nx/playwright

The Atomizer splits potentially slow tasks into separate tasks per file. This feature along with task distribution can speed up CI by distributing the split tasks among many agents.

To enable Atomizer, make sure that you are connected to Nx Cloud, and that you have distribution enabled in CI. Some plugins require extra configuration to enable Atomizer, so check the individual plugin documentation page for more details.

Connect to Nx CloudEnable task distribution and Atomizer

Troubleshooting

If you run into any issues during the migration, refer to the troubleshooting guide.

Concepts

Recipes

Reference