Nx comes with plugins that automatically infer tasks for your projects based on the configuration of different tools. Inference plugins come with many benefits, such as reduced boilerplate and access to features such as task splitting. To make the transition easier for existing projects that are not yet using inference plugins, many plugins provide the convert-to-inferred generator that will switch from executor-based tasks to inferred tasks.
To see a list of the available migration generators, run:
nx g convert-to-inferredThis will prompt you to choose a plugin to run the migration for.
Although the convert-to-inferred generator should work for most projects, there are situations that require additional changes to be done by hand. If you run into issues that are not covered on this page, please open an issue on GitHub.
Error: The nx plugin did not find a project inside...
Section titled “Error: The nx plugin did not find a project inside...”This error occurs when a configuration file matching the tooling cannot be found. For example, Vite works with vite.config.ts (or .js, .cts, .mts, etc.). If you've named your configuration file to something unconventional, you must rename it back to the standard naming convention before running the migration generator again.
For example, if you have a apps/demo/vite.custom.ts file and are running nx g @nx/vite:convert-to-inferred, you must first rename the file to apps/demo/vite.config.ts before running the generator.
Error: The nx plugin found a project but did not infer a target
Section titled “Error: The nx plugin found a project but did not infer a target”The migration reads each executor target, then asks the plugin to infer the equivalent task from the tool's configuration files. If the plugin finds your project but does not infer a task with the name the migration expects, the migration stops with an error like the following.
The nx plugin found a project inside apps/demo but did not infer a "build" target for it.This is not the same as the missing project error above. The plugin found the project, so the configuration file is already named correctly. The plugin infers only the tasks the tool's configuration file supports, and this configuration file does not support the task the migration is converting. For example, @nx/vite infers no serve task for a configuration that sets build.lib without server.host or server.port, because there is nothing to serve for a library. Check the tool's configuration file for the project and add what the plugin needs to infer that task, or migrate that target by hand. If the configuration already supports the task, open an issue on GitHub with details about your project structure.
Tasks miss the cache after conversion
Section titled “Tasks miss the cache after conversion”An inferred task that lost its plugin's externalDependencies input hashes every external dependency in the workspace, so any change to a resolved package invalidates it. This happens when inputs in targetDefaults or project.json replace the inferred inputs. Add "..." to those inputs to keep the inferred ones, as shown in Keep cache inputs tight.
ESLint and Vitest: tasks run from the project root
Section titled “ESLint and Vitest: tasks run from the project root”Inferred @nx/eslint and @nx/vitest tasks run from the project root. The removed @nx/eslint:lint and @nx/vitest:test executors ran from the workspace root, so anything the tool resolves against the working directory can change after conversion:
- ESLint in legacy eslintrc mode reads
.eslintignorefrom the working directory, so a.eslintignoreat the workspace root no longer applies. - Code that resolves a relative path from a
.envfile against the working directory now gets a path under the project root.
For Vitest, targetDefaults entries scoped to the plugin restore the old working directory. They set cwd to the workspace root and pass the project root to Vitest as --root. If the plugin sets ciTargetName, add the same entry under a second key for the per-file CI tasks, because each of those sets its own cwd:
{ "targetDefaults": { "test": [ { "filter": { "plugin": "@nx/vitest" }, "options": { "cwd": "{workspaceRoot}", "args": ["--root={projectRoot}"] } } ], "test-ci--{*,*/**}": [ { "filter": { "plugin": "@nx/vitest" }, "options": { "cwd": "{workspaceRoot}", "args": ["--root={projectRoot}"] } } ] }}Replace test with your testTargetName and test-ci with your ciTargetName. Keep the {*,*/**} suffix, since the CI task names contain the spec file's path, and a plain * doesn't match across a /. Set filter.plugin to the plugin as it appears in the plugins array of nx.json.
ESLint can't use the same entry, because the inferred command lints ., which from the workspace root is the whole workspace. Instead, copy each ignore pattern that applies to a project into an .eslintignore in that project's root:
- A pattern that starts with the project's path loses that prefix. For example,
libs/a/src/gen/**becomessrc/gen/**or/src/gen/**. - A pattern with no
/, or with only a trailing/, such as*.min.jsordist/, matches at any depth. Copy it unchanged. A leading slash would anchor it to the project root and stop it from matching nested files.
ESLint doesn't report a pattern that matches nothing, so a path pattern copied with its project prefix still in place silently stops applying. A project with its own ESLint configuration can use ignorePatterns there instead. The inferred lint task already tracks a project-root .eslintignore as an input.
Next.js: unable to migrate outputPath, generateLockfile and includeDevDependenciesInPackageJson options
Section titled “Next.js: unable to migrate outputPath, generateLockfile and includeDevDependenciesInPackageJson options”The outputPath option from @nx/next:build is ignored because it conflicts with Next.js' requirement that distDir remain inside the project directory. Previously, the @nx/next:build executor performed workarounds to bring it outside the project root, but those workarounds lead to other issues, such as Turbopack not working.
To customize the output directory, set distDir in your Next.js config file.
/** @type {import('next').NextConfig} */const nextConfig = { // Differentiate production and development builds. You can also use the `NX_TASK_TARGET_CONFIGURATION` variable that will match the `--configuration` option passed to Nx. distDir: process.env.NODE_ENV === 'production' ? 'dist' : 'dist-dev',};
module.exports = nextConfig;Since the output directory is now inside the project, we do not generate package.json since it is already present. The lockfile generation support also no longer exists, which does not affect deployments to Vercel, Netlify, or similar environments. However, it could affect deployments via Docker images where you do not copy the whole monorepo, but rather just the build artifacts.
These removals are necessary to align with Next.js recommendations.
Next.js: Nx serve only starts dev server
Section titled “Next.js: Nx serve only starts dev server”To better align with Next.js CLI, projects after the migration have two targets to start the server:
serve- Starts the dev server (same asnext dev)start- Starts the prod server (same asnext start)
Note that serve could be different depending on what you used for @nx/next:server previously. After the migration, nx run <proj>:serve --prod not longer starts the prod server. Use nx run <proj>:start instead.
Remix: unable to migrate outputPath option
Section titled “Remix: unable to migrate outputPath option”The outputPath option from @nx/remix:build is ignored because it often leads to ESM errors when the output path is outside the project root. The ESM error occurs because the root package.json may not have "type": "module" set, which means that the compiled ESM code will fail to run. To guarantee that serve works, we migrate the outputs to the Remix defaults (build and public/build inside the project root). If you have custom directories already defined in your Remix config, it will continue to be used.
To change the outputs after the migration, edit the remix config file, and look for serverBuildPath and assetsBuildDirectory and set it to the locations you want.
// ...export default { assetsBuildDirectory: '../../dist/apps/demo/public/build', serverBuildPath: '../../dist/apps/demo/build/index.js', // ...};Note that you will need to address potential ESM issues that may arise. For example, change the root package.json to "type": "module".
Remix: unsupported generatePackageJson and generateLockfile options
Section titled “Remix: unsupported generatePackageJson and generateLockfile options”The generatePackageJson and generateLockfile options in @nx/remix:build cannot be migrated. To keep the project's package.json dependencies in sync, use the @nx/dependency-checks ESLint rule. Lock file generation has no replacement.
Storybook: conflicting staticDir options
Section titled “Storybook: conflicting staticDir options”Using staticDir for both @nx/storybook:build-storybook and @nx/storybook:storybook executor options will result in the one from build-storybook being used in the resulting .storybook/main.ts file. It is not possible for us to support both automatically.
If you need to differentiate staticDir between build and serve, then consider putting logic into your main.ts file directly.
// ...const config: StorybookConfig = { // ... staticDirs: process.env.NODE_ENV === 'production' ? ['../static-prod'] : ['../static-dev'],};
export default config;Vite: unsupported proxyConfig option
Section titled “Vite: unsupported proxyConfig option”Projects that used the proxyConfig option of @nx/vite:dev-server will need to inline the proxy configuration from the original file into vite.config.ts.
For example, if you previously used this in proxy.config.json:
{ "/api/*": { "target": "http://localhost:3333" }}Then, you will need to add this entry to your vite.config.ts file:
export default defineConfig({ //... server: { // ... proxy: { '/api': { target: 'http://localhost:3333', }, }, },});Webpack: project cannot be migrated
Section titled “Webpack: project cannot be migrated”Projects that use Nx-enhanced Webpack configuration files cannot be migrated to use Webpack CLI. Those configuration files call composePlugins and withNx, which Nx v24 removed.
To solve this issue, run nx g @nx/webpack:convert-config-to-webpack-plugin first, and then try again.
Webpack: usage of useLegacyNxPlugin
Section titled “Webpack: usage of useLegacyNxPlugin”When converting from Nx-enhanced to basic Webpack configuration, we add the useLegacyNxPlugin utility function to ensure that your build tasks behave the same after the migration. We recommend that you refactor the configuration such that useLegacyNxPlugin is not needed.
For example, if you previously added plugins using the configuration function.
modules.exports = (config) => { config.plugins.push(new SomePlugin()); return config;};Then, we recommend that you move the plugin entry to the new configuration file, in the plugins option.
module.exports = async () => ({ devServer: devServerOptions, plugins: [new NxAppWebpackPlugin(pluginOptions), new SomePlugin()],});If you need to apply configuration changes after NxAppWebpackPlugin is applied, then you can create a plugin object as follows.
module.exports = async () => ({ devServer: devServerOptions, plugins: [ new NxAppWebpackPlugin(pluginOptions), { apply(compiler) { const babelLoader = compiler.options.module.rules.find( (rule) => rule && typeof rule !== 'string' && rule.loader?.toString().includes('babel-loader') );
// do something with `babelLoader... }, }, ],});