diff --git a/docs/generated/packages/angular.json b/docs/generated/packages/angular.json index c059913c84..e9a568dd8f 100644 --- a/docs/generated/packages/angular.json +++ b/docs/generated/packages/angular.json @@ -11,7 +11,7 @@ "id": "overview", "path": "/packages/angular", "file": "shared/angular-plugin", - "content": "The Nx Plugin for Angular contains executors, generators, and utilities for managing Angular applications and libraries within an Nx workspace. It provides:\n\n- Integration with libraries such as Storybook, Jest, Cypress, Karma, and Protractor.\n- Generators to help scaffold code quickly, including:\n - Micro Frontends\n - Libraries, both internal to your codebase and publishable to npm\n - Upgrading AngularJS applications\n - Single Component Application Modules (SCAMs)\n- NgRx helpers.\n- Utilities for automatic workspace refactoring.\n\n{% callout type=\"note\" title=\"Currently using the Angular CLI?\" %}\nYou can easily and mostly **automatically migrate from an Angular CLI** project to Nx! Learn more [here](/recipe/migration-angular).\n{% /callout %}\n\n## Setting up the Angular plugin\n\nAdding the Angular plugin to an existing Nx workspace can be done with the following:\n\n```bash\nyarn add -D @nrwl/angular\n```\n\n```bash\nnpm install -D @nrwl/angular\n```\n\n## Using the Angular Plugin\n\n### Generating an application\n\nIt's straightforward to generate an Angular application:\n\n```bash\nnx g @nrwl/angular:app appName\n```\n\nBy default, the application will be generated with:\n\n- ESLint as the linter.\n- Jest as the unit test runner.\n- Cypress as the E2E test runner.\n\nWe can then serve, build, test, lint, and run e2e tests on the application with the following commands:\n\n```bash\nnx serve appName\nnx build appName\nnx test appName\nnx lint appName\nnx e2e appName\n```\n\n### Generating a library\n\nGenerating an Angular library is very similar to generating an application:\n\n```bash\nnx g @nrwl/angular:lib libName\n```\n\nBy default, the library will be generated with:\n\n- ESLint as the linter.\n- Jest as the unit test runner.\n\nWe can then test and lint the library with the following commands:\n\n```bash\nnx test libName\nnx lint libName\n```\n\nRead more about:\n\n- [Creating Libraries](/more-concepts/creating-libraries)\n- [Library Types](/more-concepts/library-types)\n- [Buildable and Publishable Libraries](/more-concepts/buildable-and-publishable-libraries)\n\n## More Documentation\n\n- [Angular Nx Tutorial](/angular-tutorial/01-create-application)\n- [Migrating from the Angular CLI](recipe/migration-angular)\n- [Setup Module Federation with Angular and Nx](/recipe/faster-builds)\n- [Using NgRx](/recipe/misc-ngrx)\n- [Using Data Persistence operators](/recipe/misc-data-persistence)\n- [Upgrading an AngularJS application to Angular](/recipe/migration-angularjs)\n- [Using Tailwind CSS with Angular projects](/recipe/using-tailwind-css-with-angular-projects)\n" + "content": "The Nx Plugin for Angular contains executors, generators, and utilities for managing Angular applications and libraries within an Nx workspace. It provides:\n\n- Integration with libraries such as Storybook, Jest, Cypress, Karma, and Protractor.\n- Generators to help scaffold code quickly, including:\n - Micro Frontends\n - Libraries, both internal to your codebase and publishable to npm\n - Upgrading AngularJS applications\n - Single Component Application Modules (SCAMs)\n- NgRx helpers.\n- Utilities for automatic workspace refactoring.\n\n{% callout type=\"note\" title=\"Currently using the Angular CLI?\" %}\nYou can easily and mostly **automatically migrate from an Angular CLI** project to Nx! Learn more [here](/recipes/adopting-nx/migration-angular).\n{% /callout %}\n\n## Setting up the Angular plugin\n\nAdding the Angular plugin to an existing Nx workspace can be done with the following:\n\n```bash\nyarn add -D @nrwl/angular\n```\n\n```bash\nnpm install -D @nrwl/angular\n```\n\n## Using the Angular Plugin\n\n### Generating an application\n\nIt's straightforward to generate an Angular application:\n\n```bash\nnx g @nrwl/angular:app appName\n```\n\nBy default, the application will be generated with:\n\n- ESLint as the linter.\n- Jest as the unit test runner.\n- Cypress as the E2E test runner.\n\nWe can then serve, build, test, lint, and run e2e tests on the application with the following commands:\n\n```bash\nnx serve appName\nnx build appName\nnx test appName\nnx lint appName\nnx e2e appName\n```\n\n### Generating a library\n\nGenerating an Angular library is very similar to generating an application:\n\n```bash\nnx g @nrwl/angular:lib libName\n```\n\nBy default, the library will be generated with:\n\n- ESLint as the linter.\n- Jest as the unit test runner.\n\nWe can then test and lint the library with the following commands:\n\n```bash\nnx test libName\nnx lint libName\n```\n\nRead more about:\n\n- [Creating Libraries](/more-concepts/creating-libraries)\n- [Library Types](/more-concepts/library-types)\n- [Buildable and Publishable Libraries](/more-concepts/buildable-and-publishable-libraries)\n\n## More Documentation\n\n- [Angular Nx Tutorial](/angular-tutorial/01-create-application)\n- [Migrating from the Angular CLI](recipe/migration-angular)\n- [Setup Module Federation with Angular and Nx](/recipes/module-federation/faster-builds)\n- [Using NgRx](/recipes/other/misc-ngrx)\n- [Using Data Persistence operators](/recipes/other/misc-data-persistence)\n- [Upgrading an AngularJS application to Angular](/recipes/adopting-nx/migration-angularjs)\n- [Using Tailwind CSS with Angular projects](/recipes/other/using-tailwind-css-with-angular-projects)\n" }, { "name": "Angular and Nx Version Matrix", diff --git a/docs/generated/packages/eslint-plugin-nx.json b/docs/generated/packages/eslint-plugin-nx.json index c9b729c2e9..619247dc2f 100644 --- a/docs/generated/packages/eslint-plugin-nx.json +++ b/docs/generated/packages/eslint-plugin-nx.json @@ -11,7 +11,7 @@ "name": "Overview", "path": "/packages/eslint-plugin-nx", "file": "shared/eslint-plugin-nx", - "content": "A plugin containing a collection of recommended ESLint rule configurations wrapped as ESLint plugins and an Nx specific [enforce-module-boundaries](#enforce-module-boundaries) rule.\n\n## Setting Up ESLint Plugin\n\n### Installation\n\nIn any Nx workspace, you can install `@nrwl/eslint-plugin-nx` by running the following commands if the package is not already installed:\n\n{% tabs %}\n{%tab label=\"npm\"%}\n\n````bash\n```bash\nnpm i --save-dev @nrwl/eslint-plugin-nx\n````\n\n{% /tab %}\n{%tab label=\"yarn\"%}\n\n```bash\nyarn add --dev @nrwl/eslint-plugin-nx\n```\n\n{% /tab %}\n{% /tabs %}\n\n## ESLint plugins\n\nThe plugin contains the following rule configurations divided into sub-plugins.\n\n### JavaScript\n\nThe `@nrwl/nx/javascript` ESLint plugin contains best practices when using JavaScript.\n\n### TypeScript\n\nThe `@nrwl/nx/typescript` ESLint plugin contains best practices when using TypeSript.\n\n### Angular\n\nContains configurations matching best practices when using Angular framework:\n\n- @nrwl/nx/angular\n- @nrwl/nx/angular-template\n\n### React\n\nContains configurations matching best practices when using React framework:\n\n- @nrwl/nx/react-base\n- @nrwl/nx/react-jsx\n- @nrwl/nx/react-typescript\n\nYou can also use `@nrwl/nx/react` which includes all three `@nrwl/nx/react-*` plugins\n\n## enforce-module-boundaries\n\nThe `@nrwl/nx/enforce-module-boundaries` ESLint rule enables you to define strict rules for accessing resources between different projects in the repository. By enforcing strict boundaries it helps keep prevent unplanned cross-dependencies.\n\n### Usage\n\nYou can use `enforce-module-boundaries` rule by adding it to your ESLint rules configuration:\n\n```json\n{\n // ... more ESLint config here\n \"overrides\": [\n {\n \"files\": [\"*.ts\", \"*.tsx\", \"*.js\", \"*.jsx\"],\n \"rules\": {\n \"@nrwl/nx/enforce-module-boundaries\": [\n \"error\",\n {\n // ...rule specific configuration\n }\n ]\n }\n }\n // ... more ESLint overrides here\n ]\n}\n```\n\nRead more about proper usage of this rule:\n\n- [Enforce Project Boundaries](/core-features/enforce-project-boundaries)\n- [Ban Dependencies with Certain Tags](/recipe/ban-dependencies-with-tags)\n- [Tag in Multiple Dimensions](/recipe/tag-multiple-dimensions)\n- [Ban External Imports](/recipe/ban-external-imports)\n- [Tags Allow List](/recipe/tags-allow-list)\n- [Taming Code Organization with Module Boundaries in Nx](https://blog.nrwl.io/mastering-the-project-boundaries-in-nx-f095852f5bf4)\n" + "content": "A plugin containing a collection of recommended ESLint rule configurations wrapped as ESLint plugins and an Nx specific [enforce-module-boundaries](#enforce-module-boundaries) rule.\n\n## Setting Up ESLint Plugin\n\n### Installation\n\nIn any Nx workspace, you can install `@nrwl/eslint-plugin-nx` by running the following commands if the package is not already installed:\n\n{% tabs %}\n{%tab label=\"npm\"%}\n\n````bash\n```bash\nnpm i --save-dev @nrwl/eslint-plugin-nx\n````\n\n{% /tab %}\n{%tab label=\"yarn\"%}\n\n```bash\nyarn add --dev @nrwl/eslint-plugin-nx\n```\n\n{% /tab %}\n{% /tabs %}\n\n## ESLint plugins\n\nThe plugin contains the following rule configurations divided into sub-plugins.\n\n### JavaScript\n\nThe `@nrwl/nx/javascript` ESLint plugin contains best practices when using JavaScript.\n\n### TypeScript\n\nThe `@nrwl/nx/typescript` ESLint plugin contains best practices when using TypeSript.\n\n### Angular\n\nContains configurations matching best practices when using Angular framework:\n\n- @nrwl/nx/angular\n- @nrwl/nx/angular-template\n\n### React\n\nContains configurations matching best practices when using React framework:\n\n- @nrwl/nx/react-base\n- @nrwl/nx/react-jsx\n- @nrwl/nx/react-typescript\n\nYou can also use `@nrwl/nx/react` which includes all three `@nrwl/nx/react-*` plugins\n\n## enforce-module-boundaries\n\nThe `@nrwl/nx/enforce-module-boundaries` ESLint rule enables you to define strict rules for accessing resources between different projects in the repository. By enforcing strict boundaries it helps keep prevent unplanned cross-dependencies.\n\n### Usage\n\nYou can use `enforce-module-boundaries` rule by adding it to your ESLint rules configuration:\n\n```json\n{\n // ... more ESLint config here\n \"overrides\": [\n {\n \"files\": [\"*.ts\", \"*.tsx\", \"*.js\", \"*.jsx\"],\n \"rules\": {\n \"@nrwl/nx/enforce-module-boundaries\": [\n \"error\",\n {\n // ...rule specific configuration\n }\n ]\n }\n }\n // ... more ESLint overrides here\n ]\n}\n```\n\nRead more about proper usage of this rule:\n\n- [Enforce Project Boundaries](/core-features/enforce-project-boundaries)\n- [Ban Dependencies with Certain Tags](/recipes/other/ban-dependencies-with-tags)\n- [Tag in Multiple Dimensions](/recipes/other/tag-multiple-dimensions)\n- [Ban External Imports](/recipes/other/ban-external-imports)\n- [Tags Allow List](/recipes/other/tags-allow-list)\n- [Taming Code Organization with Module Boundaries in Nx](https://blog.nrwl.io/mastering-the-project-boundaries-in-nx-f095852f5bf4)\n" } ], "generators": [], diff --git a/docs/generated/packages/linter.json b/docs/generated/packages/linter.json index a18bd676b0..ebe320cf8f 100644 --- a/docs/generated/packages/linter.json +++ b/docs/generated/packages/linter.json @@ -17,7 +17,7 @@ "id": "eslint-plugin-nx", "name": "eslint-plugin-nx", "file": "shared/eslint-plugin-nx", - "content": "A plugin containing a collection of recommended ESLint rule configurations wrapped as ESLint plugins and an Nx specific [enforce-module-boundaries](#enforce-module-boundaries) rule.\n\n## Setting Up ESLint Plugin\n\n### Installation\n\nIn any Nx workspace, you can install `@nrwl/eslint-plugin-nx` by running the following commands if the package is not already installed:\n\n{% tabs %}\n{%tab label=\"npm\"%}\n\n````bash\n```bash\nnpm i --save-dev @nrwl/eslint-plugin-nx\n````\n\n{% /tab %}\n{%tab label=\"yarn\"%}\n\n```bash\nyarn add --dev @nrwl/eslint-plugin-nx\n```\n\n{% /tab %}\n{% /tabs %}\n\n## ESLint plugins\n\nThe plugin contains the following rule configurations divided into sub-plugins.\n\n### JavaScript\n\nThe `@nrwl/nx/javascript` ESLint plugin contains best practices when using JavaScript.\n\n### TypeScript\n\nThe `@nrwl/nx/typescript` ESLint plugin contains best practices when using TypeSript.\n\n### Angular\n\nContains configurations matching best practices when using Angular framework:\n\n- @nrwl/nx/angular\n- @nrwl/nx/angular-template\n\n### React\n\nContains configurations matching best practices when using React framework:\n\n- @nrwl/nx/react-base\n- @nrwl/nx/react-jsx\n- @nrwl/nx/react-typescript\n\nYou can also use `@nrwl/nx/react` which includes all three `@nrwl/nx/react-*` plugins\n\n## enforce-module-boundaries\n\nThe `@nrwl/nx/enforce-module-boundaries` ESLint rule enables you to define strict rules for accessing resources between different projects in the repository. By enforcing strict boundaries it helps keep prevent unplanned cross-dependencies.\n\n### Usage\n\nYou can use `enforce-module-boundaries` rule by adding it to your ESLint rules configuration:\n\n```json\n{\n // ... more ESLint config here\n \"overrides\": [\n {\n \"files\": [\"*.ts\", \"*.tsx\", \"*.js\", \"*.jsx\"],\n \"rules\": {\n \"@nrwl/nx/enforce-module-boundaries\": [\n \"error\",\n {\n // ...rule specific configuration\n }\n ]\n }\n }\n // ... more ESLint overrides here\n ]\n}\n```\n\nRead more about proper usage of this rule:\n\n- [Enforce Project Boundaries](/core-features/enforce-project-boundaries)\n- [Ban Dependencies with Certain Tags](/recipe/ban-dependencies-with-tags)\n- [Tag in Multiple Dimensions](/recipe/tag-multiple-dimensions)\n- [Ban External Imports](/recipe/ban-external-imports)\n- [Tags Allow List](/recipe/tags-allow-list)\n- [Taming Code Organization with Module Boundaries in Nx](https://blog.nrwl.io/mastering-the-project-boundaries-in-nx-f095852f5bf4)\n" + "content": "A plugin containing a collection of recommended ESLint rule configurations wrapped as ESLint plugins and an Nx specific [enforce-module-boundaries](#enforce-module-boundaries) rule.\n\n## Setting Up ESLint Plugin\n\n### Installation\n\nIn any Nx workspace, you can install `@nrwl/eslint-plugin-nx` by running the following commands if the package is not already installed:\n\n{% tabs %}\n{%tab label=\"npm\"%}\n\n````bash\n```bash\nnpm i --save-dev @nrwl/eslint-plugin-nx\n````\n\n{% /tab %}\n{%tab label=\"yarn\"%}\n\n```bash\nyarn add --dev @nrwl/eslint-plugin-nx\n```\n\n{% /tab %}\n{% /tabs %}\n\n## ESLint plugins\n\nThe plugin contains the following rule configurations divided into sub-plugins.\n\n### JavaScript\n\nThe `@nrwl/nx/javascript` ESLint plugin contains best practices when using JavaScript.\n\n### TypeScript\n\nThe `@nrwl/nx/typescript` ESLint plugin contains best practices when using TypeSript.\n\n### Angular\n\nContains configurations matching best practices when using Angular framework:\n\n- @nrwl/nx/angular\n- @nrwl/nx/angular-template\n\n### React\n\nContains configurations matching best practices when using React framework:\n\n- @nrwl/nx/react-base\n- @nrwl/nx/react-jsx\n- @nrwl/nx/react-typescript\n\nYou can also use `@nrwl/nx/react` which includes all three `@nrwl/nx/react-*` plugins\n\n## enforce-module-boundaries\n\nThe `@nrwl/nx/enforce-module-boundaries` ESLint rule enables you to define strict rules for accessing resources between different projects in the repository. By enforcing strict boundaries it helps keep prevent unplanned cross-dependencies.\n\n### Usage\n\nYou can use `enforce-module-boundaries` rule by adding it to your ESLint rules configuration:\n\n```json\n{\n // ... more ESLint config here\n \"overrides\": [\n {\n \"files\": [\"*.ts\", \"*.tsx\", \"*.js\", \"*.jsx\"],\n \"rules\": {\n \"@nrwl/nx/enforce-module-boundaries\": [\n \"error\",\n {\n // ...rule specific configuration\n }\n ]\n }\n }\n // ... more ESLint overrides here\n ]\n}\n```\n\nRead more about proper usage of this rule:\n\n- [Enforce Project Boundaries](/core-features/enforce-project-boundaries)\n- [Ban Dependencies with Certain Tags](/recipes/other/ban-dependencies-with-tags)\n- [Tag in Multiple Dimensions](/recipes/other/tag-multiple-dimensions)\n- [Ban External Imports](/recipes/other/ban-external-imports)\n- [Tags Allow List](/recipes/other/tags-allow-list)\n- [Taming Code Organization with Module Boundaries in Nx](https://blog.nrwl.io/mastering-the-project-boundaries-in-nx-f095852f5bf4)\n" } ], "generators": [ diff --git a/docs/generated/packages/next.json b/docs/generated/packages/next.json index cb1fa58b73..dd18a104a8 100644 --- a/docs/generated/packages/next.json +++ b/docs/generated/packages/next.json @@ -11,7 +11,7 @@ "name": "Overview", "path": "/packages/next", "file": "shared/next-plugin", - "content": "When using Next.js in Nx, you get the out-of-the-box support for TypeScript, Cypress, and Jest. No need to configure anything: watch mode, source maps, and typings just work.\n\nThe Next.js plugin contains executors and generators for managing Next.js applications and libraries within an Nx workspace. It provides:\n\n- Scaffolding for creating, building, serving, linting, and testing Next.js applications.\n- Integration with building, serving, and exporting a Next.js application.\n- Integration with React libraries within the workspace.\n\n## Setting up Next.js\n\nTo create a new Nx workspace with Next.js, run `npx create-nx-workspace@latest --preset=next`.\n\nTo add Next.js to an existing Nx workspace, install the `@nrwl/next` package. Make sure to install the version that matches your `@nrwl/workspace` version.\n\n```bash\n#yarn\nyarn add --dev @nrwl/next\n```\n\n```bash\n#npm\nnpm install --save-dev @nrwl/next\n```\n\n### Creating Applications\n\nYou can add a new application with the following:\n\n```bash\nnx g @nrwl/next:app my-new-app\n```\n\n### Generating Libraries\n\nNx allows you to create libraries with just one command. Some reasons you might want to create a library include:\n\n- Share code between applications\n- Publish a package to be used outside the monorepo\n- Better visualize the architecture using `nx graph`\n\nFor more information on Nx libraries, see our documentation on [Creating Libraries](/more-concepts/creating-libraries)\nand [Library Types](/more-concepts/library-types).\n\nTo generate a new library run:\n\n```bash\nnx g @nrwl/next:lib my-new-lib\n```\n\n### Generating Pages and Components\n\nNx also provides commands to quickly generate new pages and components for your application.\n\n```bash\nnx g @nrwl/next:page my-new-page --project=my-new-app\n\nnx g @nrwl/next:component my-new-component --project=my-new-app\n```\n\nAbove commands will add a new page `my-new-page` and a component `my-new-component` to `my-new-app` project respectively.\n\nNx generates components with tests by default. For pages, you can pass the `--withTests` option to generate tests under the `specs` folder.\n\n## Using Next.js\n\n### Serving Next.js Applications\n\nYou can run `nx serve my-new-app` to serve a Next.js application called `my-new-app` for development. This will start the dev server at http://localhost:4200.\n\nTo serve a Next.js application for production, add the `--prod` flag to the serve command:\n\n```bash\nnx serve my-new-app --prod\n```\n\n### Using an Nx Library in your Application\n\nYou can import a library called `my-new-lib` in your application as follows.\n\n```typescript jsx\n// apps/my-next-app/pages/index.tsx\nimport { MyNewLib } from '@/my-new-lib';\n\nexport function Index() {\n return (\n \n

The main content

\n \n );\n}\n\nexport default Index;\n```\n\nThere is no need to build the library prior to using it. When you update your library, the Next.js application will automatically pick up the changes.\n\n### Publishable libraries\n\nFor libraries intended to be built and published to a registry (e.g. npm) you can use the `--publishable` and `--importPath` options.\n\n```bash\nnx g @nrwl/next:lib my-new-lib --publishable --importPath=@happynrwl/ui-components\n```\n\n### Testing Projects\n\nYou can run unit tests with:\n\n```bash\nnx test my-new-app\nnx test my-new-lib\n```\n\nReplace `my-new-app` and `my-new-lib` with the name or the project you want to test. This command works for both applications and libraries.\n\nYou can also run E2E tests for applications:\n\n```bash\nnx e2e my-new-app-e2e\n```\n\nReplace `my-new-app-e2e` with the name or your project with -e2e appended.\n\n### Linting Projects\n\nYou can lint projects with:\n\n```bash\nnx lint my-new-app\nnx lint my-new-lib\n```\n\nReplace `my-new-app` and `my-new-lib` with the name or the project you want to test. This command works for both applications and libraries.\n\n### Building Projects\n\nNext.js applications can be build with:\n\n```bash\nnx build my-new-app\n```\n\nAnd if you generated a library with --buildable, then you can build a library as well:\n\n```bash\nnx build my-new-lib\n```\n\nAfter running a build, the output will be in the `dist` folder. You can customize the output folder by setting `outputPath` in the project's `project.json` file.\n\nThe library in `dist` is publishable to npm or a private registry.\n\n### Static HTML Export\n\nNext.js applications can be statically exported with:\n\n```bash\nnx export my-new-app\n```\n\n### Deploying Next.js Applications\n\nOnce you are ready to deploy your Next.js application, you have absolute freedom to choose any hosting provider that fits your needs.\n\nYou may know that the company behind Next.js, Vercel, has a great hosting platform offering that is developed in tandem with Next.js itself to offer a great overall developer and user experience. We have detailed [how to deploy your Next.js application to Vercel in a separate guide](/recipe/deploy-nextjs-to-vercel).\n\n## More Documentation\n\nHere are other resources that you may find useful to learn more about Next.js and Nx.\n\n- **Blog post:** [Building a blog with Next.js and Nx Series](https://blog.nrwl.io/create-a-next-js-web-app-with-nx-bcf2ab54613) by Juri Strumpflohner\n- **Video tutorial:** [Typescript NX Monorepo with NextJS and Express](https://www.youtube.com/watch?v=WOfL5q2HznI) by Jack Herrington\n" + "content": "When using Next.js in Nx, you get the out-of-the-box support for TypeScript, Cypress, and Jest. No need to configure anything: watch mode, source maps, and typings just work.\n\nThe Next.js plugin contains executors and generators for managing Next.js applications and libraries within an Nx workspace. It provides:\n\n- Scaffolding for creating, building, serving, linting, and testing Next.js applications.\n- Integration with building, serving, and exporting a Next.js application.\n- Integration with React libraries within the workspace.\n\n## Setting up Next.js\n\nTo create a new Nx workspace with Next.js, run `npx create-nx-workspace@latest --preset=next`.\n\nTo add Next.js to an existing Nx workspace, install the `@nrwl/next` package. Make sure to install the version that matches your `@nrwl/workspace` version.\n\n```bash\n#yarn\nyarn add --dev @nrwl/next\n```\n\n```bash\n#npm\nnpm install --save-dev @nrwl/next\n```\n\n### Creating Applications\n\nYou can add a new application with the following:\n\n```bash\nnx g @nrwl/next:app my-new-app\n```\n\n### Generating Libraries\n\nNx allows you to create libraries with just one command. Some reasons you might want to create a library include:\n\n- Share code between applications\n- Publish a package to be used outside the monorepo\n- Better visualize the architecture using `nx graph`\n\nFor more information on Nx libraries, see our documentation on [Creating Libraries](/more-concepts/creating-libraries)\nand [Library Types](/more-concepts/library-types).\n\nTo generate a new library run:\n\n```bash\nnx g @nrwl/next:lib my-new-lib\n```\n\n### Generating Pages and Components\n\nNx also provides commands to quickly generate new pages and components for your application.\n\n```bash\nnx g @nrwl/next:page my-new-page --project=my-new-app\n\nnx g @nrwl/next:component my-new-component --project=my-new-app\n```\n\nAbove commands will add a new page `my-new-page` and a component `my-new-component` to `my-new-app` project respectively.\n\nNx generates components with tests by default. For pages, you can pass the `--withTests` option to generate tests under the `specs` folder.\n\n## Using Next.js\n\n### Serving Next.js Applications\n\nYou can run `nx serve my-new-app` to serve a Next.js application called `my-new-app` for development. This will start the dev server at http://localhost:4200.\n\nTo serve a Next.js application for production, add the `--prod` flag to the serve command:\n\n```bash\nnx serve my-new-app --prod\n```\n\n### Using an Nx Library in your Application\n\nYou can import a library called `my-new-lib` in your application as follows.\n\n```typescript jsx\n// apps/my-next-app/pages/index.tsx\nimport { MyNewLib } from '@/my-new-lib';\n\nexport function Index() {\n return (\n \n

