diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index feb57ce92a..6702bcd516 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -3588,7 +3588,7 @@ "disableCollapsible": false }, { - "name": "Troubleshooting Nx Console Issues", + "name": "Troubleshoot Nx Console Issues", "path": "/recipes/nx-console/console-troubleshooting", "id": "console-troubleshooting", "isExternal": false, @@ -4458,7 +4458,7 @@ "disableCollapsible": false }, { - "name": "Troubleshooting Nx Install Issues", + "name": "Troubleshoot Nx Install Issues", "path": "/troubleshooting/troubleshoot-nx-install-issues", "id": "troubleshoot-nx-install-issues", "isExternal": false, @@ -4490,12 +4490,20 @@ "disableCollapsible": false }, { - "name": "Troubleshooting Nx Console Issues", + "name": "Troubleshoot Nx Console Issues", "path": "/recipes/nx-console/console-troubleshooting", "id": "console-troubleshooting", "isExternal": false, "children": [], "disableCollapsible": false + }, + { + "name": "Troubleshoot Convert to Inferred Migration", + "path": "/troubleshooting/convert-to-inferred", + "id": "convert-to-inferred", + "isExternal": false, + "children": [], + "disableCollapsible": false } ], "disableCollapsible": false @@ -4509,7 +4517,7 @@ "disableCollapsible": false }, { - "name": "Troubleshooting Nx Install Issues", + "name": "Troubleshoot Nx Install Issues", "path": "/troubleshooting/troubleshoot-nx-install-issues", "id": "troubleshoot-nx-install-issues", "isExternal": false, @@ -4540,6 +4548,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Troubleshoot Convert to Inferred Migration", + "path": "/troubleshooting/convert-to-inferred", + "id": "convert-to-inferred", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Deprecated", "path": "/deprecated", diff --git a/docs/generated/manifests/nx.json b/docs/generated/manifests/nx.json index e56d2fcaa7..420cdab51d 100644 --- a/docs/generated/manifests/nx.json +++ b/docs/generated/manifests/nx.json @@ -4912,7 +4912,7 @@ }, "/recipes/nx-console/console-troubleshooting": { "id": "console-troubleshooting", - "name": "Troubleshooting Nx Console Issues", + "name": "Troubleshoot Nx Console Issues", "description": "", "mediaImage": "", "file": "shared/recipes/console-troubleshooting", @@ -6104,7 +6104,7 @@ }, { "id": "troubleshoot-nx-install-issues", - "name": "Troubleshooting Nx Install Issues", + "name": "Troubleshoot Nx Install Issues", "description": "", "mediaImage": "", "file": "shared/installation/troubleshoot-installation", @@ -6148,7 +6148,7 @@ }, { "id": "console-troubleshooting", - "name": "Troubleshooting Nx Console Issues", + "name": "Troubleshoot Nx Console Issues", "description": "", "mediaImage": "", "file": "shared/recipes/console-troubleshooting", @@ -6156,6 +6156,17 @@ "isExternal": false, "path": "/recipes/nx-console/console-troubleshooting", "tags": [] + }, + { + "id": "convert-to-inferred", + "name": "Troubleshoot Convert to Inferred Migration", + "description": "", + "mediaImage": "", + "file": "shared/guides/troubleshoot-convert-to-inferred", + "itemList": [], + "isExternal": false, + "path": "/troubleshooting/convert-to-inferred", + "tags": [] } ], "isExternal": false, @@ -6175,7 +6186,7 @@ }, "/troubleshooting/troubleshoot-nx-install-issues": { "id": "troubleshoot-nx-install-issues", - "name": "Troubleshooting Nx Install Issues", + "name": "Troubleshoot Nx Install Issues", "description": "", "mediaImage": "", "file": "shared/installation/troubleshoot-installation", @@ -6217,6 +6228,17 @@ "path": "/troubleshooting/performance-profiling", "tags": ["environment-variables"] }, + "/troubleshooting/convert-to-inferred": { + "id": "convert-to-inferred", + "name": "Troubleshoot Convert to Inferred Migration", + "description": "", + "mediaImage": "", + "file": "shared/guides/troubleshoot-convert-to-inferred", + "itemList": [], + "isExternal": false, + "path": "/troubleshooting/convert-to-inferred", + "tags": [] + }, "/deprecated": { "id": "deprecated", "name": "Deprecated", diff --git a/docs/map.json b/docs/map.json index c747f868d9..8908a25534 100644 --- a/docs/map.json +++ b/docs/map.json @@ -1264,7 +1264,7 @@ "file": "shared/recipes/resolve-circular-dependencies" }, { - "name": "Troubleshooting Nx Install Issues", + "name": "Troubleshoot Nx Install Issues", "id": "troubleshoot-nx-install-issues", "file": "shared/installation/troubleshoot-installation" }, @@ -1287,10 +1287,16 @@ "file": "shared/guides/performance-profiling" }, { - "name": "Troubleshooting Nx Console Issues", + "name": "Troubleshoot Nx Console Issues", "id": "console-troubleshooting", "path": "/recipes/nx-console/console-troubleshooting", "file": "shared/recipes/console-troubleshooting" + }, + { + "name": "Troubleshoot Convert to Inferred Migration", + "id": "convert-to-inferred", + "tags": [], + "file": "shared/guides/troubleshoot-convert-to-inferred" } ] }, diff --git a/docs/shared/guides/troubleshoot-convert-to-inferred.md b/docs/shared/guides/troubleshoot-convert-to-inferred.md new file mode 100644 index 0000000000..c82be96268 --- /dev/null +++ b/docs/shared/guides/troubleshoot-convert-to-inferred.md @@ -0,0 +1,141 @@ +# Troubleshoot Convert to Inferred Migration + +Nx comes with plugins that automatically [infer tasks](/concepts/inferred-tasks) (i.e. Project Crystal) 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](/ci/features/split-e2e-tasks). 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: + +```shell +nx g convert-to-inferred +``` + +This 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](https://github.com/nrwl/nx/issues). + +## 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. + +## Remix: Unsupported `outputPath` Option + +The [`outputPath`](/nx-api/remix/executors/build#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. + +```ts +// ... +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 + +The `generatePackageJson` and `generateLockFile` options in [`@nx/remix:build`](/nx-api/remix/executors/build) cannot currently be migrated. There is support for this feature in the [Nx Vite plugin](/recipes/vite/configure-vite#typescript-paths), so in the future we may be able to support it if using Remix+Vite. + +## 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. + +```ts +// ... +const config: StorybookConfig = { + // ... + staticDirs: + process.env.NODE_ENV === 'production' + ? ['../static-prod'] + : ['../static-dev'], +}; + +export default config; +``` + +## Vite: Unsupported `proxyConfig` Option + +Projects that used the [`proxyConfig`](/nx-api/vite/executors/dev-server#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`: + +```json +{ + "/api/*": { + "target": "http://localhost:3333" + } +} +``` + +Then, you will need to add this entry to your `vite.config.ts` file: + +```ts +export default defineConfig({ + //... + server: { + // ... + proxy: { + '/api': { + target: 'http://localhost:3333', + }, + }, + }, +}); +``` + +## Webpack: Project Cannot Be Migrated + +Projects that use [Nx-enhanced Webpack configuration](/recipes/webpack/webpack-config-setup#nxenhanced-configuration-with-composable-plugins) files cannot be migrated to use Webpack CLI. Nx-enhanced configuration files that contain `composePlugins` and `withNx` require the `@nx/webpack:webpack` executor to work. + +To solve this issue, run `nx g @nx/webpack:convert-config-to-webpack-plugin` first, and then try again. + +## Webpack: Usage of `useLegacyNxPlugin` + +When converting from Nx-enhanced to basic Webpack configuration, we add the `useLegacyNxPlugin` utility to ensure that the functionality of your existing configuration continues to function normally. We recommend that you refactor the configuration such that `useLegacyNxPlugin` is not needed. + +For example, if you previously added plugins using the configuration function. + +```js +// webpack.config.old.js +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. + +```js +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. + +```js +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... + }, + }, + ], +}); +``` diff --git a/docs/shared/recipes/console-troubleshooting.md b/docs/shared/recipes/console-troubleshooting.md index bb079c98c3..661867268f 100644 --- a/docs/shared/recipes/console-troubleshooting.md +++ b/docs/shared/recipes/console-troubleshooting.md @@ -1,4 +1,4 @@ -# Nx Console Troubleshooting +# Troubleshoot Nx Console Issues Often, issues with Nx Console are the result of underlying issues with Nx. Make sure to read the [Nx installation troubleshooting docs](/troubleshooting/troubleshoot-nx-install-issues) for more help. diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index c0fe925927..480a45380c 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -166,7 +166,7 @@ - [Publish a Custom Dist Directory](/recipes/nx-release/publish-custom-dist-directory) - [Other](/recipes/other) - [Rescope Packages from @nrwl to @nx](/recipes/other/rescope) - - [Troubleshooting Nx Console Issues](/recipes/nx-console/console-troubleshooting) + - [Troubleshoot Nx Console Issues](/recipes/nx-console/console-troubleshooting) - [Showcase](/showcase) - [Nx with your favorite tech](/showcase/example-repos) - [Express](/showcase/example-repos/add-express) @@ -199,10 +199,11 @@ - [Releases](/reference/releases) - [Troubleshooting](/troubleshooting) - [Resolve Circular Dependencies](/troubleshooting/resolve-circular-dependencies) - - [Troubleshooting Nx Install Issues](/troubleshooting/troubleshoot-nx-install-issues) + - [Troubleshoot Nx Install Issues](/troubleshooting/troubleshoot-nx-install-issues) - [Troubleshoot Cache Misses](/troubleshooting/troubleshoot-cache-misses) - [Unknown Local Cache Error](/troubleshooting/unknown-local-cache) - [Profiling Build Performance](/troubleshooting/performance-profiling) + - [Troubleshoot Convert to Inferred Migration](/troubleshooting/convert-to-inferred) - [Deprecated](/deprecated) - [affected:graph](/deprecated/affected-graph) - [print-affected](/deprecated/print-affected)