miel.truyen/nx
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

docs(core): add troubelshooting guide for convert-to-inferred migrations (#26630)

Browse Source 
<!-- Please make sure you have read the submission guidelines before
posting an PR -->
<!--
https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr
-->

<!-- Please make sure that your commit message follows our format -->
<!-- Example: `fix(nx): must begin with lowercase` -->

<!-- If this is a particularly complex change or feature addition, you
can request a dedicated Nx release for this pull request branch. Mention
someone from the Nx team or the `@nrwl/nx-pipelines-reviewers` and they
will confirm if the PR warrants its own release for testing purposes,
and generate it for you if appropriate. -->

## Current Behavior
<!-- This is the behavior we have today -->

## Expected Behavior
<!-- This is the behavior we should expect with the changes in this PR
-->

## Related Issue(s)
<!-- Please link the issue being fixed so it gets closed when this is
merged. -->

Fixes #
This commit is contained in:
Jack Hsu 2024-06-26 14:15:09 -04:00 committed by GitHub
parent 92be32c1a8
commit 04bb1f7cd9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 199 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
docs/generated/manifests/menus.json
View File

@ -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",

30
docs/generated/manifests/nx.json
View File

@ -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",

10
docs/map.json
View File

@ -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"
}
]
},

141
docs/shared/guides/troubleshoot-convert-to-inferred.md Normal file
View File

@ -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...
},
},
],
});
```

2
docs/shared/recipes/console-troubleshooting.md
View File

@ -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.

5
docs/shared/reference/sitemap.md
View File

@ -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)