The main content

\n \n );\n}\n\nexport default Index;\n```\n\nThere is no need to build the library prior to using it. When you update your library, the Next.js application will automatically pick up the changes.\n\n### Publishable libraries\n\nFor libraries intended to be built and published to a registry (e.g. npm) you can use the `--publishable` and `--importPath` options.\n\n```bash\nnx g @nrwl/next:lib my-new-lib --publishable --importPath=@happynrwl/ui-components\n```\n\n### Testing Projects\n\nYou can run unit tests with:\n\n```bash\nnx test my-new-app\nnx test my-new-lib\n```\n\nReplace `my-new-app` and `my-new-lib` with the name or the project you want to test. This command works for both applications and libraries.\n\nYou can also run E2E tests for applications:\n\n```bash\nnx e2e my-new-app-e2e\n```\n\nReplace `my-new-app-e2e` with the name or your project with -e2e appended.\n\n### Linting Projects\n\nYou can lint projects with:\n\n```bash\nnx lint my-new-app\nnx lint my-new-lib\n```\n\nReplace `my-new-app` and `my-new-lib` with the name or the project you want to test. This command works for both applications and libraries.\n\n### Building Projects\n\nNext.js applications can be build with:\n\n```bash\nnx build my-new-app\n```\n\nAnd if you generated a library with --buildable, then you can build a library as well:\n\n```bash\nnx build my-new-lib\n```\n\nAfter running a build, the output will be in the `dist` folder. You can customize the output folder by setting `outputPath` in the project's `project.json` file.\n\nThe library in `dist` is publishable to npm or a private registry.\n\n### Static HTML Export\n\nNext.js applications can be statically exported with:\n\n```bash\nnx export my-new-app\n```\n\n### Deploying Next.js Applications\n\nOnce you are ready to deploy your Next.js application, you have absolute freedom to choose any hosting provider that fits your needs.\n\nYou may know that the company behind Next.js, Vercel, has a great hosting platform offering that is developed in tandem with Next.js itself to offer a great overall developer and user experience. We have detailed [how to deploy your Next.js application to Vercel in a separate guide](/recipes/other/deploy-nextjs-to-vercel).\n\n## More Documentation\n\nHere are other resources that you may find useful to learn more about Next.js and Nx.\n\n- **Blog post:** [Building a blog with Next.js and Nx Series](https://blog.nrwl.io/create-a-next-js-web-app-with-nx-bcf2ab54613) by Juri Strumpflohner\n- **Video tutorial:** [Typescript NX Monorepo with NextJS and Express](https://www.youtube.com/watch?v=WOfL5q2HznI) by Jack Herrington\n" } ], "generators": [ diff --git a/docs/generated/packages/nx-plugin.json b/docs/generated/packages/nx-plugin.json index b1fe356a7c..2afc45e7d2 100644 --- a/docs/generated/packages/nx-plugin.json +++ b/docs/generated/packages/nx-plugin.json @@ -11,7 +11,7 @@ "name": "Overview", "path": "/packages/nx-plugin", "file": "shared/nx-plugin", - "content": "Nx plugins are npm packages that contain generators and executors to extend a Nx workspace. Generators are blueprints to create new files from templates, and executors run those files. These plugins also update the `nx.json` when generating new libs or apps.\n\n> A list of plugins that is maintained by Nrwl is found in the [Nrwl/nx repo](https://github.com/nrwl/nx/tree/master/packages). \\\n> A list of custom plugins created by the community is found in the [Community](/community) section.\n> Plugins are written using Nx Devkit. **Read [Nx Devkit](/devkit/index) for more information.**\n\n{% youtube\nsrc=\"https://www.youtube.com/embed/fC1-4fAZDP4\"\ntitle=\"Nx Tutorial: Building Custom Plugins for Nx\"\nwidth=\"100%\" /%}\n\n> For a detailed video explaining the things covered here and more, check out [Creating and Publishing Your Own Nx Plugin](https://www.youtube.com/watch?v=vVT7Al01VZc).\n\n## Generating a Plugin\n\nTo get started with building a Nx Plugin, run the following command:\n\n```bash\nnpx create-nx-plugin my-org --pluginName my-plugin\n```\n\nThis command creates a brand-new workspace, and sets up a pre-configured plugin with the specified name.\n\n> Note, the command above will create a plugin the package name set to `@my-org/my-plugin`. You can pass `--importPath` to provide a different package name.\n\n> If you do not want to create a new workspace, install the `@nrwl/nx-plugin` dependency in an already existing workspace with npm or yarn. Then run `nx g @nrwl/nx-plugin:plugin [pluginName]`.\n\nA new plugin is created with a default generator, executor, and e2e app.\n\n## Generator\n\nThe created generator contains boilerplate that will do the following:\n\n- Normalize a schema (the options that the generator accepts)\n- Update the `project.json`\n- Add the plugin's project to the `nx.json` file\n- Add files to the disk using templates\n\nThere will be an exported default function that will be the main entry for the generator.\n\n### Generator options\n\nThe `schema.d.ts` file contains all the options that the generator supports. By default, it includes `directory`, `tags`, and `name` as the options. If more options need to be added, please update this file and the `schema.json` file.\n\n{% callout type=\"note\" title=\"More details\" %}\nThe `schema.d.ts` file is used for type checking inside the implementation file. It should match the properties in `schema.json`.\n{% /callout %}\n\n### Adding more generators\n\nTo add more generators to the plugin, run the following command:\n`nx generate @nrwl/nx-plugin:generator [generatorName] --project=[pluginName]`.\n\nThis will scaffold out a new generator and update the necessary files to support it.\n\n### Generator Testing\n\nThe generator spec file includes boilerplate to help get started with testing. This includes setting up an empty workspace.\n\nThese tests should ensure that files within the tree (created with `createTreeWithEmptyWorkspace`) are in the correct place, and contain the right content.\n\nFull E2Es are supported (and recommended) and will run everything on the file system like a user would.\n\n## Executor\n\nThe default executor is set up to just emit a console log. Some examples of what an executor can do are:\n\n- Support different languages, (Java, Go, Python, C#)\n- Compile new UI framework components\n- Deploy an app on a CDN\n- Publish to NPM\n- and many more!\n\n### Adding more executors\n\nTo add more executors to the plugin, run the following command:\n`nx generate @nrwl/nx-plugin:executor [executor] --project=[pluginName]`.\n\nThis will scaffold out a new generator and update the necessary files to support it.\n\n### Executor testing\n\nThe executor spec file contains boilerplate to run the default exported function from the executor.\n\nThese tests should make sure that the executor is executing and calling the functions that it relies on.\n\nFull E2Es are supported (and recommended) and will run everything on the file system like a user would.\n\n## Testing your plugin\n\nOne of the biggest benefits that the Nx Plugin package provides is support for E2E and unit testing.\n\nWhen the E2E app runs, a temporary E2E directory is created in the root of the workspace. This directory is a blank Nx workspace, and will have the plugin's built package installed locally.\n\n### E2E Testing file\n\nWhen the plugin is generated, a test file is created in the `my-plugin-e2e` app. Inside this test file, there are already tests for making sure that the executor ran, checking if directories are created with the `--directory` option, and checking if tags are added to the project configuration.\n\nWe'll go over a few parts of a test file below:\n\n```typescript\nit('should create my-plugin', async (done) => {\n const plugin = uniq('my-plugin');\n ensureNxProject('@my-org/my-plugin', 'dist/packages/my-plugin');\n await runNxCommandAsync(`generate @my-org/my-plugin:myPlugin ${plugin}`);\n\n const result = await runNxCommandAsync(`build ${plugin}`);\n expect(result.stdout).toContain('Executor ran');\n\n done();\n});\n```\n\n- The `uniq` function creates a random name with the prefix and a random number.\n- The `ensureNxProject` is the function that will create the temporary directory. It takes two arguments, the plugin package name and the dist directory of when it's built.\n- The `runNxCommandAsync` will execute a `nx` command in the E2E directory.\n\nThere are additional functions that the `@nrwl/nx-plugin/testing` package exports. Most of them are file utilities to manipulate and read files in the E2E directory.\n\n## Including Assets\n\nSometimes you might want to include some assets with the plugin. This might be a image or some additional binaries.\n\nTo make sure that assets are copied to the dist folder, open the plugin's `project.json` file. Inside the `build` property, add additional assets. By default, all `.md` files in the root, all non-ts files in folders, and the `generators.json` and `executors.json` files are included.\n\n```json\n\"build\": {\n \"executor\": \"@nrwl/node:package\",\n \"options\": {\n // shortened...\n \"assets\": [\n \"packages/my-plugin/*.md\",\n {\n \"input\": \"./packages/my-plugin/src\",\n \"glob\": \"**/*.!(ts)\",\n \"output\": \"./src\"\n },\n {\n \"input\": \"./packages/my-plugin\",\n \"glob\": \"generators.json\",\n \"output\": \".\"\n },\n {\n \"input\": \"./packages/my-plugin\",\n \"glob\": \"executors.json\",\n \"output\": \".\"\n }\n ]\n }\n}\n```\n\n## Using your Nx Plugin\n\nTo use your plugin, simply list it in `nx.json` or use its generators and executors as you would for any other plugin. This could look like `nx g @my-org/my-plugin:lib` for generators or `\"executor\": \"@my-org/my-plugin:build\"` for executors. It should be usable in all of the same ways as published plugins in your local workspace immediately after generating it. This includes setting it up as the default collection in `nx.json`, which would allow you to run `nx g lib` and hit your plugin's generator.\n\n## Publishing your Nx Plugin\n\nIn order to use your plugin in other workspaces or share it with the community, you will need to publish it to an npm registry. To publish your plugin follow these steps:\n\n1. Build your plugin with the command `nx run my-plugin:build`\n1. `npm publish ./dist/package/my-plugin` and follow the prompts from npm.\n1. That's it!\n\n{% callout type=\"warning\" title=\"Version bump\" %}\nCurrently you will have to modify the `package.json` version by yourself or with a tool.\n{% /callout %}\n\nAfter that, you can then install your plugin like any other npm package,\n`npm i -D @my-org/my-plugin` or `yarn add -D @my-org/my-plugin`.\n\n### Listing your Nx Plugin\n\nNx provides a utility (`nx list`) that lists both core and community plugins. To submit your plugin, please follow the steps below:\n\n- Fork the [Nx repo](https://github.com/nrwl/nx/fork) (if you haven't already)\n- Update the [`community/approved-plugins.json` file](https://github.com/nrwl/nx/blob/master/community/approved-plugins.json) with a new entry for your plugin that includes name, url and description\n- Use the following commit message template: `chore(core): nx plugin submission [PLUGIN_NAME]`\n- push your changes, and run `yarn submit-plugin`\n\n> The `yarn submit-plugin` command automatically opens the Github pull request process with the correct template.\n\nWe will then verify the plugin, offer suggestions or merge the pull request!\n\n## Preset\n\nA Preset is a customization option which you provide when creating a new workspace. TS, Node, React are some internal presets that Nx provides by default.\n\n{% youtube\nsrc=\"https://www.youtube.com/embed/yGUrF0-uqaU\"\ntitle=\"Develop a Nx Preset for your Nx Plugin\"\nwidth=\"100%\" /%}\n\n### Custom Preset\n\nAt its core a preset is a generator, which we can create inside of a plugin.\nIf you **don't** have an existing plugin you can create one by running\n\n```bash\n npx create-nx-plugin my-org --pluginName my-plugin\n```\n\nTo create our preset inside of our plugin we can run\n\n```bash\n nx generate @nrwl/nx-plugin:generator --name=preset --project=happynrwl\n```\n\n{% callout type=\"warning\" title=\"Double check\" %}\nThe word `preset` is required for the name of this generator\n{% /callout %}\n\nYou should have a similar structure to this:\n\n```treeview\nhappynrwl/\n\t├── e2e\n\t├── jest.config.js\n\t├── jest.preset.js\n\t├── nx.json\n\t├── package-lock.json\n\t├── package.json\n\t├── packages\n\t│ └── happynrwl\n\t│ ├── src\n\t│ │ ├── executors\n\t│ │ ├── generators\n\t│ │ │ ├── happynrwl\n\t│ │ │ └── preset \t\t// <------------- Here\n\t│ │ └── index.ts\n\t├── tools\n\t└── tsconfig.base.json\n```\n\nAfter the command is finished, the preset generator is created under the folder named **preset**.\nThe **generator.ts** provides an entry point to the generator. This file contains a function that is called to perform manipulations on a tree that represents the file system. The **schema.json** provides a description of the generator, available options, validation information, and default values.\n\nHere is the sample generator function which you can customize to meet your needs.\n\n```typescript\nexport default async function (tree: Tree, options: PresetGeneratorSchema) {\n const normalizedOptions = normalizeOptions(tree, options);\n addProjectConfiguration(tree, normalizedOptions.projectName, {\n root: normalizedOptions.projectRoot,\n projectType: 'application',\n sourceRoot: `${normalizedOptions.projectRoot}/src`,\n targets: {\n exec: {\n executor: 'nx:run-commands',\n options: {\n command: `node ${projectRoot}/src/index.js`,\n },\n },\n },\n tags: normalizedOptions.parsedTags,\n });\n addFiles(tree, normalizedOptions);\n await formatFiles(tree);\n}\n```\n\nTo get an in-depth guide on customizing/running or debugging your generator see [local generators](/recipe/local-generators).\n\n#### Usage\n\nBefore you are able to use your newly created preset you must package and publish it to a registry.\n\nAfter you have published your plugin to a registry you can now use your preset when creating a new workspace\n\n```bash\nnpx create-nx-workspace my-workspace --preset=my-plugin-name\n```\n" + "content": "Nx plugins are npm packages that contain generators and executors to extend a Nx workspace. Generators are blueprints to create new files from templates, and executors run those files. These plugins also update the `nx.json` when generating new libs or apps.\n\n> A list of plugins that is maintained by Nrwl is found in the [Nrwl/nx repo](https://github.com/nrwl/nx/tree/master/packages). \\\n> A list of custom plugins created by the community is found in the [Community](/community) section.\n> Plugins are written using Nx Devkit. **Read [Nx Devkit](/devkit/index) for more information.**\n\n{% youtube\nsrc=\"https://www.youtube.com/embed/fC1-4fAZDP4\"\ntitle=\"Nx Tutorial: Building Custom Plugins for Nx\"\nwidth=\"100%\" /%}\n\n> For a detailed video explaining the things covered here and more, check out [Creating and Publishing Your Own Nx Plugin](https://www.youtube.com/watch?v=vVT7Al01VZc).\n\n## Generating a Plugin\n\nTo get started with building a Nx Plugin, run the following command:\n\n```bash\nnpx create-nx-plugin my-org --pluginName my-plugin\n```\n\nThis command creates a brand-new workspace, and sets up a pre-configured plugin with the specified name.\n\n> Note, the command above will create a plugin the package name set to `@my-org/my-plugin`. You can pass `--importPath` to provide a different package name.\n\n> If you do not want to create a new workspace, install the `@nrwl/nx-plugin` dependency in an already existing workspace with npm or yarn. Then run `nx g @nrwl/nx-plugin:plugin [pluginName]`.\n\nA new plugin is created with a default generator, executor, and e2e app.\n\n## Generator\n\nThe created generator contains boilerplate that will do the following:\n\n- Normalize a schema (the options that the generator accepts)\n- Update the `project.json`\n- Add the plugin's project to the `nx.json` file\n- Add files to the disk using templates\n\nThere will be an exported default function that will be the main entry for the generator.\n\n### Generator options\n\nThe `schema.d.ts` file contains all the options that the generator supports. By default, it includes `directory`, `tags`, and `name` as the options. If more options need to be added, please update this file and the `schema.json` file.\n\n{% callout type=\"note\" title=\"More details\" %}\nThe `schema.d.ts` file is used for type checking inside the implementation file. It should match the properties in `schema.json`.\n{% /callout %}\n\n### Adding more generators\n\nTo add more generators to the plugin, run the following command:\n`nx generate @nrwl/nx-plugin:generator [generatorName] --project=[pluginName]`.\n\nThis will scaffold out a new generator and update the necessary files to support it.\n\n### Generator Testing\n\nThe generator spec file includes boilerplate to help get started with testing. This includes setting up an empty workspace.\n\nThese tests should ensure that files within the tree (created with `createTreeWithEmptyWorkspace`) are in the correct place, and contain the right content.\n\nFull E2Es are supported (and recommended) and will run everything on the file system like a user would.\n\n## Executor\n\nThe default executor is set up to just emit a console log. Some examples of what an executor can do are:\n\n- Support different languages, (Java, Go, Python, C#)\n- Compile new UI framework components\n- Deploy an app on a CDN\n- Publish to NPM\n- and many more!\n\n### Adding more executors\n\nTo add more executors to the plugin, run the following command:\n`nx generate @nrwl/nx-plugin:executor [executor] --project=[pluginName]`.\n\nThis will scaffold out a new generator and update the necessary files to support it.\n\n### Executor testing\n\nThe executor spec file contains boilerplate to run the default exported function from the executor.\n\nThese tests should make sure that the executor is executing and calling the functions that it relies on.\n\nFull E2Es are supported (and recommended) and will run everything on the file system like a user would.\n\n## Testing your plugin\n\nOne of the biggest benefits that the Nx Plugin package provides is support for E2E and unit testing.\n\nWhen the E2E app runs, a temporary E2E directory is created in the root of the workspace. This directory is a blank Nx workspace, and will have the plugin's built package installed locally.\n\n### E2E Testing file\n\nWhen the plugin is generated, a test file is created in the `my-plugin-e2e` app. Inside this test file, there are already tests for making sure that the executor ran, checking if directories are created with the `--directory` option, and checking if tags are added to the project configuration.\n\nWe'll go over a few parts of a test file below:\n\n```typescript\nit('should create my-plugin', async (done) => {\n const plugin = uniq('my-plugin');\n ensureNxProject('@my-org/my-plugin', 'dist/packages/my-plugin');\n await runNxCommandAsync(`generate @my-org/my-plugin:myPlugin ${plugin}`);\n\n const result = await runNxCommandAsync(`build ${plugin}`);\n expect(result.stdout).toContain('Executor ran');\n\n done();\n});\n```\n\n- The `uniq` function creates a random name with the prefix and a random number.\n- The `ensureNxProject` is the function that will create the temporary directory. It takes two arguments, the plugin package name and the dist directory of when it's built.\n- The `runNxCommandAsync` will execute a `nx` command in the E2E directory.\n\nThere are additional functions that the `@nrwl/nx-plugin/testing` package exports. Most of them are file utilities to manipulate and read files in the E2E directory.\n\n## Including Assets\n\nSometimes you might want to include some assets with the plugin. This might be a image or some additional binaries.\n\nTo make sure that assets are copied to the dist folder, open the plugin's `project.json` file. Inside the `build` property, add additional assets. By default, all `.md` files in the root, all non-ts files in folders, and the `generators.json` and `executors.json` files are included.\n\n```json\n\"build\": {\n \"executor\": \"@nrwl/node:package\",\n \"options\": {\n // shortened...\n \"assets\": [\n \"packages/my-plugin/*.md\",\n {\n \"input\": \"./packages/my-plugin/src\",\n \"glob\": \"**/*.!(ts)\",\n \"output\": \"./src\"\n },\n {\n \"input\": \"./packages/my-plugin\",\n \"glob\": \"generators.json\",\n \"output\": \".\"\n },\n {\n \"input\": \"./packages/my-plugin\",\n \"glob\": \"executors.json\",\n \"output\": \".\"\n }\n ]\n }\n}\n```\n\n## Using your Nx Plugin\n\nTo use your plugin, simply list it in `nx.json` or use its generators and executors as you would for any other plugin. This could look like `nx g @my-org/my-plugin:lib` for generators or `\"executor\": \"@my-org/my-plugin:build\"` for executors. It should be usable in all of the same ways as published plugins in your local workspace immediately after generating it. This includes setting it up as the default collection in `nx.json`, which would allow you to run `nx g lib` and hit your plugin's generator.\n\n## Publishing your Nx Plugin\n\nIn order to use your plugin in other workspaces or share it with the community, you will need to publish it to an npm registry. To publish your plugin follow these steps:\n\n1. Build your plugin with the command `nx run my-plugin:build`\n1. `npm publish ./dist/package/my-plugin` and follow the prompts from npm.\n1. That's it!\n\n{% callout type=\"warning\" title=\"Version bump\" %}\nCurrently you will have to modify the `package.json` version by yourself or with a tool.\n{% /callout %}\n\nAfter that, you can then install your plugin like any other npm package,\n`npm i -D @my-org/my-plugin` or `yarn add -D @my-org/my-plugin`.\n\n### Listing your Nx Plugin\n\nNx provides a utility (`nx list`) that lists both core and community plugins. To submit your plugin, please follow the steps below:\n\n- Fork the [Nx repo](https://github.com/nrwl/nx/fork) (if you haven't already)\n- Update the [`community/approved-plugins.json` file](https://github.com/nrwl/nx/blob/master/community/approved-plugins.json) with a new entry for your plugin that includes name, url and description\n- Use the following commit message template: `chore(core): nx plugin submission [PLUGIN_NAME]`\n- push your changes, and run `yarn submit-plugin`\n\n> The `yarn submit-plugin` command automatically opens the Github pull request process with the correct template.\n\nWe will then verify the plugin, offer suggestions or merge the pull request!\n\n## Preset\n\nA Preset is a customization option which you provide when creating a new workspace. TS, Node, React are some internal presets that Nx provides by default.\n\n{% youtube\nsrc=\"https://www.youtube.com/embed/yGUrF0-uqaU\"\ntitle=\"Develop a Nx Preset for your Nx Plugin\"\nwidth=\"100%\" /%}\n\n### Custom Preset\n\nAt its core a preset is a generator, which we can create inside of a plugin.\nIf you **don't** have an existing plugin you can create one by running\n\n```bash\n npx create-nx-plugin my-org --pluginName my-plugin\n```\n\nTo create our preset inside of our plugin we can run\n\n```bash\n nx generate @nrwl/nx-plugin:generator --name=preset --project=happynrwl\n```\n\n{% callout type=\"warning\" title=\"Double check\" %}\nThe word `preset` is required for the name of this generator\n{% /callout %}\n\nYou should have a similar structure to this:\n\n```treeview\nhappynrwl/\n\t├── e2e\n\t├── jest.config.js\n\t├── jest.preset.js\n\t├── nx.json\n\t├── package-lock.json\n\t├── package.json\n\t├── packages\n\t│ └── happynrwl\n\t│ ├── src\n\t│ │ ├── executors\n\t│ │ ├── generators\n\t│ │ │ ├── happynrwl\n\t│ │ │ └── preset \t\t// <------------- Here\n\t│ │ └── index.ts\n\t├── tools\n\t└── tsconfig.base.json\n```\n\nAfter the command is finished, the preset generator is created under the folder named **preset**.\nThe **generator.ts** provides an entry point to the generator. This file contains a function that is called to perform manipulations on a tree that represents the file system. The **schema.json** provides a description of the generator, available options, validation information, and default values.\n\nHere is the sample generator function which you can customize to meet your needs.\n\n```typescript\nexport default async function (tree: Tree, options: PresetGeneratorSchema) {\n const normalizedOptions = normalizeOptions(tree, options);\n addProjectConfiguration(tree, normalizedOptions.projectName, {\n root: normalizedOptions.projectRoot,\n projectType: 'application',\n sourceRoot: `${normalizedOptions.projectRoot}/src`,\n targets: {\n exec: {\n executor: 'nx:run-commands',\n options: {\n command: `node ${projectRoot}/src/index.js`,\n },\n },\n },\n tags: normalizedOptions.parsedTags,\n });\n addFiles(tree, normalizedOptions);\n await formatFiles(tree);\n}\n```\n\nTo get an in-depth guide on customizing/running or debugging your generator see [local generators](/recipes/generators/local-generators).\n\n#### Usage\n\nBefore you are able to use your newly created preset you must package and publish it to a registry.\n\nAfter you have published your plugin to a registry you can now use your preset when creating a new workspace\n\n```bash\nnpx create-nx-workspace my-workspace --preset=my-plugin-name\n```\n" } ], "generators": [ diff --git a/docs/generated/packages/storybook.json b/docs/generated/packages/storybook.json index d130bfe599..f4081d0a65 100644 --- a/docs/generated/packages/storybook.json +++ b/docs/generated/packages/storybook.json @@ -29,7 +29,7 @@ "id": "best-practices", "name": "Storybook best practices for making the most out of Nx", "file": "shared/guides/storybook/best-practices", - "content": "# Storybook best practices for making the most out of Nx\n\n## Purpose of this guide\n\nThe purpose of this guide is to help you [set up Storybook in your Nx workspace](/packages/storybook) so that you can get the most out of Nx and its powerful capabilities.\n\n## When to use Storybook\n\nUsually, Storybook is mainly used for two reasons. Testing and documentation. You can read more on when and why to use Storybook in the [Why Storybook in 2022?](https://storybook.js.org/blog/why-storybook-in-2022/) article and also in the [Introduction to Storybook](https://storybook.js.org/docs/react/get-started/introduction) documentation page.\n\n### Testing\n\nStorybook helps you test your UIs. You can read more about testing with Storybook in the [How to test your UIs with Storybook](https://storybook.js.org/docs/react/writing-tests/introduction) documentation page. Essentially, Storybook uses the stories as a starting point for testing.\n\n### Documentation\n\nStorybook helps you document your UI elements, or your design system, effectively and in an interactive way. You can read more in the [How to document components](https://storybook.js.org/docs/react/writing-docs/introduction) documentation page. Essentially, you can use Storybook to publish a catalog of your components. A catalog that you can share with the design team, the developer team, the product team, anyone else in the product development process, or even the client. The components are isolated, interactive, and can be represented in all possible forms that they can take (eg. for a button: enabled, disabled, active, etc). You can read more about publishing your Storybook in the [Publish Storybook](https://storybook.js.org/docs/react/sharing/publish-storybook) documentation page.\n\n## Nx and Storybook\n\nNow let’s see how Nx can be used to accommodate both of these pillars of Storybook. Nx takes lots of the burden off your arms when setting up Storybook initially. It essentially provides you with all that you need to start using Storybook’s capabilities (testing and documentation) right away, without having to write a single line of code.\n\n### Development tools\n\nFirst, let’s see what Nx offers, when you are in the process of developing a project with Storybook.\n\n#### Configuration generation\n\nYou can generate the Storybook configuration files and settings using the Nx [`@nrwl/storybook:configuration` generator](/packages/storybook/generators/configuration). You can read more about configuring Storybook with Nx in our [`@nrwl/storybook` package overview page](/packages/storybook#generating-storybook-configuration). With Nx, you configure Storybook for each individual project.\n\n#### Stories generation\n\nIf you are on a project using Angular, React or React Native, you can also generate stories for your components. You can do so either by using each package's `storybook-configuration` generators or by using the `stories` generator, if you already have Storybook configured for your project.\n\nIf your project is not configured yet, check out one of these guides:\n\n- [Set up Storybook for React Projects](/storybook/overview-react)\n\n- [Set up Storybook for Angular Projects](/storybook/overview-angular)\n\nIf your project is [already configured](/packages/storybook), you can use the `stories` generator:\n\n- [React stories generator](/packages/react/generators/stories)\n\n- [React Native stories generator](/packages/react-native/generators/stories)\n\n- [Angular stories generator](/packages/angular/generators/stories)\n\nThe stories generator will read your inputs (if you’re using Angular), or your props (if you're using React), and will generate stories with the corresponding arguments/controls already prefilled.\n\n#### Cypress tests generation\n\nNx also generates Cypress tests for your components, that point to the corresponding component’s story. You can read more about how the Cypress tests are generated and how they look like in the [storybook-configuration generator documentation](/storybook/overview-react#cypress-tests-for-stories).\n\nTake a look at the generated code of the Cypress test file, specifically at the URL which Cypress visits:\n\n```javascript\ncy.visit(\n '/iframe.html?id=buttoncomponent--primary&args=text:Click+me!;padding;style:default'\n);\n```\n\nCypress visits the URL that hosts the story of the component we are testing, adding values to its controls (eg. `args=text:Click+me!`). Then, the test attempts to validate that the values are correctly applied.\n\n### CI/CD tools\n\nNow let’s see how Nx helps in the CI/CD journey, as well.\n\n#### Cypress testing\n\nWhen you are running the Cypress tests for a project, Cypress will start the Storybook server of that project. The Storybook server will fire up a Storybook instance, hosting all the components's stories for that project. The e2e tests will then run, which actually visit the stories and perform the tests there. Cypress will be configured to start and stop the Storybook server. The results will be cached, and they will go through the Nx graph, meaning that Nx will know if the tests need to be run again or not, depending on the affected status of your project.\n\n#### Serve\n\nWhen you are configuring Storybook, Nx [adds a serve and a build target for Storybook](/packages/storybook#generating-storybook-configuration) in your `project.json`, as we explained above. You can use these targets to [serve](/packages/storybook/executors/storybook) and [build](/packages/storybook/executors/build) storybook locally, and also in production. Cypress will also use these targets when firing up the e2e tests. While developing, you can serve your Storybooks locally to see if your components work and look as expected. This can help you and speed up the development and debugging process (no need to fire up a complex dev stack).\n\n#### Build and deploy\n\nThe build and deploy step usually comes in handy when you are ready to use Storybook for documentation, and you want to publish it. The [building](/packages/storybook/executors/build) step of Storybook is integrated in the Nx ecosystem, as explained above, and you can trigger your Storybook builds as you would trigger any other build inside your workspace.\n\nWhen you publish your organization’s Storybook, as a result, ideally, you would want to have one shareable Storybook page/application living under one URL, that you can share. With Nx, you can build your Storybook and it will be ready for deployment. **However**, at this point, you have one Storybook per project in your workspace, and you could end up with far too many Storybooks that are built and ready for deployment. This is not ideal, and does not accomplish the ultimate goal of “one shareable documentation page”.\n\nIn the following section, we are going to see how to set up Storybook in these cases, to get the most out of Nx.\n\n## How to set up Storybook to get the most out of Nx\n\n### Philosophy\n\nSetting up Storybook on Nx reflects - and takes advantage of - the [mental model](/concepts/mental-model) of Nx, and especially the architecture of [Applications and Libraries](/more-concepts/applications-and-libraries). What that means, in essence, is that you still maintain the individual Storybook instances (per project) which you use for testing and local development, but you also keep one extra “container” for publishing, that serves as a single entry point. Let’s see this in more detail.\n\n#### Local development and testing\n\n##### Development and debugging\n\nIn the process of setting up Storybook in your Nx workspace that we described above, you end up with one Storybook instance per project. That way, you can use your project’s Storybook targets to serve and build Storybook:\n\n```bash\nnx storybook my-project\n```\n\nand\n\n```bash\nnx build-storybook my-project\n```\n\nThis feature is extremely useful when developing locally. The containerized stories in your Storybook are the only ones that are built/served when you want to debug just one component, or just one library. You don’t have to wait for a huge Storybook containing all your stories in your repository to fire up. You just need to wait for the Storybook of a single project to start. This speeds up the process.\n\n##### E2e tests with Cypress\n\nIf you’re using Cypress, and you’re taking advantage of the generated Cypress tests that our Storybook generators generate, then your e2e tests are also going to be much faster. When you run your e2e tests for a particular project, Cypress is only going to start the specific Storybook instance, and it’s going to take much less time than having to start an all-including universal Storybook.\n\n##### Caching, affected, dependency management\n\nSince each Storybook, in this case, is attached to a project, so is the serving of Storybook and the building of Storybook and the e2e tests for that project. That means that Nx is aware of these tasks, so it caches them, it knows when to fetch them from the cache or re-run them according to the affected status of that project. It also knows that project’s dependencies and knows which things to rebuild before each task.\n\n#### Publishing\n\nWhen you are publishing your Storybook, you can follow the same principles described in the [Applications and Libraries Mental Model](/more-concepts/applications-and-libraries#mental-model) documentation page. The general idea is to have one central Storybook container, into which you are going to gather your stories from multiple libraries.\n\nYou can think of the central Storybook container as a grouping of similar-concept or same-scope UI parts of your workspace. In the same way you are scoping libraries, you can group your stories as well.\n\nThen, according to your use-case, you can have one central Storybook for your whole workspace, importing all the stories from all the projects. Alternatively, you can have one Storybook per \"scope\", which imports all the stories from projects the same scope. Or even one Storybook per application, importing all the stories of all the libraries that it is depending on. As you can see, there are many options, and you can choose the one that best suits your needs.\n\n{% callout type=\"note\" title=\"Storybook Composition\" %}\nIn order to achieve some of the things mentioned above, you may use [Storybook Composition](/storybook/storybook-composition-setup). However, in this case, you would still need to build each project’s Storybook individually, and also deploy it individually. So in the cases where you have multiple projects, Storybook Composition would not be very efficient.\n{% /callout %}\n\nBefore moving on to the examples section, it could be useful to read the [Library Types](/more-concepts/library-types) documentation page and the [Grouping libraries](/more-concepts/grouping-libraries) documentation page. These could help you decide which way fits your use case better.\n\n## Examples / Use cases\n\nYou can check out the following examples (recipes) to see publishing strategies for Storybook in Nx:\n\n- [One main Storybook instance for all projects](/recipe/one-storybook-for-all)\n- [One Storybook instance per scope](/recipe/one-storybook-per-scope)\n- [One main Storybook instance using Storybook Composition](/recipe/one-storybook-with-composition)\n\n## Conclusion\n\nIn this guide, we have given a direction towards the most efficient way to use Storybook in a Nx workspace, in a way that takes advantage of the all that Nx has to offer.\nWe have covered the different ways to set up Storybook, and publish it, too. We have also covered the different use cases that apply to each of the solutions.\n\nIf you have any questions or suggestions, please feel free to reach out to us on [GitHub](https://github.com/nrwl/nx), and don't hesitate to ask your questions or share your stories in our [Nx community Slack](https://join.slack.com/t/nrwlcommunity/shared_invite/zt-1fmyh7hib-MsIDqDDxoutA1gqeFHCnyA).\n\n### Nx & Storybook documentation\n\nYou can find all Storybook-related Nx documentation in the [packages page](/packages#storybook).\n" + "content": "# Storybook best practices for making the most out of Nx\n\n## Purpose of this guide\n\nThe purpose of this guide is to help you [set up Storybook in your Nx workspace](/packages/storybook) so that you can get the most out of Nx and its powerful capabilities.\n\n## When to use Storybook\n\nUsually, Storybook is mainly used for two reasons. Testing and documentation. You can read more on when and why to use Storybook in the [Why Storybook in 2022?](https://storybook.js.org/blog/why-storybook-in-2022/) article and also in the [Introduction to Storybook](https://storybook.js.org/docs/react/get-started/introduction) documentation page.\n\n### Testing\n\nStorybook helps you test your UIs. You can read more about testing with Storybook in the [How to test your UIs with Storybook](https://storybook.js.org/docs/react/writing-tests/introduction) documentation page. Essentially, Storybook uses the stories as a starting point for testing.\n\n### Documentation\n\nStorybook helps you document your UI elements, or your design system, effectively and in an interactive way. You can read more in the [How to document components](https://storybook.js.org/docs/react/writing-docs/introduction) documentation page. Essentially, you can use Storybook to publish a catalog of your components. A catalog that you can share with the design team, the developer team, the product team, anyone else in the product development process, or even the client. The components are isolated, interactive, and can be represented in all possible forms that they can take (eg. for a button: enabled, disabled, active, etc). You can read more about publishing your Storybook in the [Publish Storybook](https://storybook.js.org/docs/react/sharing/publish-storybook) documentation page.\n\n## Nx and Storybook\n\nNow let’s see how Nx can be used to accommodate both of these pillars of Storybook. Nx takes lots of the burden off your arms when setting up Storybook initially. It essentially provides you with all that you need to start using Storybook’s capabilities (testing and documentation) right away, without having to write a single line of code.\n\n### Development tools\n\nFirst, let’s see what Nx offers, when you are in the process of developing a project with Storybook.\n\n#### Configuration generation\n\nYou can generate the Storybook configuration files and settings using the Nx [`@nrwl/storybook:configuration` generator](/packages/storybook/generators/configuration). You can read more about configuring Storybook with Nx in our [`@nrwl/storybook` package overview page](/packages/storybook#generating-storybook-configuration). With Nx, you configure Storybook for each individual project.\n\n#### Stories generation\n\nIf you are on a project using Angular, React or React Native, you can also generate stories for your components. You can do so either by using each package's `storybook-configuration` generators or by using the `stories` generator, if you already have Storybook configured for your project.\n\nIf your project is not configured yet, check out one of these guides:\n\n- [Set up Storybook for React Projects](/storybook/overview-react)\n\n- [Set up Storybook for Angular Projects](/storybook/overview-angular)\n\nIf your project is [already configured](/packages/storybook), you can use the `stories` generator:\n\n- [React stories generator](/packages/react/generators/stories)\n\n- [React Native stories generator](/packages/react-native/generators/stories)\n\n- [Angular stories generator](/packages/angular/generators/stories)\n\nThe stories generator will read your inputs (if you’re using Angular), or your props (if you're using React), and will generate stories with the corresponding arguments/controls already prefilled.\n\n#### Cypress tests generation\n\nNx also generates Cypress tests for your components, that point to the corresponding component’s story. You can read more about how the Cypress tests are generated and how they look like in the [storybook-configuration generator documentation](/storybook/overview-react#cypress-tests-for-stories).\n\nTake a look at the generated code of the Cypress test file, specifically at the URL which Cypress visits:\n\n```javascript\ncy.visit(\n '/iframe.html?id=buttoncomponent--primary&args=text:Click+me!;padding;style:default'\n);\n```\n\nCypress visits the URL that hosts the story of the component we are testing, adding values to its controls (eg. `args=text:Click+me!`). Then, the test attempts to validate that the values are correctly applied.\n\n### CI/CD tools\n\nNow let’s see how Nx helps in the CI/CD journey, as well.\n\n#### Cypress testing\n\nWhen you are running the Cypress tests for a project, Cypress will start the Storybook server of that project. The Storybook server will fire up a Storybook instance, hosting all the components's stories for that project. The e2e tests will then run, which actually visit the stories and perform the tests there. Cypress will be configured to start and stop the Storybook server. The results will be cached, and they will go through the Nx graph, meaning that Nx will know if the tests need to be run again or not, depending on the affected status of your project.\n\n#### Serve\n\nWhen you are configuring Storybook, Nx [adds a serve and a build target for Storybook](/packages/storybook#generating-storybook-configuration) in your `project.json`, as we explained above. You can use these targets to [serve](/packages/storybook/executors/storybook) and [build](/packages/storybook/executors/build) storybook locally, and also in production. Cypress will also use these targets when firing up the e2e tests. While developing, you can serve your Storybooks locally to see if your components work and look as expected. This can help you and speed up the development and debugging process (no need to fire up a complex dev stack).\n\n#### Build and deploy\n\nThe build and deploy step usually comes in handy when you are ready to use Storybook for documentation, and you want to publish it. The [building](/packages/storybook/executors/build) step of Storybook is integrated in the Nx ecosystem, as explained above, and you can trigger your Storybook builds as you would trigger any other build inside your workspace.\n\nWhen you publish your organization’s Storybook, as a result, ideally, you would want to have one shareable Storybook page/application living under one URL, that you can share. With Nx, you can build your Storybook and it will be ready for deployment. **However**, at this point, you have one Storybook per project in your workspace, and you could end up with far too many Storybooks that are built and ready for deployment. This is not ideal, and does not accomplish the ultimate goal of “one shareable documentation page”.\n\nIn the following section, we are going to see how to set up Storybook in these cases, to get the most out of Nx.\n\n## How to set up Storybook to get the most out of Nx\n\n### Philosophy\n\nSetting up Storybook on Nx reflects - and takes advantage of - the [mental model](/concepts/mental-model) of Nx, and especially the architecture of [Applications and Libraries](/more-concepts/applications-and-libraries). What that means, in essence, is that you still maintain the individual Storybook instances (per project) which you use for testing and local development, but you also keep one extra “container” for publishing, that serves as a single entry point. Let’s see this in more detail.\n\n#### Local development and testing\n\n##### Development and debugging\n\nIn the process of setting up Storybook in your Nx workspace that we described above, you end up with one Storybook instance per project. That way, you can use your project’s Storybook targets to serve and build Storybook:\n\n```bash\nnx storybook my-project\n```\n\nand\n\n```bash\nnx build-storybook my-project\n```\n\nThis feature is extremely useful when developing locally. The containerized stories in your Storybook are the only ones that are built/served when you want to debug just one component, or just one library. You don’t have to wait for a huge Storybook containing all your stories in your repository to fire up. You just need to wait for the Storybook of a single project to start. This speeds up the process.\n\n##### E2e tests with Cypress\n\nIf you’re using Cypress, and you’re taking advantage of the generated Cypress tests that our Storybook generators generate, then your e2e tests are also going to be much faster. When you run your e2e tests for a particular project, Cypress is only going to start the specific Storybook instance, and it’s going to take much less time than having to start an all-including universal Storybook.\n\n##### Caching, affected, dependency management\n\nSince each Storybook, in this case, is attached to a project, so is the serving of Storybook and the building of Storybook and the e2e tests for that project. That means that Nx is aware of these tasks, so it caches them, it knows when to fetch them from the cache or re-run them according to the affected status of that project. It also knows that project’s dependencies and knows which things to rebuild before each task.\n\n#### Publishing\n\nWhen you are publishing your Storybook, you can follow the same principles described in the [Applications and Libraries Mental Model](/more-concepts/applications-and-libraries#mental-model) documentation page. The general idea is to have one central Storybook container, into which you are going to gather your stories from multiple libraries.\n\nYou can think of the central Storybook container as a grouping of similar-concept or same-scope UI parts of your workspace. In the same way you are scoping libraries, you can group your stories as well.\n\nThen, according to your use-case, you can have one central Storybook for your whole workspace, importing all the stories from all the projects. Alternatively, you can have one Storybook per \"scope\", which imports all the stories from projects the same scope. Or even one Storybook per application, importing all the stories of all the libraries that it is depending on. As you can see, there are many options, and you can choose the one that best suits your needs.\n\n{% callout type=\"note\" title=\"Storybook Composition\" %}\nIn order to achieve some of the things mentioned above, you may use [Storybook Composition](/storybook/storybook-composition-setup). However, in this case, you would still need to build each project’s Storybook individually, and also deploy it individually. So in the cases where you have multiple projects, Storybook Composition would not be very efficient.\n{% /callout %}\n\nBefore moving on to the examples section, it could be useful to read the [Library Types](/more-concepts/library-types) documentation page and the [Grouping libraries](/more-concepts/grouping-libraries) documentation page. These could help you decide which way fits your use case better.\n\n## Examples / Use cases\n\nYou can check out the following examples (recipes) to see publishing strategies for Storybook in Nx:\n\n- [One main Storybook instance for all projects](/recipes/storybook/one-storybook-for-all)\n- [One Storybook instance per scope](/recipes/storybook/one-storybook-per-scope)\n- [One main Storybook instance using Storybook Composition](/recipes/storybook/one-storybook-with-composition)\n\n## Conclusion\n\nIn this guide, we have given a direction towards the most efficient way to use Storybook in a Nx workspace, in a way that takes advantage of the all that Nx has to offer.\nWe have covered the different ways to set up Storybook, and publish it, too. We have also covered the different use cases that apply to each of the solutions.\n\nIf you have any questions or suggestions, please feel free to reach out to us on [GitHub](https://github.com/nrwl/nx), and don't hesitate to ask your questions or share your stories in our [Nx community Slack](https://join.slack.com/t/nrwlcommunity/shared_invite/zt-1fmyh7hib-MsIDqDDxoutA1gqeFHCnyA).\n\n### Nx & Storybook documentation\n\nYou can find all Storybook-related Nx documentation in the [packages page](/packages#storybook).\n" }, { "id": "storybook-composition-setup", @@ -41,7 +41,7 @@ "id": "angular-storybook-compodoc", "name": "Angular: Set up Compodoc for Storybook on Nx", "file": "shared/guides/storybook/angular-storybook-compodoc", - "content": "# Set up Compodoc for Storybook on Nx\n\n{% callout type=\"note\" title=\"Note\" %}\nThis documentation page contains information about the [Storybook plugin](/packages/storybook), specifically regarding [Angular projects that are using Storybook](/storybook/overview-angular).\n{% /callout %}\n\n{% github-repository url=\"https://github.com/nrwl/nx-recipes/tree/main/storybook-compodoc-angular\" /%}\n\n## What is Compodoc\n\n[Compodoc](https://compodoc.app/) is a documentation generator for Angular applications. You can use [JSDoc](https://jsdoc.app/) comment blocks above your components, directives, and other Angular constructs, to add documentation to the elements that you want. These comments are used by `compodoc` to generate documentation for your application. As is noted in the [Compodoc documentation](https://compodoc.app/guides/comments.html), \"Compodoc uses the Typescript AST parser and it's internal APIs, so the comments have to be JSDoc comments\". You can read more about the JSDoc tags that Compodoc supports [here](https://compodoc.app/guides/jsdoc-tags.html).\n\n## How to use Compodoc in Storybook to write documentation\n\nIn Storybook, it makes sense to add explanatory comments above your `@Input`s and `@Output`s, since these are the main elements that Storybook focuses on. The `@Input`s and `@Output`s are the elements that you can interact with in the Storybook UI, the controls.\n\nLet's take for example an Angular component - a button - that has an `@Input` for the size of the button. In Compodoc, we could describe this input as follows:\n\n```ts\n /**\n * How large should the button be?\n */\n @Input()\n size: 'small' | 'medium' | 'large' = 'medium';\n```\n\nThis comment would result in the following documentation in Compodoc:\n\n![Button size `@Input` generated documentation](/shared/guides/storybook/button-size-input.png)\n\nIf we add a description and a default value to each of our component `@Input`s, we will end up with a full documentation page. See a full example of the button component [here](https://github.com/nrwl/nx-recipes/tree/main/storybook-compodoc-angular/apps/web/src/app/butn/butn.component.ts). The generated documentation of this example will look like this:\n\n![Generated Docs page for the Button](/shared/guides/storybook/button-docs.png)\n\nWhen you run Compodoc, it will generate a `documentation.json` file. Storybook will then use that file to render the documentation in the `Docs` tab.\n\n## How to enable Compodoc for Storybook\n\nThe main things that you need to do are:\n\n1. Include the component files in the TypeScript compilation for Compodoc (or any other files that contain your Compodoc documentation).\n2. Use `compodoc` to generate a `documentation.json` file.\n3. Tell Storybook to use the `documentation.json` file to display the documentation.\n\nLet's see how you can do that.\n\n{% callout type=\"note\" title=\"Note\" %}\nThis guide assumes that you have an Angular project with Storybook configured in your Nx workspace. If you do not know how to set these up, please read about [setting up Storybook for Angular](/storybook/overview-angular) on the Nx documentation website.\n{% /callout %}\n\n### 1. Install the necessary packages\n\nFirst we need to install the necessary packages:\n\n```bash\nyarn add -D @compodoc/compodoc\n```\n\nor\n\n```bash\nnpm install --save-dev @compodoc/compodoc\n```\n\n### 2. Include the component files in the TypeScript compilation for Compodoc\n\nWhen you are using Compodoc, you need to create a `tsconfig` file, and in the `include` array you need to place all the files that you want Compodoc to include in its compilation. Compodoc [suggests](https://compodoc.app/guides/installation.html) to add a `tsconfig.doc.json` to do that. Then, when running `compodoc` you can use the `-p` (or `--tsconfig`) flag to specify the path to that file. See all the options that Compodoc supports [here](https://compodoc.app/guides/options.html).\n\nIn the Storybook case, Storybook has the `--tsconfig` option [prefilled](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/utils/run-compodoc.ts#L23) to point to the `.storybook/tsconfig.json` file. As is noted in the [Storybook schema for the Angular builders](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/start-storybook/schema.json#L76), \"_Options `-p` with tsconfig path and `-d` with workspace root is always given._\". What this means is that you can add the paths to the component files (where Compodoc will look for JSDoc comment blocks) in the `include` array of the `.storybook/tsconfig.json` file. This is the file that Storybook will use to compile the TypeScript files, and it will also be the file that Compodoc will use to compile the TypeScript files.\n\nIn your project's `.storybook/tsconfig.json` file, in the `include` array, add the path to the component files (eg. `\"../src/**/*.component.ts\"`). For example, if you have an application called `web`, the file `apps/web/.storybook/tsconfig.json` will look like this:\n\n```json\n{\n \"extends\": \"../tsconfig.json\",\n \"compilerOptions\": {\n \"emitDecoratorMetadata\": true\n },\n \"files\": [\"../src/polyfills.ts\"],\n \"exclude\": [\"../**/*.spec.ts\"],\n \"include\": [\"../src/**/*.stories.ts\", \"../src/**/*.component.ts\", \"*.js\"]\n}\n```\n\n{% callout type=\"warning\" title=\"Don't forget all the paths!\" %}\nImportant! If you are importing stories from other places, and you want the docs for these stories to be generated, too, you need to add the paths to the other components in the `include` array, as well!\n\nFor example, if your stories paths look like this:\n\n```\n\"../../../**/**/src/lib/**/*.stories.ts\"\n```\n\nmake sure to also include\n\n```\n\"../../../**/**/src/lib/**/*.component.ts\"\n```\n\nfor the components to be included in the TypeScript compilation as well.\n\nThis applies in cases where, for example, you have [one single Storybook for your whole workspace](/recipe/one-storybook-for-all), where you import stories from all the projects. In that case, you need to import all the components as well!\n{% /callout %}\n\n### 3. Enable `compodoc` and configure it\n\n#### a. Set `compodoc: true`\n\nIn your project's `project.json` file (eg. `apps/web/project.json`), find the `storybook` and the `build-storybook` targets.\n\nIn the `options` you will see `\"compodoc\": false`. Change that to `true`.\n\n#### b. Set the directory\n\nStorybook has [preconfigured `compodoc`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/utils/run-compodoc.ts#L25) to generate a `documentation.json` file at the root of your workspace by default. We want to change that, and keep the documentation file project-specific. Of course you can change that later, or as you see fit for your use case. But let's keep it project-specific for now.\n\nIn your project's `project.json` file (eg. `apps/web/project.json`), find the `storybook` and the `build-storybook` targets. Below the `\"compodoc\"` option, create a new option called `\"compodocArgs` which contains the following: `[\"-e\", \"json\", \"-d\", \"apps/web\"]`. This means that the `exportFormat` (`-e`) will be `json` and the `output` directory (`-d`) will be `apps/web` (change that, of course, to the directory of your project).\n\nLet's see the result for our `web` app `storybook` target, for example (in `apps/web/project.json`):\n\n```json\n \"storybook\": {\n \"executor\": \"@storybook/angular:start-storybook\",\n \"options\": {\n \"port\": 4400,\n \"configDir\": \"apps/web/.storybook\",\n \"browserTarget\": \"web:build\",\n \"compodoc\": true,\n \"compodocArgs\": [\"-e\", \"json\", \"-d\", \"apps/web\"]\n },\n },\n```\n\n### 4. Let Storybook know of the `documentation.json` file\n\nIn your project's `.storybook/preview.js` file (for example for your `web` app the path would be `apps/web/.storybook/preview.js`), add the following:\n\n```js\nimport { setCompodocJson } from '@storybook/addon-docs/angular';\nimport docJson from '../documentation.json';\nsetCompodocJson(docJson);\n```\n\n### Now run Storybook and see the results!\n\nNow you can run Storybook or build Storybook, and documentation will be included. Just check the Docs tab!\n\n```bash\nnx storybook web\n```\n\nand\n\n```bash\nnx build-storybook web\n```\n" + "content": "# Set up Compodoc for Storybook on Nx\n\n{% callout type=\"note\" title=\"Note\" %}\nThis documentation page contains information about the [Storybook plugin](/packages/storybook), specifically regarding [Angular projects that are using Storybook](/storybook/overview-angular).\n{% /callout %}\n\n{% github-repository url=\"https://github.com/nrwl/nx-recipes/tree/main/storybook-compodoc-angular\" /%}\n\n## What is Compodoc\n\n[Compodoc](https://compodoc.app/) is a documentation generator for Angular applications. You can use [JSDoc](https://jsdoc.app/) comment blocks above your components, directives, and other Angular constructs, to add documentation to the elements that you want. These comments are used by `compodoc` to generate documentation for your application. As is noted in the [Compodoc documentation](https://compodoc.app/guides/comments.html), \"Compodoc uses the Typescript AST parser and it's internal APIs, so the comments have to be JSDoc comments\". You can read more about the JSDoc tags that Compodoc supports [here](https://compodoc.app/guides/jsdoc-tags.html).\n\n## How to use Compodoc in Storybook to write documentation\n\nIn Storybook, it makes sense to add explanatory comments above your `@Input`s and `@Output`s, since these are the main elements that Storybook focuses on. The `@Input`s and `@Output`s are the elements that you can interact with in the Storybook UI, the controls.\n\nLet's take for example an Angular component - a button - that has an `@Input` for the size of the button. In Compodoc, we could describe this input as follows:\n\n```ts\n /**\n * How large should the button be?\n */\n @Input()\n size: 'small' | 'medium' | 'large' = 'medium';\n```\n\nThis comment would result in the following documentation in Compodoc:\n\n![Button size `@Input` generated documentation](/shared/guides/storybook/button-size-input.png)\n\nIf we add a description and a default value to each of our component `@Input`s, we will end up with a full documentation page. See a full example of the button component [here](https://github.com/nrwl/nx-recipes/tree/main/storybook-compodoc-angular/apps/web/src/app/butn/butn.component.ts). The generated documentation of this example will look like this:\n\n![Generated Docs page for the Button](/shared/guides/storybook/button-docs.png)\n\nWhen you run Compodoc, it will generate a `documentation.json` file. Storybook will then use that file to render the documentation in the `Docs` tab.\n\n## How to enable Compodoc for Storybook\n\nThe main things that you need to do are:\n\n1. Include the component files in the TypeScript compilation for Compodoc (or any other files that contain your Compodoc documentation).\n2. Use `compodoc` to generate a `documentation.json` file.\n3. Tell Storybook to use the `documentation.json` file to display the documentation.\n\nLet's see how you can do that.\n\n{% callout type=\"note\" title=\"Note\" %}\nThis guide assumes that you have an Angular project with Storybook configured in your Nx workspace. If you do not know how to set these up, please read about [setting up Storybook for Angular](/storybook/overview-angular) on the Nx documentation website.\n{% /callout %}\n\n### 1. Install the necessary packages\n\nFirst we need to install the necessary packages:\n\n```bash\nyarn add -D @compodoc/compodoc\n```\n\nor\n\n```bash\nnpm install --save-dev @compodoc/compodoc\n```\n\n### 2. Include the component files in the TypeScript compilation for Compodoc\n\nWhen you are using Compodoc, you need to create a `tsconfig` file, and in the `include` array you need to place all the files that you want Compodoc to include in its compilation. Compodoc [suggests](https://compodoc.app/guides/installation.html) to add a `tsconfig.doc.json` to do that. Then, when running `compodoc` you can use the `-p` (or `--tsconfig`) flag to specify the path to that file. See all the options that Compodoc supports [here](https://compodoc.app/guides/options.html).\n\nIn the Storybook case, Storybook has the `--tsconfig` option [prefilled](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/utils/run-compodoc.ts#L23) to point to the `.storybook/tsconfig.json` file. As is noted in the [Storybook schema for the Angular builders](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/start-storybook/schema.json#L76), \"_Options `-p` with tsconfig path and `-d` with workspace root is always given._\". What this means is that you can add the paths to the component files (where Compodoc will look for JSDoc comment blocks) in the `include` array of the `.storybook/tsconfig.json` file. This is the file that Storybook will use to compile the TypeScript files, and it will also be the file that Compodoc will use to compile the TypeScript files.\n\nIn your project's `.storybook/tsconfig.json` file, in the `include` array, add the path to the component files (eg. `\"../src/**/*.component.ts\"`). For example, if you have an application called `web`, the file `apps/web/.storybook/tsconfig.json` will look like this:\n\n```json\n{\n \"extends\": \"../tsconfig.json\",\n \"compilerOptions\": {\n \"emitDecoratorMetadata\": true\n },\n \"files\": [\"../src/polyfills.ts\"],\n \"exclude\": [\"../**/*.spec.ts\"],\n \"include\": [\"../src/**/*.stories.ts\", \"../src/**/*.component.ts\", \"*.js\"]\n}\n```\n\n{% callout type=\"warning\" title=\"Don't forget all the paths!\" %}\nImportant! If you are importing stories from other places, and you want the docs for these stories to be generated, too, you need to add the paths to the other components in the `include` array, as well!\n\nFor example, if your stories paths look like this:\n\n```\n\"../../../**/**/src/lib/**/*.stories.ts\"\n```\n\nmake sure to also include\n\n```\n\"../../../**/**/src/lib/**/*.component.ts\"\n```\n\nfor the components to be included in the TypeScript compilation as well.\n\nThis applies in cases where, for example, you have [one single Storybook for your whole workspace](/recipes/storybook/one-storybook-for-all), where you import stories from all the projects. In that case, you need to import all the components as well!\n{% /callout %}\n\n### 3. Enable `compodoc` and configure it\n\n#### a. Set `compodoc: true`\n\nIn your project's `project.json` file (eg. `apps/web/project.json`), find the `storybook` and the `build-storybook` targets.\n\nIn the `options` you will see `\"compodoc\": false`. Change that to `true`.\n\n#### b. Set the directory\n\nStorybook has [preconfigured `compodoc`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/utils/run-compodoc.ts#L25) to generate a `documentation.json` file at the root of your workspace by default. We want to change that, and keep the documentation file project-specific. Of course you can change that later, or as you see fit for your use case. But let's keep it project-specific for now.\n\nIn your project's `project.json` file (eg. `apps/web/project.json`), find the `storybook` and the `build-storybook` targets. Below the `\"compodoc\"` option, create a new option called `\"compodocArgs` which contains the following: `[\"-e\", \"json\", \"-d\", \"apps/web\"]`. This means that the `exportFormat` (`-e`) will be `json` and the `output` directory (`-d`) will be `apps/web` (change that, of course, to the directory of your project).\n\nLet's see the result for our `web` app `storybook` target, for example (in `apps/web/project.json`):\n\n```json\n \"storybook\": {\n \"executor\": \"@storybook/angular:start-storybook\",\n \"options\": {\n \"port\": 4400,\n \"configDir\": \"apps/web/.storybook\",\n \"browserTarget\": \"web:build\",\n \"compodoc\": true,\n \"compodocArgs\": [\"-e\", \"json\", \"-d\", \"apps/web\"]\n },\n },\n```\n\n### 4. Let Storybook know of the `documentation.json` file\n\nIn your project's `.storybook/preview.js` file (for example for your `web` app the path would be `apps/web/.storybook/preview.js`), add the following:\n\n```js\nimport { setCompodocJson } from '@storybook/addon-docs/angular';\nimport docJson from '../documentation.json';\nsetCompodocJson(docJson);\n```\n\n### Now run Storybook and see the results!\n\nNow you can run Storybook or build Storybook, and documentation will be included. Just check the Docs tab!\n\n```bash\nnx storybook web\n```\n\nand\n\n```bash\nnx build-storybook web\n```\n" }, { "id": "angular-storybook-targets", diff --git a/docs/generated/packages/workspace.json b/docs/generated/packages/workspace.json index bbc92d9468..a901d89fe7 100644 --- a/docs/generated/packages/workspace.json +++ b/docs/generated/packages/workspace.json @@ -11,7 +11,7 @@ "id": "overview", "path": "/packages/workspace", "file": "shared/workspace-plugin", - "content": "The workspace plugin contains executors and generators that are useful for any Nx workspace. It should be present in every Nx workspace and other plugins build on it.\n\n## Creating Local Generators\n\nCodifying your organization's best practices into local generators is a great way to ensure that the best practices are easy to follow and implement. Running `nx g @nrwl/nx-plugin:plugin feature` will create a local plugin with a generator which is written the same way generators are written for Nx plugins.\n\n> See more about [local generators](/recipe/local-generators)\n\n## Reorganizing Projects\n\nAfter some time of working within a workspace, projects might need to be moved or sometimes even removed.\nThe workspace plugin provides the [`@nrwl/workspace:move`](/packages/workspace/generators/move) and [`@nrwl/workspace:remove`](/packages/workspace/generators/remove) generators to help aid with this.\n\n### Moving Projects\n\nRunning `nx g @nrwl/workspace:move --projectName my-lib --destination new/location/my-lib` will move the `my-lib` library to `libs/new/location/my-lib`.\n\nMoving the files manually can be done easily but a lot of steps are often missed when projects are moved. This generator will also handle the following:\n\n1. The project's files will be moved\n2. The project will be renamed to `new-location-my-lib`\n3. The path mapping in `tsconfig.base.json` will be changed to `@npmScope/new/location/my-lib`\n4. Imports in other projects will be changed to `@npmScope/new/location/my-lib`\n5. Paths in target options such as output path will be changed\n6. Other configuration will be updated too, such as `extends` in `tsconfig.json`, the name of the project in `jest.config.js`, and the extends in `.eslintrc.json`\n\n> See more about [`@nrwl/workspace:move`](/packages/workspace/generators/move)\n\n### Removing Projects\n\nRunning `nx g @nrwl/workspace:remove my-lib` will remove the `my-lib` from the workspace. It is important to note that sometimes, projects cannot be removed if they are still depended on by other projects.\n\nLike when moving projects, some steps are often missed when removing projects. This generator will also handle the following:\n\n1. Checks if other projects depend on the project being removed. This can be ignored via the `--forceRemove` flag.\n2. The project's files will be deleted.\n3. The project's configuration will be removed.\n4. The path mapping in `tsconfig.base.json` will be removed.\n\n> See more about [`@nrwl/workspace:remove`](/packages/workspace/generators/remove)\n\n## Running custom commands\n\nExecutors provide an optimized way of running targets but unfortunately, not every target has an executor written for it. The [`nx:run-commands`](/packages/nx/executors/run-commands) executor is an executor that runs any command or multiple commands in the shell. This can be useful when integrating with other tools which do not have an executor provided. There is also a generator to help configure this executor.\n\nRunning `nx g @nrwl/workspace:run-commands printhello --project my-feature-lib --command 'echo hello'` will create a `my-feature-lib:printhello` target that executes `echo hello` in the shell.\n\n> See more about [`nx:run-commands`](/packages/nx/executors/run-commands)\n" + "content": "The workspace plugin contains executors and generators that are useful for any Nx workspace. It should be present in every Nx workspace and other plugins build on it.\n\n## Creating Local Generators\n\nCodifying your organization's best practices into local generators is a great way to ensure that the best practices are easy to follow and implement. Running `nx g @nrwl/nx-plugin:plugin feature` will create a local plugin with a generator which is written the same way generators are written for Nx plugins.\n\n> See more about [local generators](/recipes/generators/local-generators)\n\n## Reorganizing Projects\n\nAfter some time of working within a workspace, projects might need to be moved or sometimes even removed.\nThe workspace plugin provides the [`@nrwl/workspace:move`](/packages/workspace/generators/move) and [`@nrwl/workspace:remove`](/packages/workspace/generators/remove) generators to help aid with this.\n\n### Moving Projects\n\nRunning `nx g @nrwl/workspace:move --projectName my-lib --destination new/location/my-lib` will move the `my-lib` library to `libs/new/location/my-lib`.\n\nMoving the files manually can be done easily but a lot of steps are often missed when projects are moved. This generator will also handle the following:\n\n1. The project's files will be moved\n2. The project will be renamed to `new-location-my-lib`\n3. The path mapping in `tsconfig.base.json` will be changed to `@npmScope/new/location/my-lib`\n4. Imports in other projects will be changed to `@npmScope/new/location/my-lib`\n5. Paths in target options such as output path will be changed\n6. Other configuration will be updated too, such as `extends` in `tsconfig.json`, the name of the project in `jest.config.js`, and the extends in `.eslintrc.json`\n\n> See more about [`@nrwl/workspace:move`](/packages/workspace/generators/move)\n\n### Removing Projects\n\nRunning `nx g @nrwl/workspace:remove my-lib` will remove the `my-lib` from the workspace. It is important to note that sometimes, projects cannot be removed if they are still depended on by other projects.\n\nLike when moving projects, some steps are often missed when removing projects. This generator will also handle the following:\n\n1. Checks if other projects depend on the project being removed. This can be ignored via the `--forceRemove` flag.\n2. The project's files will be deleted.\n3. The project's configuration will be removed.\n4. The path mapping in `tsconfig.base.json` will be removed.\n\n> See more about [`@nrwl/workspace:remove`](/packages/workspace/generators/remove)\n\n## Running custom commands\n\nExecutors provide an optimized way of running targets but unfortunately, not every target has an executor written for it. The [`nx:run-commands`](/packages/nx/executors/run-commands) executor is an executor that runs any command or multiple commands in the shell. This can be useful when integrating with other tools which do not have an executor provided. There is also a generator to help configure this executor.\n\nRunning `nx g @nrwl/workspace:run-commands printhello --project my-feature-lib --command 'echo hello'` will create a `my-feature-lib:printhello` target that executes `echo hello` in the shell.\n\n> See more about [`nx:run-commands`](/packages/nx/executors/run-commands)\n" }, { "name": "Nx, NodeJS and Typescript Versions", diff --git a/docs/map.json b/docs/map.json index 987ce00ba6..51f3ade4c1 100644 --- a/docs/map.json +++ b/docs/map.json @@ -481,388 +481,17 @@ "name": "CI Setup", "id": "ci-setup", "tags": ["distribute-task-execution"], - "file": "shared/ci-overview" + "path": "/recipes/ci-overview" }, { "name": "Adopting Nx", "id": "adopting-nx", - "file": "shared/recipes/adopt-nx" + "path": "/recipes/adopting-nx" }, { "name": "All Recipes »", "id": "all", - "file": "shared/recipes/recipe-list" - } - ] - }, - { - "name": "Recipe", - "id": "recipe", - "description": "Learn quickly how to do things with Nx.", - "itemList": [ - { - "name": "Disable Graph Links Created from Analyzing Source Files", - "id": "analyze-source-files", - "tags": ["explore-graph"], - "file": "shared/recipes/analyze-source-files" - }, - { - "name": "Nx Console Generate Command", - "id": "console-generate-command", - "tags": ["integrate-with-editors"], - "file": "shared/recipes/console-generate-command" - }, - { - "name": "Nx Console Run Command", - "id": "console-run-command", - "tags": ["integrate-with-editors"], - "file": "shared/recipes/console-run-command" - }, - { - "name": "Nx Console Add Dependency Command", - "id": "console-add-dependency-command", - "tags": ["integrate-with-editors"], - "file": "shared/recipes/console-add-dependency-command" - }, - { - "name": "Nx Console Project Pane", - "id": "console-project-pane", - "tags": ["integrate-with-editors"], - "file": "shared/recipes/console-project-pane" - }, - { - "name": "Nx Console Keyboard Shortcuts", - "id": "console-shortcuts", - "tags": ["integrate-with-editors"], - "file": "shared/recipes/console-shortcuts" - }, - { - "name": "Advanced Update Nx", - "id": "advanced-update", - "tags": ["automate-updating-dependencies"], - "file": "shared/recipes/advanced-update" - }, - { - "name": "Set up a new workspace", - "id": "set-up-a-new-workspace", - "file": "shared/recipes/set-up-a-new-workspace" - }, - { - "name": "Setting up Azure Pipelines", - "id": "monorepo-ci-azure", - "file": "shared/monorepo-ci-azure" - }, - { - "name": "Setting up CircleCI", - "id": "monorepo-ci-circle-ci", - "file": "shared/monorepo-ci-circle-ci" - }, - { - "name": "Setting up GitHub Actions", - "id": "monorepo-ci-github-actions", - "file": "shared/monorepo-ci-github-actions" - }, - { - "name": "Setting up Jenkins", - "id": "monorepo-ci-jenkins", - "file": "shared/monorepo-ci-jenkins" - }, - { - "name": "Setting up GitLab", - "id": "monorepo-ci-gitlab", - "file": "shared/monorepo-ci-gitlab" - }, - { - "name": "Setting up Bitbucket", - "id": "monorepo-ci-bitbucket-pipelines", - "file": "shared/monorepo-ci-bitbucket-pipelines" - }, - { - "name": "Nx and Lerna", - "id": "lerna-and-nx", - "file": "shared/migration/lerna-and-nx" - }, - { - "name": "NPM/Yarn/PNPM workspaces", - "id": "adding-to-monorepo", - "file": "shared/migration/adding-to-monorepo" - }, - { - "name": "From CRA", - "id": "migration-cra", - "file": "shared/migration/migration-cra" - }, - { - "name": "From Angular CLI", - "id": "migration-angular", - "file": "shared/migration/migration-angular" - }, - { - "name": "From AngularJS", - "id": "migration-angularjs", - "file": "shared/migration/migration-angularjs" - }, - { - "name": "Preserving Git Histories", - "id": "preserving-git-histories", - "file": "shared/migration/preserving-git-histories" - }, - { - "name": "Manual migration", - "id": "manual", - "file": "shared/migration/manual" - }, - { - "name": "Running Custom Commands", - "id": "run-commands-executor", - "tags": ["use-task-executors"], - "file": "shared/running-custom-commands" - }, - { - "name": "Use Executor Configurations", - "id": "use-executor-configurations", - "tags": ["use-task-executors"], - "file": "shared/recipes/use-executor-configurations" - }, - { - "name": "Local Executors", - "id": "creating-custom-executors", - "tags": ["use-task-executors"], - "file": "shared/recipes/local-executors" - }, - { - "name": "Compose Executors", - "id": "compose-executors", - "tags": ["use-task-executors"], - "file": "shared/recipes/compose-executors" - }, - { - "name": "Local Generators", - "id": "local-generators", - "tags": ["use-code-generators"], - "file": "shared/recipes/local-generators" - }, - { - "name": "Composing Generators", - "id": "composing-generators", - "tags": ["use-code-generators"], - "file": "shared/generators/composing-generators" - }, - { - "name": "Generator Options", - "id": "generator-options", - "tags": ["use-code-generators"], - "file": "shared/generators/generator-options" - }, - { - "name": "Creating Files", - "id": "creating-files", - "tags": ["use-code-generators"], - "file": "shared/generators/creating-files" - }, - { - "name": "Modifying Files", - "id": "modifying-files", - "tags": ["use-code-generators"], - "file": "shared/generators/modifying-files" - }, - { - "name": "JavaScript and TypeScript", - "id": "js-and-ts", - "file": "shared/guides/js-and-ts" - }, - { - "name": "React Native with Nx", - "id": "react-native", - "file": "shared/guides/react-native" - }, - { - "name": "Adding Images, Fonts, and Files", - "id": "adding-assets-react", - "file": "shared/guides/adding-assets" - }, - { - "name": "Define Environment Variables", - "id": "define-environment-variables", - "tags": ["environment-variables"], - "file": "shared/guides/define-environment-variables" - }, - { - "name": "Use Environment Variables in React", - "id": "use-environment-variables-in-react", - "tags": ["environment-variables"], - "file": "shared/guides/use-environment-variables-in-react" - }, - { - "name": "Use Environment Variables in Angular", - "id": "use-environment-variables-in-angular", - "tags": ["environment-variables"], - "file": "shared/guides/use-environment-variables-in-angular" - }, - { - "name": "Setup incremental builds for Angular applications", - "id": "setup-incremental-builds-angular", - "file": "shared/guides/setup-incremental-builds-angular" - }, - { - "name": "Profiling Build Performance", - "id": "performance-profiling", - "tags": ["use-task-executors", "environment-variables"], - "file": "shared/guides/performance-profiling" - }, - { - "name": "Using ESLint in Nx Workspaces", - "id": "eslint", - "tags": ["enforce-project-boundaries"], - "file": "shared/eslint" - }, - { - "name": "Configuring Browser Support", - "id": "browser-support", - "file": "shared/guides/browser-support" - }, - { - "name": "Deploying Next.js applications to Vercel", - "id": "deploy-nextjs-to-vercel", - "file": "shared/guides/deploy-nextjs-to-vercel" - }, - { - "name": "Webpack 5 Migration", - "id": "webpack-5", - "file": "shared/guides/webpack-5" - }, - { - "name": "Using Tailwind CSS in React", - "id": "using-tailwind-css-in-react", - "file": "shared/guides/using-tailwind-css-in-react" - }, - { - "name": "React 18 Migration", - "id": "react-18", - "file": "shared/guides/react-18" - }, - { - "name": "Using Tailwind CSS with Angular projects", - "id": "using-tailwind-css-with-angular-projects", - "file": "shared/guides/using-tailwind-css-with-angular-projects" - }, - { - "name": "Using NgRx", - "id": "misc-ngrx", - "file": "shared/guides/misc-ngrx" - }, - { - "name": "Using Data Persistence operators", - "id": "misc-data-persistence", - "file": "shared/guides/misc-data-persistence" - }, - { - "name": "Customizing Webpack Config", - "id": "customize-webpack", - "tags": ["use-task-executors"], - "file": "shared/guides/customize-webpack" - }, - { - "name": "Faster Builds with Module Federation", - "id": "faster-builds", - "tags": ["use-task-executors"], - "file": "shared/guides/module-federation/faster-builds" - }, - { - "name": "Advanced Micro Frontends with Angular using Dynamic Federation", - "id": "dynamic-module-federation-with-angular", - "file": "shared/guides/module-federation/dynamic-mfe-angular" - }, - { - "name": "Nx Micro-Frontend Example", - "id": "nx-examples", - "file": "shared/examples/nx-examples" - }, - { - "name": "Powering Up React Development With Nx", - "id": "react-nx", - "file": "shared/examples/react-nx" - }, - { - "name": "Using Apollo GraphQL", - "id": "apollo-react", - "file": "shared/examples/apollo-react" - }, - { - "name": "Large Repo and Caching", - "id": "caching", - "file": "shared/examples/caching" - }, - { - "name": "Large Repo and DTE", - "id": "dte", - "file": "shared/examples/dte" - }, - { - "name": "Project Inference Plugins", - "id": "project-inference-plugins", - "tags": ["create-your-own-plugin"], - "file": "shared/extending-nx/project-inference-plugins" - }, - { - "name": "Project Graph Plugins", - "id": "project-graph-plugins", - "tags": ["create-your-own-plugin", "explore-graph"], - "file": "shared/extending-nx/project-graph-plugins" - }, - { - "name": "Ban Dependencies with Certain Tags", - "id": "ban-dependencies-with-tags", - "tags": ["enforce-project-boundaries"], - "file": "shared/recipes/ban-dependencies-with-tags" - }, - { - "name": "Tag in Multiple Dimensions", - "id": "tag-multiple-dimensions", - "tags": ["enforce-project-boundaries"], - "file": "shared/recipes/tag-multiple-dimensions" - }, - { - "name": "Ban External Imports", - "id": "ban-external-imports", - "tags": ["enforce-project-boundaries"], - "file": "shared/recipes/ban-external-imports" - }, - { - "name": "Tags Allow List", - "id": "tags-allow-list", - "tags": ["enforce-project-boundaries"], - "file": "shared/recipes/tags-allow-list" - }, - { - "name": "Export Project Graph", - "id": "export-project-graph", - "tags": ["explore-graph"], - "file": "shared/recipes/export-project-graph" - }, - { - "name": "Resolve Circular Dependencies", - "id": "resolve-circular-dependencies", - "tags": ["explore-graph"], - "file": "shared/recipes/resolve-circular-dependencies" - }, - { - "name": "Publishing Storybook: One main Storybook instance for all projects", - "id": "one-storybook-for-all", - "tags": ["storybook"], - "file": "shared/recipes/one-storybook-for-all" - }, - { - "name": "Publishing Storybook: One Storybook instance per scope", - "id": "one-storybook-per-scope", - "tags": ["storybook"], - "file": "shared/recipes/one-storybook-per-scope" - }, - { - "name": "Publishing Storybook: One main Storybook instance using Storybook Composition", - "id": "one-storybook-with-composition", - "tags": ["storybook"], - "file": "shared/recipes/one-storybook-with-composition" + "path": "/recipes" } ] }, @@ -950,6 +579,466 @@ } ] }, + { + "name": "Nx Recipes", + "id": "nx-recipes", + "description": "Learn quickly how to do things with Nx.", + "itemList": [ + { + "name": "Getting Started", + "id": "getting-started", + "description": "Basic information to get you started.", + "itemList": [ + { + "name": "Set up a new workspace", + "id": "set-up-a-new-workspace", + "description": "How to setup quickly a new Nx workspace.", + "file": "shared/recipes/set-up-a-new-workspace" + } + ] + }, + { + "name": "Nx Console", + "id": "nx-console", + "description": "Checkout all the recipes related to Nx Console.", + "itemList": [ + { + "name": "Nx Console Generate Command", + "id": "console-generate-command", + "tags": ["integrate-with-editors"], + "file": "shared/recipes/console-generate-command" + }, + { + "name": "Nx Console Run Command", + "id": "console-run-command", + "tags": ["integrate-with-editors"], + "file": "shared/recipes/console-run-command" + }, + { + "name": "Nx Console Add Dependency Command", + "id": "console-add-dependency-command", + "tags": ["integrate-with-editors"], + "file": "shared/recipes/console-add-dependency-command" + }, + { + "name": "Nx Console Project Pane", + "id": "console-project-pane", + "tags": ["integrate-with-editors"], + "file": "shared/recipes/console-project-pane" + }, + { + "name": "Nx Console Keyboard Shortcuts", + "id": "console-shortcuts", + "tags": ["integrate-with-editors"], + "file": "shared/recipes/console-shortcuts" + } + ] + }, + { + "name": "CI", + "id": "ci", + "description": "All recipes about how to use Nx to make your CI faster.", + "itemList": [ + { + "name": "CI Setup", + "id": "ci-setup", + "tags": ["distribute-task-execution"], + "file": "shared/ci-overview" + }, + { + "name": "Setting up Azure Pipelines", + "id": "monorepo-ci-azure", + "file": "shared/monorepo-ci-azure" + }, + { + "name": "Setting up CircleCI", + "id": "monorepo-ci-circle-ci", + "file": "shared/monorepo-ci-circle-ci" + }, + { + "name": "Setting up GitHub Actions", + "id": "monorepo-ci-github-actions", + "file": "shared/monorepo-ci-github-actions" + }, + { + "name": "Setting up Jenkins", + "id": "monorepo-ci-jenkins", + "file": "shared/monorepo-ci-jenkins" + }, + { + "name": "Setting up GitLab", + "id": "monorepo-ci-gitlab", + "file": "shared/monorepo-ci-gitlab" + }, + { + "name": "Setting up Bitbucket", + "id": "monorepo-ci-bitbucket-pipelines", + "file": "shared/monorepo-ci-bitbucket-pipelines" + } + ] + }, + { + "name": "Adopting Nx", + "id": "adopting-nx", + "description": "Adopting Nx incrementally, on existing project or from scratch.", + "itemList": [ + { + "name": "Nx and Lerna", + "id": "lerna-and-nx", + "file": "shared/migration/lerna-and-nx" + }, + { + "name": "NPM/Yarn/PNPM workspaces", + "id": "adding-to-monorepo", + "file": "shared/migration/adding-to-monorepo" + }, + { + "name": "From CRA", + "id": "migration-cra", + "file": "shared/migration/migration-cra" + }, + { + "name": "From Angular CLI", + "id": "migration-angular", + "file": "shared/migration/migration-angular" + }, + { + "name": "From AngularJS", + "id": "migration-angularjs", + "file": "shared/migration/migration-angularjs" + }, + { + "name": "Preserving Git Histories", + "id": "preserving-git-histories", + "file": "shared/migration/preserving-git-histories" + }, + { + "name": "Manual migration", + "id": "manual", + "file": "shared/migration/manual" + } + ] + }, + { + "name": "Executors", + "id": "executors", + "description": "Use, extend and compose executors.", + "itemList": [ + { + "name": "Use Executor Configurations", + "id": "use-executor-configurations", + "tags": ["use-task-executors"], + "file": "shared/recipes/use-executor-configurations" + }, + { + "name": "Running Custom Commands", + "id": "run-commands-executor", + "tags": ["use-task-executors"], + "file": "shared/running-custom-commands" + }, + { + "name": "Local Executors", + "id": "creating-custom-executors", + "tags": ["use-task-executors"], + "file": "shared/recipes/local-executors" + }, + { + "name": "Compose Executors", + "id": "compose-executors", + "tags": ["use-task-executors"], + "file": "shared/recipes/compose-executors" + } + ] + }, + { + "name": "Generators", + "id": "generators", + "description": "Use, extend and compose generators.", + "itemList": [ + { + "name": "Local Generators", + "id": "local-generators", + "tags": ["use-code-generators"], + "file": "shared/recipes/local-generators" + }, + { + "name": "Composing Generators", + "id": "composing-generators", + "tags": ["use-code-generators"], + "file": "shared/generators/composing-generators" + }, + { + "name": "Generator Options", + "id": "generator-options", + "tags": ["use-code-generators"], + "file": "shared/generators/generator-options" + }, + { + "name": "Creating Files", + "id": "creating-files", + "tags": ["use-code-generators"], + "file": "shared/generators/creating-files" + }, + { + "name": "Modifying Files", + "id": "modifying-files", + "tags": ["use-code-generators"], + "file": "shared/generators/modifying-files" + } + ] + }, + { + "name": "Advanced Plugins", + "id": "advanced-plugins", + "description": "Learn more about creating your own plugin, extending Nx.", + "itemList": [ + { + "name": "Project Inference Plugins", + "id": "project-inference-plugins", + "tags": ["create-your-own-plugin"], + "file": "shared/extending-nx/project-inference-plugins" + }, + { + "name": "Project Graph Plugins", + "id": "project-graph-plugins", + "tags": ["create-your-own-plugin", "explore-graph"], + "file": "shared/extending-nx/project-graph-plugins" + } + ] + }, + { + "name": "Environment Variables", + "id": "environment-variables", + "description": "Using environment variables in an Nx workspace.", + "itemList": [ + { + "name": "Define Environment Variables", + "id": "define-environment-variables", + "tags": ["environment-variables"], + "file": "shared/guides/define-environment-variables" + }, + { + "name": "Use Environment Variables in React", + "id": "use-environment-variables-in-react", + "tags": ["environment-variables"], + "file": "shared/guides/use-environment-variables-in-react" + }, + { + "name": "Use Environment Variables in Angular", + "id": "use-environment-variables-in-angular", + "tags": ["environment-variables"], + "file": "shared/guides/use-environment-variables-in-angular" + } + ] + }, + { + "name": "Module Federation and Micro Frontends", + "id": "module-federation", + "description": "How to work with and setup Module Federation with Nx.", + "itemList": [ + { + "name": "Faster Builds with Module Federation", + "id": "faster-builds", + "tags": ["use-task-executors"], + "file": "shared/guides/module-federation/faster-builds" + }, + { + "name": "Advanced Micro Frontends with Angular using Dynamic Federation", + "id": "dynamic-module-federation-with-angular", + "file": "shared/guides/module-federation/dynamic-mfe-angular" + }, + { + "name": "Nx Micro-Frontend Example", + "id": "nx-examples", + "file": "shared/examples/nx-examples" + } + ] + }, + { + "name": "Storybook", + "id": "storybook", + "description": "Storybook how tos", + "itemList": [ + { + "name": "Publishing Storybook: One main Storybook instance for all projects", + "id": "one-storybook-for-all", + "tags": ["storybook"], + "file": "shared/recipes/one-storybook-for-all" + }, + { + "name": "Publishing Storybook: One Storybook instance per scope", + "id": "one-storybook-per-scope", + "tags": ["storybook"], + "file": "shared/recipes/one-storybook-per-scope" + }, + { + "name": "Publishing Storybook: One main Storybook instance using Storybook Composition", + "id": "one-storybook-with-composition", + "tags": ["storybook"], + "file": "shared/recipes/one-storybook-with-composition" + } + ] + }, + { + "name": "Other", + "id": "other", + "description": "Other recipes you will find useful.", + "itemList": [ + { + "name": "Disable Graph Links Created from Analyzing Source Files", + "id": "analyze-source-files", + "tags": ["explore-graph"], + "file": "shared/recipes/analyze-source-files" + }, + + { + "name": "Advanced Update Nx", + "id": "advanced-update", + "tags": ["automate-updating-dependencies"], + "file": "shared/recipes/advanced-update" + }, + + { + "name": "JavaScript and TypeScript", + "id": "js-and-ts", + "file": "shared/guides/js-and-ts" + }, + { + "name": "React Native with Nx", + "id": "react-native", + "file": "shared/guides/react-native" + }, + { + "name": "Adding Images, Fonts, and Files", + "id": "adding-assets-react", + "file": "shared/guides/adding-assets" + }, + + { + "name": "Setup incremental builds for Angular applications", + "id": "setup-incremental-builds-angular", + "file": "shared/guides/setup-incremental-builds-angular" + }, + { + "name": "Profiling Build Performance", + "id": "performance-profiling", + "tags": ["use-task-executors", "environment-variables"], + "file": "shared/guides/performance-profiling" + }, + { + "name": "Using ESLint in Nx Workspaces", + "id": "eslint", + "tags": ["enforce-project-boundaries"], + "file": "shared/eslint" + }, + { + "name": "Configuring Browser Support", + "id": "browser-support", + "file": "shared/guides/browser-support" + }, + { + "name": "Deploying Next.js applications to Vercel", + "id": "deploy-nextjs-to-vercel", + "file": "shared/guides/deploy-nextjs-to-vercel" + }, + { + "name": "Webpack 5 Migration", + "id": "webpack-5", + "file": "shared/guides/webpack-5" + }, + { + "name": "Using Tailwind CSS in React", + "id": "using-tailwind-css-in-react", + "file": "shared/guides/using-tailwind-css-in-react" + }, + { + "name": "React 18 Migration", + "id": "react-18", + "file": "shared/guides/react-18" + }, + { + "name": "Using Tailwind CSS with Angular projects", + "id": "using-tailwind-css-with-angular-projects", + "file": "shared/guides/using-tailwind-css-with-angular-projects" + }, + { + "name": "Using NgRx", + "id": "misc-ngrx", + "file": "shared/guides/misc-ngrx" + }, + { + "name": "Using Data Persistence operators", + "id": "misc-data-persistence", + "file": "shared/guides/misc-data-persistence" + }, + { + "name": "Customizing Webpack Config", + "id": "customize-webpack", + "tags": ["use-task-executors"], + "file": "shared/guides/customize-webpack" + }, + + { + "name": "Powering Up React Development With Nx", + "id": "react-nx", + "file": "shared/examples/react-nx" + }, + { + "name": "Using Apollo GraphQL", + "id": "apollo-react", + "file": "shared/examples/apollo-react" + }, + { + "name": "Large Repo and Caching", + "id": "caching", + "file": "shared/examples/caching" + }, + { + "name": "Large Repo and DTE", + "id": "dte", + "file": "shared/examples/dte" + }, + + { + "name": "Ban Dependencies with Certain Tags", + "id": "ban-dependencies-with-tags", + "tags": ["enforce-project-boundaries"], + "file": "shared/recipes/ban-dependencies-with-tags" + }, + { + "name": "Tag in Multiple Dimensions", + "id": "tag-multiple-dimensions", + "tags": ["enforce-project-boundaries"], + "file": "shared/recipes/tag-multiple-dimensions" + }, + { + "name": "Ban External Imports", + "id": "ban-external-imports", + "tags": ["enforce-project-boundaries"], + "file": "shared/recipes/ban-external-imports" + }, + { + "name": "Tags Allow List", + "id": "tags-allow-list", + "tags": ["enforce-project-boundaries"], + "file": "shared/recipes/tags-allow-list" + }, + { + "name": "Export Project Graph", + "id": "export-project-graph", + "tags": ["explore-graph"], + "file": "shared/recipes/export-project-graph" + }, + { + "name": "Resolve Circular Dependencies", + "id": "resolve-circular-dependencies", + "tags": ["explore-graph"], + "file": "shared/recipes/resolve-circular-dependencies" + } + ] + } + ] + }, { "name": "Nx Cloud docs", "id": "nx-cloud-documentation", diff --git a/docs/nx-cloud/set-up/set-up-dte.md b/docs/nx-cloud/set-up/set-up-dte.md index cbcaf4ca08..27fdb079f3 100644 --- a/docs/nx-cloud/set-up/set-up-dte.md +++ b/docs/nx-cloud/set-up/set-up-dte.md @@ -129,11 +129,11 @@ CI/CD (e.g., deployment). They mainly focus on configuring Nx correctly. Read the guides for more information on how to configure them in CI. -- [Overview](/recipes/ci-setup#distributed-ci-with-nx-cloud) -- [Azure Pipelines](/recipe/monorepo-ci-azure#distributed-ci-with-nx-cloud) -- [Circle CI](/recipe/monorepo-ci-circle-ci#distributed-ci-with-nx-cloud) -- [GitHub Actions](/recipe/monorepo-ci-github-actions#distributed-ci-with-nx-cloud) -- [Jenkins](/recipe/monorepo-ci-jenkins#distributed-ci-with-nx-cloud) +- [Overview](/recipes/ci/ci-setup#distributed-ci-with-nx-cloud) +- [Azure Pipelines](/recipes/ci/monorepo-ci-azure#distributed-ci-with-nx-cloud) +- [Circle CI](/recipes/ci/monorepo-ci-circle-ci#distributed-ci-with-nx-cloud) +- [GitHub Actions](/recipes/ci/monorepo-ci-github-actions#distributed-ci-with-nx-cloud) +- [Jenkins](/recipes/ci/monorepo-ci-jenkins#distributed-ci-with-nx-cloud) Note that only cacheable operations can be distributed because they have to be replayed on the main job. diff --git a/docs/shared/angular-plugin.md b/docs/shared/angular-plugin.md index e4c9fcd200..b44f739942 100644 --- a/docs/shared/angular-plugin.md +++ b/docs/shared/angular-plugin.md @@ -10,7 +10,7 @@ The Nx Plugin for Angular contains executors, generators, and utilities for mana - Utilities for automatic workspace refactoring. {% callout type="note" title="Currently using the Angular CLI?" %} -You can easily and mostly **automatically migrate from an Angular CLI** project to Nx! Learn more [here](/recipe/migration-angular). +You can easily and mostly **automatically migrate from an Angular CLI** project to Nx! Learn more [here](/recipes/adopting-nx/migration-angular). {% /callout %} ## Setting up the Angular plugin @@ -81,8 +81,8 @@ Read more about: - [Angular Nx Tutorial](/angular-tutorial/01-create-application) - [Migrating from the Angular CLI](recipe/migration-angular) -- [Setup Module Federation with Angular and Nx](/recipe/faster-builds) -- [Using NgRx](/recipe/misc-ngrx) -- [Using Data Persistence operators](/recipe/misc-data-persistence) -- [Upgrading an AngularJS application to Angular](/recipe/migration-angularjs) -- [Using Tailwind CSS with Angular projects](/recipe/using-tailwind-css-with-angular-projects) +- [Setup Module Federation with Angular and Nx](/recipes/module-federation/faster-builds) +- [Using NgRx](/recipes/other/misc-ngrx) +- [Using Data Persistence operators](/recipes/other/misc-data-persistence) +- [Upgrading an AngularJS application to Angular](/recipes/adopting-nx/migration-angularjs) +- [Using Tailwind CSS with Angular projects](/recipes/other/using-tailwind-css-with-angular-projects) diff --git a/docs/shared/ci-overview.md b/docs/shared/ci-overview.md index 170dad4304..339c1bc2d1 100644 --- a/docs/shared/ci-overview.md +++ b/docs/shared/ci-overview.md @@ -51,9 +51,9 @@ Learn more about configuring your CI environment using Nx Cloud with [Distribute The following guides cover optimizing your CI/CD environments with affected commands and distributed caching: -- [Setting up CI using Azure Pipelines](/recipe/monorepo-ci-azure) -- [Setting up CI using CircleCI](/recipe/monorepo-ci-circle-ci) -- [Setting up CI using GitHub Actions](/recipe/monorepo-ci-github-actions) -- [Setting up CI using Jenkins](/recipe/monorepo-ci-jenkins) -- [Setting up CI using GitLab](/recipe/monorepo-ci-gitlab) -- [Setting up CI using Bitbucket](/recipe/monorepo-ci-bitbucket-pipelines) +- [Setting up CI using Azure Pipelines](/recipes/ci/monorepo-ci-azure) +- [Setting up CI using CircleCI](/recipes/ci/monorepo-ci-circle-ci) +- [Setting up CI using GitHub Actions](/recipes/ci/monorepo-ci-github-actions) +- [Setting up CI using Jenkins](/recipes/ci/monorepo-ci-jenkins) +- [Setting up CI using GitLab](/recipes/ci/monorepo-ci-gitlab) +- [Setting up CI using Bitbucket](/recipes/ci/monorepo-ci-bitbucket-pipelines) diff --git a/docs/shared/core-features/automate-updating-dependencies.md b/docs/shared/core-features/automate-updating-dependencies.md index 6a02ee70d9..38e5200dff 100644 --- a/docs/shared/core-features/automate-updating-dependencies.md +++ b/docs/shared/core-features/automate-updating-dependencies.md @@ -61,4 +61,4 @@ Note: You may want to keep the `migrations.json` until every branch that was cre ## Problems? -If you can't run `nx migrate --run-migrations` all in one step, try the tips in [Advanced Update Process](/recipe/advanced-update) +If you can't run `nx migrate --run-migrations` all in one step, try the tips in [Advanced Update Process](/recipes/other/advanced-update) diff --git a/docs/shared/deprecated/workspace-json.md b/docs/shared/deprecated/workspace-json.md index 0efbaf142a..00603ade96 100644 --- a/docs/shared/deprecated/workspace-json.md +++ b/docs/shared/deprecated/workspace-json.md @@ -5,7 +5,7 @@ Nx used to have a `workspace.json` file at the root of the repo that at various 1. Identified the locations of all project in the repo 2. Contained the target configuration for all projects -Identifying the locations of projects is now done automatically through project inference. You can even customize how projects are inferred with a [project inference plugin](/recipe/project-inference-plugins). +Identifying the locations of projects is now done automatically through project inference. You can even customize how projects are inferred with a [project inference plugin](/recipes/advanced-plugins/project-inference-plugins). The target configuration for each project is now stored in individual `project.json` files or `package.json` files. diff --git a/docs/shared/eslint-plugin-nx.md b/docs/shared/eslint-plugin-nx.md index ea5a8b5317..98d6c3c698 100644 --- a/docs/shared/eslint-plugin-nx.md +++ b/docs/shared/eslint-plugin-nx.md @@ -84,8 +84,8 @@ You can use `enforce-module-boundaries` rule by adding it to your ESLint rules c Read more about proper usage of this rule: - [Enforce Project Boundaries](/core-features/enforce-project-boundaries) -- [Ban Dependencies with Certain Tags](/recipe/ban-dependencies-with-tags) -- [Tag in Multiple Dimensions](/recipe/tag-multiple-dimensions) -- [Ban External Imports](/recipe/ban-external-imports) -- [Tags Allow List](/recipe/tags-allow-list) +- [Ban Dependencies with Certain Tags](/recipes/other/ban-dependencies-with-tags) +- [Tag in Multiple Dimensions](/recipes/other/tag-multiple-dimensions) +- [Ban External Imports](/recipes/other/ban-external-imports) +- [Tags Allow List](/recipes/other/tags-allow-list) - [Taming Code Organization with Module Boundaries in Nx](https://blog.nrwl.io/mastering-the-project-boundaries-in-nx-f095852f5bf4) diff --git a/docs/shared/generators/modifying-files.md b/docs/shared/generators/modifying-files.md index 8a0d5fa44e..ec151da6ea 100644 --- a/docs/shared/generators/modifying-files.md +++ b/docs/shared/generators/modifying-files.md @@ -4,7 +4,7 @@ Modifying existing files is an order of magnitude harder than creating new files ## Compose Existing Generators -If you can compose together existing generators to modify the files you need, you should take that approach. See [Composing Generators](/recipe/composing-generators) for more information. +If you can compose together existing generators to modify the files you need, you should take that approach. See [Composing Generators](/recipes/generators/composing-generators) for more information. ## Modify JSON Files diff --git a/docs/shared/getting-started/intro.md b/docs/shared/getting-started/intro.md index 1bb0ee76a8..04c8c40765 100644 --- a/docs/shared/getting-started/intro.md +++ b/docs/shared/getting-started/intro.md @@ -19,7 +19,7 @@ Here's a deep dive on [Integrated Repos vs. Package-Based Repos](/concepts/integ ## Getting Started - [Nx core tutorial](/core-tutorial/01-create-blog) will help you understand the core of Nx. -- [Adding Nx to an existing monorepo](/recipe/adding-to-monorepo) shows several paths to adopting Nx in your organization. +- [Adding Nx to an existing monorepo](/recipes/adopting-nx/adding-to-monorepo) shows several paths to adopting Nx in your organization. - [Mental model](/concepts/mental-model) is a good starting point for those who like to understand things theoretically first. If you want to use Nx plugins to really level up your productivity, pick one of the following tutorials: diff --git a/docs/shared/guides/customize-webpack.md b/docs/shared/guides/customize-webpack.md index 1be79f71fb..cf6b3c2ca6 100644 --- a/docs/shared/guides/customize-webpack.md +++ b/docs/shared/guides/customize-webpack.md @@ -69,7 +69,7 @@ module.exports = (config, context) => { ## Module Federation -If you use the [Module Federation](/recipe/faster-builds) support from `@nrwl/angular` or `@nrwl/react` then +If you use the [Module Federation](/recipes/module-federation/faster-builds) support from `@nrwl/angular` or `@nrwl/react` then you can customize your webpack configuration as follows. ```typescript diff --git a/docs/shared/guides/integrated-repo-folder-structure.md b/docs/shared/guides/integrated-repo-folder-structure.md index a431ddede8..0c631e81ef 100644 --- a/docs/shared/guides/integrated-repo-folder-structure.md +++ b/docs/shared/guides/integrated-repo-folder-structure.md @@ -16,7 +16,7 @@ myorg/ `/libs/` contains the library projects. There are many kinds of libraries, and each library defines its own external API so that boundaries between libraries remain clear. -`/tools/` contains scripts that act on your code base. This could be database scripts, [local executors](/recipe/creating-custom-executors), or [local generators](/recipe/local-generators). +`/tools/` contains scripts that act on your code base. This could be database scripts, [local executors](/recipes/executors/creating-custom-executors), or [local generators](/recipes/generators/local-generators). `/nx.json` configures the Nx CLI itself. It tells Nx what needs to be cached, how to run tasks etc. diff --git a/docs/shared/guides/module-federation/micro-frontend-architecture.md b/docs/shared/guides/module-federation/micro-frontend-architecture.md index 846d49a51b..d0c69b7734 100644 --- a/docs/shared/guides/module-federation/micro-frontend-architecture.md +++ b/docs/shared/guides/module-federation/micro-frontend-architecture.md @@ -1,9 +1,9 @@ # Micro Frontend Architecture -Since version 14, Nx provides out-of-the-box [Module Federation](/recipe/faster-builds) support to both React +Since version 14, Nx provides out-of-the-box [Module Federation](/recipes/module-federation/faster-builds) support to both React and Angular. The Micro Frontend (MFE) architecture builds on top of Module Federation by providing _independent deployability_. -If you have not read the [Module Federation guide](/recipe/faster-builds) yet, we recommend that you read it +If you have not read the [Module Federation guide](/recipes/module-federation/faster-builds) yet, we recommend that you read it before continuing with this MFE guide. ## When should I use micro frontend architecture? @@ -17,7 +17,7 @@ of MFEs and decide whether it makes sense for your own teams. logic that breaks compatibility with remotes. If you are looking at optimizing builds and do not need independent deployments, we recommend reading our guide on -[Faster Builds with Module Federation](/recipe/faster-builds). +[Faster Builds with Module Federation](/recipes/module-federation/faster-builds). If you need to use MFEs, keep reading, and we'll examine the architecture and strategies to deal with shared libraries and deployments. @@ -29,7 +29,7 @@ With MFE architecture, a large application is split into: 1. A single **Host** application that references external... 2. **Remote** applications, which handle a single domain or feature. -In a normal Module Federation setup, we [recommend setting up implicit dependencies](/recipe/faster-builds#architectural-overview) +In a normal Module Federation setup, we [recommend setting up implicit dependencies](/recipes/module-federation/faster-builds#architectural-overview) from the host application to remote applications. However, in an MFE architecture you _do not_ want these dependencies to exist between host and remotes. diff --git a/docs/shared/guides/storybook/angular-storybook-compodoc.md b/docs/shared/guides/storybook/angular-storybook-compodoc.md index 4845dbe77b..53b527d0da 100644 --- a/docs/shared/guides/storybook/angular-storybook-compodoc.md +++ b/docs/shared/guides/storybook/angular-storybook-compodoc.md @@ -99,7 +99,7 @@ make sure to also include for the components to be included in the TypeScript compilation as well. -This applies in cases where, for example, you have [one single Storybook for your whole workspace](/recipe/one-storybook-for-all), where you import stories from all the projects. In that case, you need to import all the components as well! +This applies in cases where, for example, you have [one single Storybook for your whole workspace](/recipes/storybook/one-storybook-for-all), where you import stories from all the projects. In that case, you need to import all the components as well! {% /callout %} ### 3. Enable `compodoc` and configure it diff --git a/docs/shared/guides/storybook/best-practices.md b/docs/shared/guides/storybook/best-practices.md index c538e18253..633ff534c1 100644 --- a/docs/shared/guides/storybook/best-practices.md +++ b/docs/shared/guides/storybook/best-practices.md @@ -132,9 +132,9 @@ Before moving on to the examples section, it could be useful to read the [Librar You can check out the following examples (recipes) to see publishing strategies for Storybook in Nx: -- [One main Storybook instance for all projects](/recipe/one-storybook-for-all) -- [One Storybook instance per scope](/recipe/one-storybook-per-scope) -- [One main Storybook instance using Storybook Composition](/recipe/one-storybook-with-composition) +- [One main Storybook instance for all projects](/recipes/storybook/one-storybook-for-all) +- [One Storybook instance per scope](/recipes/storybook/one-storybook-per-scope) +- [One main Storybook instance using Storybook Composition](/recipes/storybook/one-storybook-with-composition) ## Conclusion diff --git a/docs/shared/guides/webpack-5.md b/docs/shared/guides/webpack-5.md index 4f118605a9..8093f6c012 100644 --- a/docs/shared/guides/webpack-5.md +++ b/docs/shared/guides/webpack-5.md @@ -1,7 +1,7 @@ # Webpack 5 Migration {% callout type="note" title="Customizing webpack" %} -This page is for Nx 13 migration to Webpack 5, and is no longer applicable in Nx 14+. For customizing Webpack, see [our recipe on this topic](/recipe/customize-webpack). +This page is for Nx 13 migration to Webpack 5, and is no longer applicable in Nx 14+. For customizing Webpack, see [our recipe on this topic](/recipes/other/customize-webpack). {% /callout %} Starting in Nx 13, we only support Webpack 5, which is automatically enabled for all workspaces. diff --git a/docs/shared/guides/why-monorepos.md b/docs/shared/guides/why-monorepos.md index 468aa15313..0cbd20ae2e 100644 --- a/docs/shared/guides/why-monorepos.md +++ b/docs/shared/guides/why-monorepos.md @@ -3,7 +3,7 @@ A monorepo is a single git repository that holds the source code for multiple applications and libraries, along with the tooling for them. {% callout type="note" title="Lerna users" %} -If you are familiar with Lerna or Yarn workspaces, check out [this guide](/recipe/lerna-and-nx) (with a quick video) showing how to add Nx to a Lerna/Yarn workspace, what the difference is, when to use both and when to use just Nx. +If you are familiar with Lerna or Yarn workspaces, check out [this guide](/recipes/adopting-nx/lerna-and-nx) (with a quick video) showing how to add Nx to a Lerna/Yarn workspace, what the difference is, when to use both and when to use just Nx. {% /callout %} ## What are the benefits of a monorepo? diff --git a/docs/shared/incremental-builds.md b/docs/shared/incremental-builds.md index 4c8cd1b2db..5decfe21e5 100644 --- a/docs/shared/incremental-builds.md +++ b/docs/shared/incremental-builds.md @@ -78,4 +78,4 @@ But there are other ways to make the build process incremental. One of them is u When using WebPack Module Federation, you split the application into multiple webpack builds. Imagine the application has 3 big sections, and they are built using 3 webpack builds: `W1`, `W2`, and `W3`. Each of them has to build shared code in addition to building the corresponding application section code. So the time it takes to build all of them (`W1` + `W2` + `W3`) will be greater than `W`. However, if you change only Section 1, you will only need to run `W1`. `W2` and `W3` will be retrieved from cache. In addition, `W1`, `W2`, and `W3` can run on separate machines. Because of that, both the CI time and the local serve time can be drastically reduced. -Learn more: [Faster Builds with Module Federation](/recipe/faster-builds) +Learn more: [Faster Builds with Module Federation](/recipes/module-federation/faster-builds) diff --git a/docs/shared/migration/adding-to-monorepo.md b/docs/shared/migration/adding-to-monorepo.md index 0fce7c784e..66b9d5312a 100644 --- a/docs/shared/migration/adding-to-monorepo.md +++ b/docs/shared/migration/adding-to-monorepo.md @@ -1,7 +1,7 @@ # Adding Nx to Lerna/Yarn/PNPM/NPM Workspace {% callout type="note" title="Migrating from Lerna?" %} -Interested in migrating from [Lerna](https://github.com/lerna/lerna) in particular? In case you missed it, Nrwl, the company behind Nx, [took over stewardship of Lerna](https://blog.nrwl.io/lerna-is-dead-long-live-lerna-61259f97dbd9). This allows for a much better integration between the two. [Read more in our dedicated guide](/recipe/lerna-and-nx). +Interested in migrating from [Lerna](https://github.com/lerna/lerna) in particular? In case you missed it, Nrwl, the company behind Nx, [took over stewardship of Lerna](https://blog.nrwl.io/lerna-is-dead-long-live-lerna-61259f97dbd9). This allows for a much better integration between the two. [Read more in our dedicated guide](/recipes/adopting-nx/lerna-and-nx). {% /callout %} **Short story:** you can use Nx easily together with your current Lerna/Yarn/PNPM/NPM monorepo setup. Why? To speed up @@ -62,7 +62,7 @@ This sets up Nx core in your existing monorepo which comes with a series of inte ## Looking for integrating Lerna and Nx? -Check out our dedicated guide: [Lerna and Nx](/recipe/lerna-and-nx) +Check out our dedicated guide: [Lerna and Nx](/recipes/adopting-nx/lerna-and-nx) ## Further customizations diff --git a/docs/shared/migration/manual.md b/docs/shared/migration/manual.md index 72a41ce3ab..da7f36029e 100644 --- a/docs/shared/migration/manual.md +++ b/docs/shared/migration/manual.md @@ -157,7 +157,7 @@ nx format:write Nx offers built-in tasks for the most common needs: `serve`, `build`, `test`, `e2e`, and `lint`. You likely have additional tasks that are needed to manage or deploy your codebase. These tasks might include deployment, i18n workflows, or uploading assets to CDNs. These tasks can be set up as scripts that you run manually with node, ts-node, or npm scripts. You can migrate those tasks over as-is, to begin with. -You should consider implementing them as Nx tasks which should be a quick transition with the `run-commands` builder. [The `run-commands` executor](/recipe/run-commands-executor) will allow you to run any custom commands you need as an Nx task. By implementing these commands in an Nx task, they are able to take advantage of the project graph in Nx and only run when necessary. They are also able to be cached and only be re-run when necessary. +You should consider implementing them as Nx tasks which should be a quick transition with the `run-commands` builder. [The `run-commands` executor](/recipes/executors/run-commands-executor) will allow you to run any custom commands you need as an Nx task. By implementing these commands in an Nx task, they are able to take advantage of the project graph in Nx and only run when necessary. They are also able to be cached and only be re-run when necessary. Your use-case may also be covered by one of our community plugins. Plugin authors are able to extend the functionality of Nx through our plugin API. diff --git a/docs/shared/migration/migration-cra.md b/docs/shared/migration/migration-cra.md index 219a4d13d8..49fd774d31 100644 --- a/docs/shared/migration/migration-cra.md +++ b/docs/shared/migration/migration-cra.md @@ -8,7 +8,7 @@ You can either use a CLI tool to migrate your app automatically, or you can foll This guide has been updated for Nx 13 and may not work for earlier versions of Nx. {% /callout %} -If you have a monorepo (more than one project in the same repo), follow the [Adding Nx to Lerna/Yarn/PNPM/NPM Workspace](/recipe/adding-to-monorepo) guide instead. +If you have a monorepo (more than one project in the same repo), follow the [Adding Nx to Lerna/Yarn/PNPM/NPM Workspace](/recipes/adopting-nx/adding-to-monorepo) guide instead. ## Using a tool that will do it for you @@ -21,7 +21,7 @@ npx cra-to-nx ``` Then just sit back and wait. After a while, take advantage of the [full magic of Nx](/getting-started/intro). -Start from [the commands mentioned in this article](/recipe/migration-cra#try-nx). +Start from [the commands mentioned in this article](/recipes/adopting-nx/migration-cra#try-nx). {% callout type="caution" title="Commit your changes" %} The command will fail if you try to execute it, and you have uncommitted changes in your repository. Commit any local changes, and then try to run the command. diff --git a/docs/shared/migration/preserving-git-histories.md b/docs/shared/migration/preserving-git-histories.md index 9848eee9b7..0a6ab7a2df 100644 --- a/docs/shared/migration/preserving-git-histories.md +++ b/docs/shared/migration/preserving-git-histories.md @@ -36,4 +36,4 @@ Note that for these files, the file history of the standalone project will not b ## Using `git mv` -If your standalone project was not an Nx workspace, it's likely that your migration work will also entail moving directories to match a typical Nx Workspace structure. You can find more information in the [Manual migration](/recipe/manual) page, but when migrating an existing project, you'll want to ensure that you use [`git mv`](https://git-scm.com/docs/git-mv) when moving a file or directory to ensure that file history from the old standalone repo is not lost! +If your standalone project was not an Nx workspace, it's likely that your migration work will also entail moving directories to match a typical Nx Workspace structure. You can find more information in the [Manual migration](/recipes/adopting-nx/manual) page, but when migrating an existing project, you'll want to ensure that you use [`git mv`](https://git-scm.com/docs/git-mv) when moving a file or directory to ensure that file history from the old standalone repo is not lost! diff --git a/docs/shared/monorepo-ci-azure.md b/docs/shared/monorepo-ci-azure.md index 6d1d97da32..f3e608d1bd 100644 --- a/docs/shared/monorepo-ci-azure.md +++ b/docs/shared/monorepo-ci-azure.md @@ -46,7 +46,7 @@ The `main` job implements the CI workflow. In order to use distributed task execution, we need to start agents and set the `NX_CLOUD_DISTRIBUTED_EXECUTION` flag to `true`. -Read more about the [Distributed CI setup with Nx Cloud](/recipes/ci-setup#distributed-ci-with-nx-cloud). +Read more about the [Distributed CI setup with Nx Cloud](/recipes/ci/ci-setup#distributed-ci-with-nx-cloud). ```yaml trigger: diff --git a/docs/shared/monorepo-ci-circle-ci.md b/docs/shared/monorepo-ci-circle-ci.md index 7a19f8b5e2..36e666f255 100644 --- a/docs/shared/monorepo-ci-circle-ci.md +++ b/docs/shared/monorepo-ci-circle-ci.md @@ -45,7 +45,7 @@ It should be a user token, not project token. In order to use distributed task execution, we need to start agents and set the `NX_CLOUD_DISTRIBUTED_EXECUTION` flag to `true`. -Read more about the [Distributed CI setup with Nx Cloud](/recipes/ci-setup#distributed-ci-with-nx-cloud). +Read more about the [Distributed CI setup with Nx Cloud](/recipes/ci/ci-setup#distributed-ci-with-nx-cloud). ```yaml version: 2.1 diff --git a/docs/shared/monorepo-ci-github-actions.md b/docs/shared/monorepo-ci-github-actions.md index 626fb92d45..0631f60f34 100644 --- a/docs/shared/monorepo-ci-github-actions.md +++ b/docs/shared/monorepo-ci-github-actions.md @@ -38,7 +38,7 @@ The `pr` and `main` jobs implement the CI workflow. Setting `timeout-minutes` is In order to use distributed task execution, we need to start agents and set the `NX_CLOUD_DISTRIBUTED_EXECUTION` flag to `true`. -Read more about the [Distributed CI setup with Nx Cloud](/recipes/ci-setup#distributed-ci-with-nx-cloud). +Read more about the [Distributed CI setup with Nx Cloud](/recipes/ci/ci-setup#distributed-ci-with-nx-cloud). ```yaml name: CI diff --git a/docs/shared/monorepo-ci-gitlab.md b/docs/shared/monorepo-ci-gitlab.md index 01eab848e2..c5f354ad82 100644 --- a/docs/shared/monorepo-ci-gitlab.md +++ b/docs/shared/monorepo-ci-gitlab.md @@ -67,7 +67,7 @@ The `build` and `test` jobs implement the CI workflow using `.distributed` as te In order to use distributed task execution, we need to start agents and set the `NX_CLOUD_DISTRIBUTED_EXECUTION` flag to `true`. -Read more about the [Distributed CI setup with Nx Cloud](/recipes/ci-setup#distributed-ci-with-nx-cloud). +Read more about the [Distributed CI setup with Nx Cloud](/recipes/ci/ci-setup#distributed-ci-with-nx-cloud). ```yaml image: node:18 diff --git a/docs/shared/monorepo-ci-jenkins.md b/docs/shared/monorepo-ci-jenkins.md index 849b3e62e0..8f5627c63a 100644 --- a/docs/shared/monorepo-ci-jenkins.md +++ b/docs/shared/monorepo-ci-jenkins.md @@ -57,7 +57,7 @@ The `pr` and `main` jobs implement the CI workflow. In order to use distributed task execution, we need to start agents and set the `NX_CLOUD_DISTRIBUTED_EXECUTION` flag to `true`. -Read more about the [Distributed CI setup with Nx Cloud](/recipes/ci-setup#distributed-ci-with-nx-cloud). +Read more about the [Distributed CI setup with Nx Cloud](/recipes/ci/ci-setup#distributed-ci-with-nx-cloud). ```groovy pipeline { diff --git a/docs/shared/next-plugin.md b/docs/shared/next-plugin.md index 00704d7a99..af7b697293 100644 --- a/docs/shared/next-plugin.md +++ b/docs/shared/next-plugin.md @@ -162,7 +162,7 @@ nx export my-new-app Once you are ready to deploy your Next.js application, you have absolute freedom to choose any hosting provider that fits your needs. -You may know that the company behind Next.js, Vercel, has a great hosting platform offering that is developed in tandem with Next.js itself to offer a great overall developer and user experience. We have detailed [how to deploy your Next.js application to Vercel in a separate guide](/recipe/deploy-nextjs-to-vercel). +You may know that the company behind Next.js, Vercel, has a great hosting platform offering that is developed in tandem with Next.js itself to offer a great overall developer and user experience. We have detailed [how to deploy your Next.js application to Vercel in a separate guide](/recipes/other/deploy-nextjs-to-vercel). ## More Documentation diff --git a/docs/shared/nx-plugin.md b/docs/shared/nx-plugin.md index b1dddd19c7..99abc2d4b0 100644 --- a/docs/shared/nx-plugin.md +++ b/docs/shared/nx-plugin.md @@ -259,7 +259,7 @@ export default async function (tree: Tree, options: PresetGeneratorSchema) { } ``` -To get an in-depth guide on customizing/running or debugging your generator see [local generators](/recipe/local-generators). +To get an in-depth guide on customizing/running or debugging your generator see [local generators](/recipes/generators/local-generators). #### Usage diff --git a/docs/shared/plugin-features/create-your-own-plugin.md b/docs/shared/plugin-features/create-your-own-plugin.md index 771f3b3f53..c66e136e74 100644 --- a/docs/shared/plugin-features/create-your-own-plugin.md +++ b/docs/shared/plugin-features/create-your-own-plugin.md @@ -29,7 +29,7 @@ Plugins have: - Plugins can provide a function `processProjectGraph` to add extra edges to the project graph. - This allows plugins to influence the behavior of `nx affected` and the project graph visualization. - - See [project graph plugins](/recipe/project-graph-plugins) for more information. + - See [project graph plugins](/recipes/advanced-plugins/project-graph-plugins) for more information. - **Project Inference Extensions** @@ -43,7 +43,7 @@ All the core plugins are written using Nx Devkit, and you can use the same utili executors. {% callout type="check" title="Plugins!" %} -The Nx team maintains a core set of plugins for many application and tooling frameworks. You can write [custom generators](/recipe/local-generators) and [executors](/recipe/creating-custom-executors) for your own workspace. You can also write your own plugin and share it with the community. The [Nx Plugin](/packages/nx-plugin) plugin provides guidance on how you can build your own custom plugins. +The Nx team maintains a core set of plugins for many application and tooling frameworks. You can write [custom generators](/recipes/generators/local-generators) and [executors](/recipes/executors/creating-custom-executors) for your own workspace. You can also write your own plugin and share it with the community. The [Nx Plugin](/packages/nx-plugin) plugin provides guidance on how you can build your own custom plugins. {% /callout %} ### Local workspace plugins @@ -74,7 +74,7 @@ Trees (ASTs), and more. ### Pay as you go As with most things in Nx, the core of Nx Devkit is very simple. It only uses language primitives and immutable -objects (the tree being the only exception). See [Simplest Generator](/recipe/creating-files) +objects (the tree being the only exception). See [Simplest Generator](/recipes/generators/creating-files) and [Simplest Executor](/plugin-features/use-task-executors#simplest-executor) for examples on creating generators and executors. The [Using Executors](/plugin-features/use-task-executors) and [Using Generators](/plugin-features/use-code-generators) guides also have additional information on executors @@ -83,6 +83,6 @@ and generators. ## Learn more - [Creating and Publishing Your Own Nx Plugin - Youtube](https://www.youtube.com/watch?v=vVT7Al01VZc) -- [Local generators](/recipe/local-generators) -- [Local executors](/recipe/creating-custom-executors) +- [Local generators](/recipes/generators/local-generators) +- [Local executors](/recipes/executors/creating-custom-executors) - [Nx Community Plugins](/community) diff --git a/docs/shared/plugin-features/use-code-generators.md b/docs/shared/plugin-features/use-code-generators.md index eae0aaaa28..332e3995ee 100644 --- a/docs/shared/plugin-features/use-code-generators.md +++ b/docs/shared/plugin-features/use-code-generators.md @@ -7,7 +7,7 @@ Generators provide a way to automate many tasks you regularly perform as part of There are three main types of generators: 1. **Plugin Generators** are available when an Nx plugin has been installed in your workspace. -2. **Local Generators** are generators that you can create for your own workspace. [Local generators](/recipe/local-generators) allow you to codify the processes that are unique to your own organization. +2. **Local Generators** are generators that you can create for your own workspace. [Local generators](/recipes/generators/local-generators) allow you to codify the processes that are unique to your own organization. 3. **Update Generators** are invoked by Nx plugins when you [update Nx](/recipes/adopting-nx) to keep your config files in sync with the latest versions of third party tools. ## Invoking Plugin Generators diff --git a/docs/shared/recipes/adopt-nx.md b/docs/shared/recipes/adopt-nx.md deleted file mode 100644 index 999f8854b2..0000000000 --- a/docs/shared/recipes/adopt-nx.md +++ /dev/null @@ -1,14 +0,0 @@ -# Adopting Nx - -There are several strategies you can use to adopt Nx in your organization, depending on where you're starting from. - -- [Nx and Lerna](/recipe/lerna-and-nx) -- [NPM/Yarn/PNPM workspaces](/recipe/adding-to-monorepo) -- [From CRA](/recipe/migration-cra) -- [From Angular CLI](/recipe/migration-angular) -- [From AngularJS](/recipe/migration-angularjs) -- [Manual migration](/recipe/manual) - -Other recipes related to adopting Nx: - -- [Preserving Git Histories](/recipe/preserving-git-histories) diff --git a/docs/shared/recipes/recipe-list.md b/docs/shared/recipes/recipe-list.md deleted file mode 100644 index 6dd2349fc8..0000000000 --- a/docs/shared/recipes/recipe-list.md +++ /dev/null @@ -1,96 +0,0 @@ -# All Recipes - -## Getting Started - -- [Set up a new workspace](/recipe/set-up-a-new-workspace) - -## Nx Console - -- [Generate Command](/recipe/console-generate-command) -- [Run Command](/recipe/console-run-command) -- [Project Pane](/recipe/console-project-pane) -- [Keyboard Shortcuts](/recipe/console-shortcuts) - -## CI - -- [Setting up Azure Pipelines](/recipe/monorepo-ci-azure) -- [Setting up CircleCI](/recipe/monorepo-ci-circle-ci) -- [Setting up GitHub Actions](/recipe/monorepo-ci-github-actions) -- [Setting up Jenkins](/recipe/monorepo-ci-jenkins) -- [Setting up GitLab](/recipe/monorepo-ci-gitlab) -- [Setting up Bitbucket](/recipe/monorepo-ci-bitbucket-pipelines) - -## Adopting Nx - -- [Nx and Lerna](/recipe/lerna-and-nx) -- [NPM/Yarn/PNPM workspaces](/recipe/adding-to-monorepo) -- [From CRA](/recipe/migration-cra) -- [From Angular CLI](/recipe/migration-angular) -- [From AngularJS](/recipe/migration-angularjs) -- [Manual migration](/recipe/manual) -- [Preserving Git Histories](/recipe/preserving-git-histories) - -## Executors - -- [Use Executor Configurations](/recipe/use-executor-configurations) -- [Running Custom Commands](/recipe/run-commands-executor) -- [Creating Custom Executors](/recipe/creating-custom-executors) -- [Compose Executors](/recipe/compose-executors) - -## Generators - -- [Local Generators](/recipe/local-generators) -- [Composing Generators](/recipe/composing-generators) -- [Generator Options](/recipe/generator-options) -- [Creating Files](/recipe/creating-files) -- [Modifying Files](/recipe/modifying-files) - -## Advanced Plugins - -- [Project Inference Plugins](/recipe/project-inference-plugins) -- [Project Graph Plugins](/recipe/project-graph-plugins) - -## Environment Variables - -- [Define Environment Variables](/recipe/define-environment-variables) -- [Use Environment Variables in React](/recipe/use-environment-variables-in-react) -- [Use Environment Variables in Angular](/recipe/use-environment-variables-in-angular) - -## Module Federation and Micro Frontends - -- [Faster Builds with Module Federation](/recipe/faster-builds) -- [Advanced Micro Frontends with Angular using Dynamic Federation](/recipe/dynamic-module-federation-with-angular) -- [Nx Micro-Frontend Example](/recipe/nx-examples) - -## Storybook - -- [Publishing Storybook: One main Storybook instance for all projects](/recipe/one-storybook-for-all) -- [Publishing Storybook: One Storybook instance per scope](/recipe/one-storybook-per-scope) -- [Publishing Storybook: One main Storybook instance using Storybook Composition](/recipe/one-storybook-with-composition) - -## Other - -- [JavaScript and TypeScript](/recipe/js-and-ts) -- [React Native with Nx](/recipe/react-native) -- [Adding Images, Fonts, and Files](/recipe/adding-assets-react) -- [Setup incremental builds for Angular applications](/recipe/setup-incremental-builds-angular) -- [Profiling Build Performance](/recipe/performance-profiling) -- [Using ESLint in Nx Workspaces](/recipe/eslint) -- [Configuring Browser Support](/recipe/browser-support) -- [Deploying Next.js applications to Vercel](/recipe/deploy-nextjs-to-vercel) -- [Webpack 5 Migration](/recipe/webpack-5) -- [Using Tailwind CSS in React](/recipe/using-tailwind-css-in-react) -- [React 18 Migration](/recipe/react-18) -- [Using Tailwind CSS with Angular projects](/recipe/using-tailwind-css-with-angular-projects) -- [Using NgRx](/recipe/misc-ngrx) -- [Using Data Persistence operators](/recipe/misc-data-persistence) -- [Customizing Webpack Config](/recipe/customize-webpack) -- [Powering Up React Development With Nx](/recipe/react-nx) -- [Using Apollo GraphQL](/recipe/apollo-react) -- [Large Repo and Caching](/recipe/caching) -- [Large Repo and DTE](/recipe/dte) -- [Ban Dependencies with Certain Tags](/recipe/ban-dependencies-with-tags) -- [Tag in Multiple Dimensions](/recipe/tag-multiple-dimensions) -- [Ban External Imports](/recipe/ban-external-imports) -- [Tags Allow List](/recipe/tags-allow-list) -- [Disable Graph Links Created from Analyzing Source Files](/recipe/analyze-source-files) diff --git a/docs/shared/reference/environment-variables.md b/docs/shared/reference/environment-variables.md index 1a970be4b7..1fabd88d87 100644 --- a/docs/shared/reference/environment-variables.md +++ b/docs/shared/reference/environment-variables.md @@ -1,12 +1,12 @@ # Environment Variables -| Property | Type | Description | -| ------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| NX_VERBOSE_LOGGING | boolean | If set to `true`, will print debug information useful for troubleshooting | -| NX_PERF_LOGGING | boolean | If set to `true`, will print debug information useful for for profiling executors and Nx itself | -| NX_TASKS_RUNNER_DYNAMIC_OUTPUT | boolean | If set to `false`, will use non-dynamic terminal output strategy (what you see in CI), even when you terminal can support the dynamic version | -| NX_CACHE_DIRECTORY | string | The cache is stored in `node_modules/.cache/nx` by default. Set this variable to use a different directory. | -| NX_SKIP_NX_CACHE | boolean | Rerun the tasks even when the results are available in the cache | -| NX_CACHE_PROJECT_GRAPH | boolean | If set to `false`, disables the project graph cache. Most useful when developing a plugin that modifies the project graph. | -| NX_DAEMON | boolean | If set to `false`, disables the Nx daemon process. Disable the daemon to print `console.log` statements in plugin code you are developing. | -| NX_PROFILE | string | Prepend `NX_PROFILE=profile.json` before running targets with Nx to generate a file that be [loaded in Chrome dev tools](/recipe/performance-profiling) to visualize the performance of Nx across multiple processes. | +| Property | Type | Description | +| ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| NX_VERBOSE_LOGGING | boolean | If set to `true`, will print debug information useful for troubleshooting | +| NX_PERF_LOGGING | boolean | If set to `true`, will print debug information useful for for profiling executors and Nx itself | +| NX_TASKS_RUNNER_DYNAMIC_OUTPUT | boolean | If set to `false`, will use non-dynamic terminal output strategy (what you see in CI), even when you terminal can support the dynamic version | +| NX_CACHE_DIRECTORY | string | The cache is stored in `node_modules/.cache/nx` by default. Set this variable to use a different directory. | +| NX_SKIP_NX_CACHE | boolean | Rerun the tasks even when the results are available in the cache | +| NX_CACHE_PROJECT_GRAPH | boolean | If set to `false`, disables the project graph cache. Most useful when developing a plugin that modifies the project graph. | +| NX_DAEMON | boolean | If set to `false`, disables the Nx daemon process. Disable the daemon to print `console.log` statements in plugin code you are developing. | +| NX_PROFILE | string | Prepend `NX_PROFILE=profile.json` before running targets with Nx to generate a file that be [loaded in Chrome dev tools](/recipes/other/performance-profiling) to visualize the performance of Nx across multiple processes. | diff --git a/docs/shared/workspace-plugin.md b/docs/shared/workspace-plugin.md index 663cec0430..316e3e8505 100644 --- a/docs/shared/workspace-plugin.md +++ b/docs/shared/workspace-plugin.md @@ -4,7 +4,7 @@ The workspace plugin contains executors and generators that are useful for any N Codifying your organization's best practices into local generators is a great way to ensure that the best practices are easy to follow and implement. Running `nx g @nrwl/nx-plugin:plugin feature` will create a local plugin with a generator which is written the same way generators are written for Nx plugins. -> See more about [local generators](/recipe/local-generators) +> See more about [local generators](/recipes/generators/local-generators) ## Reorganizing Projects diff --git a/graph/client/src/assets/graphs/nx.json b/graph/client/src/assets/graphs/nx.json index 307ccc8766..612f464231 100644 --- a/graph/client/src/assets/graphs/nx.json +++ b/graph/client/src/assets/graphs/nx.json @@ -18139,15 +18139,15 @@ "hash": "999f8854b2cf195f8a0a7b3026320a0a125174be" }, { - "file": "docs/shared/recipes/advanced-update.md", + "file": "docs/shared/recipes/other/advanced-update.md", "hash": "6ad45fbb024118d6b3e6dbba0f9a8b910141331c" }, { - "file": "docs/shared/recipes/ban-dependencies-with-tags.md", + "file": "docs/shared/recipes/other/ban-dependencies-with-tags.md", "hash": "c43e666d41fef0331bdc072f293a76d22eb9a607" }, { - "file": "docs/shared/recipes/ban-external-imports.md", + "file": "docs/shared/recipes/other/ban-external-imports.md", "hash": "825cf907bf9aae69bbc97cc979b4b3edb5f71d9f" }, { @@ -18187,11 +18187,11 @@ "hash": "c2113b3d68dfcb234ee225afe382b83847f21440" }, { - "file": "docs/shared/recipes/tag-multiple-dimensions.md", + "file": "docs/shared/recipes/other/tag-multiple-dimensions.md", "hash": "70f7256551db65ad586d1c49f0e554acad993d19" }, { - "file": "docs/shared/recipes/tags-allow-list.md", + "file": "docs/shared/recipes/other/tags-allow-list.md", "hash": "39262d8ac3bdc913d62f327f8c68f494c5d2e146" }, { diff --git a/nx-dev/data-access-documents/src/lib/documents.api.ts b/nx-dev/data-access-documents/src/lib/documents.api.ts index 788b75a0fe..6fe750ec7f 100644 --- a/nx-dev/data-access-documents/src/lib/documents.api.ts +++ b/nx-dev/data-access-documents/src/lib/documents.api.ts @@ -249,7 +249,7 @@ export class DocumentsApi { if ( curr.tags && tags.some((tag) => curr.tags.includes(tag)) && - acc.includes('recipe') + acc.includes('recipes') ) { curr.path = [...acc, curr.id].join('/'); relatedRecipes.push(curr); diff --git a/nx-dev/data-access-menu/src/lib/menu.api.ts b/nx-dev/data-access-menu/src/lib/menu.api.ts index 66c4b1ca2f..a45b20d45a 100644 --- a/nx-dev/data-access-menu/src/lib/menu.api.ts +++ b/nx-dev/data-access-menu/src/lib/menu.api.ts @@ -19,13 +19,12 @@ export class MenuApi { const items = createMenuItems(this.documents); if (!items) throw new Error(`Cannot find any documents`); + const isAncestor: boolean = Boolean( + items.length === 1 && items[0].itemList && items[0].itemList.length > 1 + ); menu = { sections: this.extractorFunctions.map((categorizer) => - categorizer( - items.length === 1 && items[0].id === 'nx-cloud' - ? (items[0].itemList as MenuItem[]) - : items - ) + categorizer(isAncestor ? (items[0].itemList as MenuItem[]) : items) ), }; diff --git a/nx-dev/data-access-menu/src/lib/menu.utils.ts b/nx-dev/data-access-menu/src/lib/menu.utils.ts index 278438d9e4..a10688d1ce 100644 --- a/nx-dev/data-access-menu/src/lib/menu.utils.ts +++ b/nx-dev/data-access-menu/src/lib/menu.utils.ts @@ -45,6 +45,22 @@ export function getBasicSection(items: MenuItem[]): MenuSection { }; } +export function getBasicRecipesSection(items: MenuItem[]): MenuSection { + return { + id: 'basic', + name: 'Basic', + hideSectionHeader: true, + itemList: items + // .filter((m) => m.id === 'getting-started') + .map((m) => { + return { + ...m, + disableCollapsible: true, + }; + }), + }; +} + export function getDeepDiveSection(items: MenuItem[]): MenuSection { return { id: 'deep-dive', diff --git a/nx-dev/nx-dev/lib/api.ts b/nx-dev/nx-dev/lib/api.ts index 4f68e16333..5f2e407f05 100644 --- a/nx-dev/nx-dev/lib/api.ts +++ b/nx-dev/nx-dev/lib/api.ts @@ -6,6 +6,7 @@ import { getBasicNxCloudSection, getBasicSection, getDeepDiveNxCloudSection, + getBasicRecipesSection, } from '../../data-access-menu/src/lib/menu.utils'; // Imports JSON directly, so they can be bundled into the app and functions. @@ -17,7 +18,6 @@ export const packagesApi = new PackagesApi({ publicPackagesRoot: 'nx-dev/nx-dev/public/documentation', packagesIndex: packages, }); - export const nxDocumentsApi = new DocumentsApi({ publicDocsRoot: 'nx-dev/nx-dev/public/documentation', documentSources: [ @@ -26,7 +26,13 @@ export const nxDocumentsApi = new DocumentsApi({ ].filter((x) => !!x) as DocumentMetadata[], addAncestor: null, }); - +export const nxRecipesApi = new DocumentsApi({ + publicDocsRoot: 'nx-dev/nx-dev/public/documentation', + documentSources: [documents.find((x) => x.id === 'nx-recipes')].filter( + (x) => !!x + ) as DocumentMetadata[], + addAncestor: { id: 'recipes', name: 'Recipes' }, +}); export const nxCloudDocumentsApi = new DocumentsApi({ publicDocsRoot: 'nx-dev/nx-dev/public/documentation', documentSources: [ @@ -40,7 +46,11 @@ export const nxMenuApi = new MenuApi( packagesApi.getPackageDocuments().itemList as DocumentMetadata[], [getBasicSection] ); - +export const nxRecipesMenuApi = new MenuApi( + nxRecipesApi.getDocuments(), + [], + [getBasicRecipesSection] +); export const nxCloudMenuApi = new MenuApi( nxCloudDocumentsApi.getDocuments(), [], diff --git a/nx-dev/nx-dev/pages/[...segments].tsx b/nx-dev/nx-dev/pages/[...segments].tsx index dc136f13db..113407f32e 100644 --- a/nx-dev/nx-dev/pages/[...segments].tsx +++ b/nx-dev/nx-dev/pages/[...segments].tsx @@ -16,6 +16,8 @@ import { nxCloudMenuApi, nxDocumentsApi, nxMenuApi, + nxRecipesApi, + nxRecipesMenuApi, packagesApi, } from '../lib/api'; import { useNavToggle } from '../lib/navigation-toggle.effect'; @@ -136,6 +138,10 @@ export const getStaticProps: GetStaticProps = async ({ documentsApi = nxCloudDocumentsApi; menuApi = nxCloudMenuApi; } + if (params.segments[0] === 'recipes') { + documentsApi = nxRecipesApi; + menuApi = nxRecipesMenuApi; + } const menu = menuApi.getMenu(); @@ -217,6 +223,7 @@ export const getStaticPaths: GetStaticPaths = () => { paths: [ ...packagesApi.getStaticPackagePaths(), ...nxDocumentsApi.getStaticDocumentPaths(), + ...nxRecipesApi.getStaticDocumentPaths(), ...nxCloudDocumentsApi.getStaticDocumentPaths(), ], fallback: 'blocking', diff --git a/nx-dev/nx-dev/redirect-rules.config.js b/nx-dev/nx-dev/redirect-rules.config.js index 7bd4234c5b..be38e2d474 100644 --- a/nx-dev/nx-dev/redirect-rules.config.js +++ b/nx-dev/nx-dev/redirect-rules.config.js @@ -181,30 +181,35 @@ const diataxis = { '/using-nx/caching': '/concepts/how-caching-works', '/using-nx/dte': '/core-features/distribute-task-execution', '/using-nx/affected': '/concepts/affected', - '/using-nx/ci-overview': '/recipes/ci-setup', + '/using-nx/ci-overview': '/recipes/ci/ci-setup', '/using-nx/updating-nx': '/core-features/automate-updating-dependencies', '/using-nx/nx-nodejs-typescript-version-matrix': '/workspace/nx-nodejs-typescript-version-matrix', '/extending-nx/nx-devkit': '/plugin-features/create-your-own-plugin', '/extending-nx/project-inference-plugins': - '/recipe/project-inference-plugins', - '/extending-nx/project-graph-plugins': '/recipe/project-graph-plugins', - '/migration/lerna-and-nx': '/recipe/lerna-and-nx', - '/migration/adding-to-monorepo': '/recipe/adding-to-monorepo', - '/migration/migration-cra': '/recipe/migration-cra', - '/migration/migration-angular': '/recipe/migration-angular', - '/migration/migration-angularjs': '/recipe/migration-angularjs', - '/migration/preserving-git-histories': '/recipe/preserving-git-histories', - '/migration/manual': '/recipe/manual', + '/recipes/advanced-plugins/project-inference-plugins', + '/extending-nx/project-graph-plugins': + '/recipes/advanced-plugins/project-graph-plugins', + '/migration/lerna-and-nx': '/recipes/adopting-nx/lerna-and-nx', + '/migration/adding-to-monorepo': '/recipes/adopting-nx/adding-to-monorepo', + '/migration/migration-cra': '/recipes/adopting-nx/migration-cra', + '/migration/migration-angular': '/recipes/adopting-nx/migration-angular', + '/migration/migration-angularjs': '/recipes/adopting-nx/migration-angularjs', + '/migration/preserving-git-histories': + '/recipes/adopting-nx/preserving-git-histories', + '/migration/manual': '/recipes/adopting-nx/manual', '/executors/using-builders': '/plugin-features/use-task-executors', - '/executors/run-commands-builder': '/recipe/run-commands-executor', - '/executors/creating-custom-builders': '/recipe/creating-custom-executors', + '/executors/run-commands-builder': '/recipes/executors/run-commands-executor', + '/executors/creating-custom-builders': + '/recipes/executors/creating-custom-executors', '/generators/using-generators': '/plugin-features/use-code-generators', - '/generators/workspace-generators': '/recipe/workspace-generators', - '/generators/composing-generators': '/recipe/composing-generators', - '/generators/generator-options': '/recipe/generator-options', - '/generators/creating-files': '/recipe/creating-files', - '/generators/modifying-files': '/recipe/modifying-files', + '/generators/workspace-generators': + '/recipes/generators/workspace-generators', + '/generators/composing-generators': + '/recipes/generators/composing-generators', + '/generators/generator-options': '/recipes/generators/generator-options', + '/generators/creating-files': '/recipes/generators/creating-files', + '/generators/modifying-files': '/recipes/generators/modifying-files', '/structure/applications-and-libraries': 'more-concepts/applications-and-libraries', '/structure/creating-libraries': '/more-concepts/creating-libraries', @@ -214,50 +219,53 @@ const diataxis = { '/more-concepts/buildable-and-publishable-libraries', '/structure/monorepo-tags': '/core-features/enforce-project-boundaries', '/structure/dependency-graph': '/core-features/explore-graph', - '/structure/project-graph-plugins': '/recipe/project-graph-plugins', - '/ci/monorepo-ci-azure': '/recipe/monorepo-ci-azure', - '/ci/monorepo-ci-circle-ci': '/recipe/monorepo-ci-circle-ci', - '/ci/monorepo-ci-github-actions': '/recipe/monorepo-ci-github-actions', - '/ci/monorepo-ci-jenkins': '/recipe/monorepo-ci-jenkins', - '/ci/monorepo-ci-gitlab': '/recipe/monorepo-ci-gitlab', + '/structure/project-graph-plugins': + '/recipes/advanced-plugins/project-graph-plugins', + '/ci/monorepo-ci-azure': '/recipes/ci/monorepo-ci-azure', + '/ci/monorepo-ci-circle-ci': '/recipes/ci/monorepo-ci-circle-ci', + '/ci/monorepo-ci-github-actions': '/recipes/ci/monorepo-ci-github-actions', + '/ci/monorepo-ci-jenkins': '/recipes/ci/monorepo-ci-jenkins', + '/ci/monorepo-ci-gitlab': '/recipes/ci/monorepo-ci-gitlab', '/ci/monorepo-ci-bitbucket-pipelines': - '/recipe/monorepo-ci-bitbucket-pipelines', + '/recipes/ci/monorepo-ci-bitbucket-pipelines', '/ci/distributed-builds': '/concepts/dte', // 👀 '/ci/incremental-builds': '/more-concepts/incremental-builds', '/ci/setup-incremental-builds-angular': - '/recipe/setup-incremental-builds-angular', + '/recipes/other/setup-incremental-builds-angular', '/guides/turbo-and-nx': '/more-concepts/turbo-and-nx', '/guides/why-monorepos': '/more-concepts/why-monorepos', - '/guides/adding-assets-react': '/recipe/adding-assets-react', + '/guides/adding-assets-react': '/recipes/other/adding-assets-react', '/guides/environment-variables': '/reference/environment-variables', '/guides/monorepo-nx-enterprise': '/more-concepts/monorepo-nx-enterprise', - '/guides/performance-profiling': '/recipe/performance-profiling', - '/guides/eslint': '/recipe/eslint', - '/guides/customize-webpack': '/recipe/customize-webpack', + '/guides/performance-profiling': '/recipes/other/performance-profiling', + '/guides/eslint': '/recipes/other/eslint', + '/guides/customize-webpack': '/recipes/other/customize-webpack', '/guides/nx-daemon': '/more-concepts/nx-daemon', - '/guides/js-and-ts': '/recipe/js-and-ts', - '/guides/browser-support': '/recipe/browser-support', - '/guides/react-native': '/recipe/react-native', - '/guides/deploy-nextjs-to-vercel': '/recipe/deploy-nextjs-to-vercel', - '/guides/webpack-5': '/recipe/webpack-5', - '/guides/using-tailwind-css-in-react': '/recipe/using-tailwind-css-in-react', - '/guides/react-18': '/recipe/react-18', + '/guides/js-and-ts': '/recipes/other/js-and-ts', + '/guides/browser-support': '/recipes/other/browser-support', + '/guides/react-native': '/recipes/other/react-native', + '/guides/deploy-nextjs-to-vercel': '/recipes/other/deploy-nextjs-to-vercel', + '/guides/webpack-5': '/recipes/other/webpack-5', + '/guides/using-tailwind-css-in-react': + '/recipes/other/using-tailwind-css-in-react', + '/guides/react-18': '/recipes/other/react-18', '/guides/using-tailwind-css-with-angular-projects': - '/recipe/using-tailwind-css-with-angular-projects', - '/guides/misc-ngrx': '/recipe/misc-ngrx', - '/guides/misc-data-persistence': '/recipe/misc-data-persistence', + '/recipes/other/using-tailwind-css-with-angular-projects', + '/guides/misc-ngrx': '/recipes/other/misc-ngrx', + '/guides/misc-data-persistence': '/recipes/other/misc-data-persistence', '/guides/nx-devkit-angular-devkit': '/more-concepts/nx-devkit-angular-devkit', - '/module-federation/faster-builds': '/recipe/faster-builds', + '/module-federation/faster-builds': + '/recipes/module-federation/faster-builds', '/module-federation/micro-frontend-architecture': '/more-concepts/micro-frontend-architecture', '/module-federation/dynamic-module-federation-with-angular': - '/recipe/dynamic-module-federation-with-angular', - '/examples/nx-examples': '/recipe/nx-examples', - '/examples/react-nx': '/recipe/react-nx', - '/examples/apollo-react': '/recipe/apollo-react', - '/examples/caching': '/recipe/caching', - '/examples/dte': '/recipe/dte', - '/recipe/workspace-generators': '/recipe/local-generators', + '/recipes/module-federation/dynamic-module-federation-with-angular', + '/examples/nx-examples': '/recipes/other/nx-examples', + '/examples/react-nx': '/recipes/other/react-nx', + '/examples/apollo-react': '/recipes/other/apollo-react', + '/examples/caching': '/recipes/other/caching', + '/examples/dte': '/recipes/other/dte', + '/recipe/workspace-generators': '/recipes/generators/local-generators', }; /** diff --git a/nx-dev/ui-common/src/lib/documentation-header.tsx b/nx-dev/ui-common/src/lib/documentation-header.tsx index 82a497636b..130a676f08 100644 --- a/nx-dev/ui-common/src/lib/documentation-header.tsx +++ b/nx-dev/ui-common/src/lib/documentation-header.tsx @@ -63,7 +63,7 @@ export function DocumentationHeader({ }, { name: 'Recipes', - href: '/recipes/all', + href: '/recipes', current: isRecipes, }, ]; diff --git a/nx-dev/ui-common/src/lib/header.tsx b/nx-dev/ui-common/src/lib/header.tsx index b2fd14ae8d..0abf4bf454 100644 --- a/nx-dev/ui-common/src/lib/header.tsx +++ b/nx-dev/ui-common/src/lib/header.tsx @@ -35,7 +35,7 @@ export function Header(): JSX.Element { { name: 'Recipes', description: 'Follow instructions to do common specific tasks.', - href: '/recipes/all', + href: '/recipes', }, { name: 'VSCode integration',