diff --git a/docs/map.json b/docs/map.json index 7d3c52fcce..4a9117c7c3 100644 --- a/docs/map.json +++ b/docs/map.json @@ -27,11 +27,6 @@ "id": "nx-and-typescript", "file": "shared/guides/nx-and-ts" }, - { - "name": "Nx Plugins and Devkit", - "id": "nx-devkit", - "file": "shared/devkit-and-nx-plugins" - }, { "name": "Nx and React", "id": "nx-and-react", @@ -94,6 +89,11 @@ "id": "affected", "file": "shared/using-nx/affected" }, + { + "name": "Nx Plugins and Devkit", + "id": "nx-devkit", + "file": "shared/devkit-and-nx-plugins" + }, { "name": "CI Setup", "id": "ci-overview", diff --git a/docs/shared/configuration/packagejson.md b/docs/shared/configuration/packagejson.md index 7b8b8b03d8..dc9bcb2cac 100644 --- a/docs/shared/configuration/packagejson.md +++ b/docs/shared/configuration/packagejson.md @@ -111,6 +111,17 @@ statically, so you can set them manually like this: } ``` +You can also remove a dependency as follows: + +```jsonc +{ + "name": "mylib", + "nx": { + "implicitDependencies": ["!anotherlib"] # regardless of what Nx thinks, "mylib" doesn't depend on "anotherlib" + } +} +``` + ### Ignoring a project Nx will add every project with a `package.json` file in it to its project graph. If you want to ignore a particular @@ -127,7 +138,7 @@ project, add the following to its `package.json`: ### workspace json -The `workspace.json` file in the root directory is optional. It's used if you want to list the projects in your workspace explicitly instead of Nx scanning the file tree for all `project.json` and `package.json` files. +The `workspace.json` file in the root directory is optional. It's used if you want to list the projects in your workspace explicitly instead of Nx scanning the file tree for all `project.json` and `package.json` files that match the globs specified in the `workspaces` property of the root `package.json`. ```json { @@ -143,7 +154,7 @@ The `workspace.json` file in the root directory is optional. It's used if you wa ## CLI Configuration -The `nx.json` file contains extra configuration options mostly related to the project graph. +The `nx.json` file configures the Nx CLI and project defaults. The following is an expanded version showing all options. Your `nx.json` will likely be much shorter. diff --git a/docs/shared/configuration/projectjson.md b/docs/shared/configuration/projectjson.md index 9053f4022a..75b4af066c 100644 --- a/docs/shared/configuration/projectjson.md +++ b/docs/shared/configuration/projectjson.md @@ -12,8 +12,7 @@ files to get each project's configuration. This guide covers the `project.json` ## Project Configuration The `project.json` file contains configuration specific to its project. This file is often created when you use Nx -Plugins. Everything you can configure in `package.json` you can also configure in `project.json`. In addition, you can -configure custom executors, which are used instead of npm scripts. Custom executors are typed, toolable and provide a +Plugins. It configures custom executors, which are used instead of npm scripts. Custom executors are typed, toolable and provide a lot more flexibility for running long-live processes. They are also more composable. If you satisfied with npm scripts though, you will never see a `project.json` file in your workspace. But we encourage @@ -209,6 +208,18 @@ statically, so you can set them manually like this: } ``` +You can also remove a dependency as follows: + +```jsonc +{ + "root": "libs/mylib/", + "sourceRoot": "libs/mylib/src", + "projectType": "library", + "targets": {}, + "implicitDependencies": ["!anotherlib"] # regardless of what Nx thinks, "mylib" doesn't depend on "anotherlib" +} +``` + ### workspace json The `workspace.json` file in the root directory is optional. It's used if you want to list the projects in your workspace explicitly instead of Nx scanning the file tree for all `project.json` and `package.json` files. @@ -234,7 +245,7 @@ run `nx format`. ## CLI Configuration -The `nx.json` file contains extra configuration options mostly related to the project graph. +The `nx.json` file configures the Nx CLI and project defaults. The following is an expanded version showing all options. Your `nx.json` will likely be much shorter. diff --git a/docs/shared/getting-started/intro.md b/docs/shared/getting-started/intro.md index d7eafc0900..0082597b43 100644 --- a/docs/shared/getting-started/intro.md +++ b/docs/shared/getting-started/intro.md @@ -16,41 +16,12 @@ the boilerplate. However, the vast majority of the features will work the same w ## Getting Started -These guides will help you get started: +- [Using Nx without plugins](/getting-started/nx-core) will help you understand the core of Nx. +- [Adding Nx to an existing monorepo](/migration/adding-to-monorepo) will show how to add Nx to an existing monorepo. +- [Mental model](/using-nx/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 guides: -- [Installing Nx CLI & creating a new Nx Workspace](/getting-started/nx-setup) -- [Adding Nx to an existing monorepo](/migration/adding-to-monorepo) -- [Using Nx without plugins](/getting-started/nx-core) - [Nx and TypeScript](/getting-started/nx-and-typescript) - [Nx and React](/getting-started/nx-and-react) - [Nx and Angular](/getting-started/nx-and-angular) -- [CI Overview](/using-nx/ci-overview) - -## Features - -**Best-in-Class Support for Monorepos** - -- [Smart rebuilds of affected projects](/using-nx/affected) -- [Computation caching](/using-nx/caching) -- [Distributed task execution](/using-nx/dte) -- [Code sharing and ownership management](/structure/monorepo-tags) - -**Integrated Development Experience** - -- [High-quality editor plugins](/using-nx/console) & [GitHub apps](https://github.com/apps/nx-cloud) -- [Powerful code generators](/generators/using-schematics) -- [Workspace visualizations](/structure/dependency-graph) - -**Supports Your Ecosystem** - -- [Rich plugin ecosystem](/getting-started/nx-devkit) from Nrwl and the [community](/community) -- Consistent dev experience for any framework -- [Automatic upgrade to the latest versions of all frameworks and tools](/using-nx/updating-nx) - -## Learn While Doing - -- [Using Nx without plugins](/getting-started/nx-core) -- [Nx and TypeScript](/getting-started/nx-and-typescript) -- [React: Interactive Nx Tutorial (with videos)](/react-tutorial/01-create-application) -- [Node: Interactive Nx Tutorial (with videos)](/node-tutorial/01-create-application) -- [Angular: Interactive Nx Tutorial (with videos)](/angular-tutorial/01-create-application) diff --git a/docs/shared/getting-started/nx-and-angular.md b/docs/shared/getting-started/nx-and-angular.md index 71c7934152..43ae530c23 100644 --- a/docs/shared/getting-started/nx-and-angular.md +++ b/docs/shared/getting-started/nx-and-angular.md @@ -8,12 +8,10 @@ If you're only interested in improving the performance of your monorepo by using Check out the following guides to get started: -- [Installing Nx CLI & creating a new Nx Workspace](/getting-started/nx-setup) +- [Using Nx without plugins](/getting-started/nx-core) - [Adding Nx to an existing monorepo](/migration/adding-to-monorepo) - [Adding Nx to an Angular CLI project](/migration/migration-angular) - [Migrating from AngularJS](/migration/migration-angularjs) -- [Using Nx without plugins](/getting-started/nx-core) -- [CI Overview](/using-nx/ci-overview) It is also a good idea to read the [mental model guide](/using-nx/mental-model) to understand how Nx works. @@ -23,8 +21,6 @@ Nx plugins helps you develop [Angular](/angular/overview) applications with full modern tools and libraries like [Jest](/jest/overview), [Cypress](/cypress/overview), [ESLint](/linter/eslint), Storybook, [NgRx](/angular/guides/misc-ngrx) and more. -### 10-min Video Overview - Check out the following to get started: diff --git a/docs/shared/getting-started/nx-and-react.md b/docs/shared/getting-started/nx-and-react.md index ef1064ad00..202babf572 100644 --- a/docs/shared/getting-started/nx-and-react.md +++ b/docs/shared/getting-started/nx-and-react.md @@ -8,11 +8,9 @@ If you're only interested in improving the performance of your monorepo by using Check out the following guides to get started: -- [Installing Nx CLI & creating a new Nx Workspace](/getting-started/nx-setup) +- [Using Nx without plugins](/getting-started/nx-core) - [Adding Nx to an existing monorepo](/migration/adding-to-monorepo) - [Migrating from CRA](/migration/migration-cra) -- [Using Nx without plugins](/getting-started/nx-core) -- [CI Overview](/using-nx/ci-overview) It is also a good idea to read the [mental model guide](/using-nx/mental-model) to understand how Nx works. @@ -21,9 +19,7 @@ It is also a good idea to read the [mental model guide](/using-nx/mental-model) Nx plugins help you develop [React](/react/overview) applications with fully integrated support for modern tools and libraries like [Jest](/jest/overview), [Cypress](/cypress/overview), Storybook, [ESLint](/linter/eslint), and more. Nx also supports React -frameworks like [Gatsby](/gatsby/overview), [Next.js](/guides/nextjs), Remix, and has great support for React Native. - -### 10-min Video Overview +frameworks like [Gatsby](/gatsby/overview), [Next.js](/guides/nextjs), Remix, and has great support for [React Native](/react-native/overview). diff --git a/docs/shared/guides/nx-and-ts.md b/docs/shared/guides/nx-and-ts.md index 7370247af5..9620b32981 100644 --- a/docs/shared/guides/nx-and-ts.md +++ b/docs/shared/guides/nx-and-ts.md @@ -10,7 +10,7 @@ The `@nrwl/js` package ships with corresponding generators and executors that be `@nrwl/js` is particularly useful if you want to -- Create framework agnostic TypeScript libraries within an existing Nx workspace (say to use in your React, Node or Angular app) +- Create framework-agnostic TypeScript libraries within an existing Nx workspace (say to use in your React, Node or Angular app) - Publish TypeScript packages to NPM To get started with TypeScript packages in Nx, either add the `@nrwl/js` package to an existing Nx workspace or generate a new Nx workspace using the `--preset=ts` preset. diff --git a/docs/shared/nx-core.md b/docs/shared/nx-core.md index d4bcc64444..818cefc2f4 100644 --- a/docs/shared/nx-core.md +++ b/docs/shared/nx-core.md @@ -10,7 +10,7 @@ of Nx are completely generic and can be used with any technology or tool. ### Creating a New Workspace -Running `yarn create nx-workspace --preset=core` creates an empty workspace. +Running `npx create-nx-workspace@latest --preset=core` creates an empty workspace. This is what is generated: @@ -58,8 +58,6 @@ package.json } ``` -Finally, `workspace.json` lists the workspace projects, and since we have none, it is empty. - ### Creating an NPM Package Running `nx g npm-package simple` results in: @@ -88,17 +86,12 @@ The generated `simple/package.json`: ``` With this you can invoke any script defined in `packages/simple/package.json` via Nx. For instance, you can invoke the `test` -script by running `yarn nx test simple`. And if you invoke this command a second time, the results are retrieved from +script by running `nx test simple`. And if you invoke this command a second time, the results are retrieved from cache. In this example, we used a generator to create the package, but you could have also created it by hand or copied it from another project. -The change in `workspace.json` is the only thing required to make Nx aware of the `simple` package. As long as you -include the project in `workspace.json`, Nx will include that project source in its graph computation and source -code analysis. It will, for instance, analyze the project's source code, and it will know when it can reuse the -computation from the cache and when it has to recompute it from scratch. - ### Creating Second NPM Package and Enabling Yarn Workspaces Running `nx g npm-package complex` results in: @@ -117,7 +110,7 @@ tsconfig.base.json package.json ``` -Now let's modify `packages/complex/index.js` to include `require('@myorg/simple')`. If you run `yarn nx test complex`, +Now let's modify `packages/complex/index.js` to include `require('@myorg/simple')`. If you run `nx test complex`, you will see an error saying that `@myorg/simple` cannot be resolved. This is expected. Nx analyzes your source to enable computation caching, it knows what projects are affected by your PR, @@ -139,17 +132,9 @@ To make it work, add a dependency from `complex` to `simple` in `packages/comple } ``` -Then add the following to the root `package.json` (which enables Yarn Workspaces). - -```json -{ - "workspaces": ["packages/*"] -} -``` - Finally, run `yarn`. -`yarn nx test complex` works now. +`nx test complex` works now. ## Using Yarn/PNPM/Lerna @@ -162,7 +147,7 @@ elegant way. [Read about the relationship between Nx and Yarn/Lerna/PNPM](/guide ### Nx Understands How Your Workspace Is Structured -If you run `yarn nx dep-graph` you will see that `complex` has a dependency on `simple`. Any change to `simple` will +If you run `nx dep-graph` you will see that `complex` has a dependency on `simple`. Any change to `simple` will invalidate the computation cache for `complex`, but changes to `complex` won't invalidate the cache for `simple`. In contrast to more basic monorepo tools, Nx doesn't just analyze `package.json` files. It does much more. Nx also knows @@ -170,19 +155,19 @@ that adding a `require()` creates a dependency and that some dependencies cannot ### Nx Orchestrates Tasks -Running `yarn nx run-many --target=test --all` will test all projects in parallel. +Running `nx run-many --target=test --all` will test all projects in parallel. -Running `yarn nx run-many --target=build --projects=app1,app2` will build `proj1` and `proj2` and their -dependencies in parallel. Note that if `app1` depends on the output of its dependency (e.g., `shared-components`), Nx -will build `shared-components` first and only then will build the app. +Often, tests for different projects can run independently, but builds can't. If you, say, have two applications `app1` and `app2` depending on the `shared-components` library, it's possible that the library has to be built first before the two applications can be built. And that's what `nx run-many --target=build --projects=app1,app2` will do. + +With Nx, you never have to worry about preparing your workspace before running a particular command. Nx will do it for you. ### Nx Knows What Is Affected -Running `yarn nx affected --target=test` will test all the projects affected by the current PR. +Running `nx affected --target=test` will test all the projects affected by the current PR. ### Nx Caches and Distributes Tasks -Running `yarn nx build app1` will cache the file artifacts and the terminal output, so if you run it again the command +Running `nx run-many --target=build --all` will cache the file artifacts and the terminal output, so if you run it again the command will execute instantly because the results will be retrieved from cache. If you use `Nx Cloud` the cache will be shared between you, your teammates, and the CI agents. Nx can also distribute tasks across multiple machines while preserving the developer experience of running it on a single machine. diff --git a/docs/shared/using-nx/dte.md b/docs/shared/using-nx/dte.md index 6f0bc6d699..6aa9d232a0 100644 --- a/docs/shared/using-nx/dte.md +++ b/docs/shared/using-nx/dte.md @@ -27,4 +27,8 @@ it locally. ## Example -- [This is an example repo](https://github.com/vsavkin/interstellar) showing how easy it is to set up distributed task execution, showing the performance gains, and comparing to sharding/binnig. +[This is an example repo](https://github.com/vsavkin/interstellar) showing how easy it is to set up distributed task execution, showing the performance gains, and comparing to sharding/binnig. + +These are the savings you get by enabling Distributed Task Execution in your CI config: + +![DTE](/shared/using-nx/dte.png) diff --git a/docs/shared/using-nx/dte.png b/docs/shared/using-nx/dte.png new file mode 100644 index 0000000000..d5e9cd4eb6 Binary files /dev/null and b/docs/shared/using-nx/dte.png differ diff --git a/nx-dev/nx-dev/public/documentation/map.json b/nx-dev/nx-dev/public/documentation/map.json index 7d3c52fcce..4a9117c7c3 100644 --- a/nx-dev/nx-dev/public/documentation/map.json +++ b/nx-dev/nx-dev/public/documentation/map.json @@ -27,11 +27,6 @@ "id": "nx-and-typescript", "file": "shared/guides/nx-and-ts" }, - { - "name": "Nx Plugins and Devkit", - "id": "nx-devkit", - "file": "shared/devkit-and-nx-plugins" - }, { "name": "Nx and React", "id": "nx-and-react", @@ -94,6 +89,11 @@ "id": "affected", "file": "shared/using-nx/affected" }, + { + "name": "Nx Plugins and Devkit", + "id": "nx-devkit", + "file": "shared/devkit-and-nx-plugins" + }, { "name": "CI Setup", "id": "ci-overview", diff --git a/nx-dev/nx-dev/public/documentation/shared/configuration/packagejson.md b/nx-dev/nx-dev/public/documentation/shared/configuration/packagejson.md index 7b8b8b03d8..dc9bcb2cac 100644 --- a/nx-dev/nx-dev/public/documentation/shared/configuration/packagejson.md +++ b/nx-dev/nx-dev/public/documentation/shared/configuration/packagejson.md @@ -111,6 +111,17 @@ statically, so you can set them manually like this: } ``` +You can also remove a dependency as follows: + +```jsonc +{ + "name": "mylib", + "nx": { + "implicitDependencies": ["!anotherlib"] # regardless of what Nx thinks, "mylib" doesn't depend on "anotherlib" + } +} +``` + ### Ignoring a project Nx will add every project with a `package.json` file in it to its project graph. If you want to ignore a particular @@ -127,7 +138,7 @@ project, add the following to its `package.json`: ### workspace json -The `workspace.json` file in the root directory is optional. It's used if you want to list the projects in your workspace explicitly instead of Nx scanning the file tree for all `project.json` and `package.json` files. +The `workspace.json` file in the root directory is optional. It's used if you want to list the projects in your workspace explicitly instead of Nx scanning the file tree for all `project.json` and `package.json` files that match the globs specified in the `workspaces` property of the root `package.json`. ```json { @@ -143,7 +154,7 @@ The `workspace.json` file in the root directory is optional. It's used if you wa ## CLI Configuration -The `nx.json` file contains extra configuration options mostly related to the project graph. +The `nx.json` file configures the Nx CLI and project defaults. The following is an expanded version showing all options. Your `nx.json` will likely be much shorter. diff --git a/nx-dev/nx-dev/public/documentation/shared/configuration/projectjson.md b/nx-dev/nx-dev/public/documentation/shared/configuration/projectjson.md index 9053f4022a..75b4af066c 100644 --- a/nx-dev/nx-dev/public/documentation/shared/configuration/projectjson.md +++ b/nx-dev/nx-dev/public/documentation/shared/configuration/projectjson.md @@ -12,8 +12,7 @@ files to get each project's configuration. This guide covers the `project.json` ## Project Configuration The `project.json` file contains configuration specific to its project. This file is often created when you use Nx -Plugins. Everything you can configure in `package.json` you can also configure in `project.json`. In addition, you can -configure custom executors, which are used instead of npm scripts. Custom executors are typed, toolable and provide a +Plugins. It configures custom executors, which are used instead of npm scripts. Custom executors are typed, toolable and provide a lot more flexibility for running long-live processes. They are also more composable. If you satisfied with npm scripts though, you will never see a `project.json` file in your workspace. But we encourage @@ -209,6 +208,18 @@ statically, so you can set them manually like this: } ``` +You can also remove a dependency as follows: + +```jsonc +{ + "root": "libs/mylib/", + "sourceRoot": "libs/mylib/src", + "projectType": "library", + "targets": {}, + "implicitDependencies": ["!anotherlib"] # regardless of what Nx thinks, "mylib" doesn't depend on "anotherlib" +} +``` + ### workspace json The `workspace.json` file in the root directory is optional. It's used if you want to list the projects in your workspace explicitly instead of Nx scanning the file tree for all `project.json` and `package.json` files. @@ -234,7 +245,7 @@ run `nx format`. ## CLI Configuration -The `nx.json` file contains extra configuration options mostly related to the project graph. +The `nx.json` file configures the Nx CLI and project defaults. The following is an expanded version showing all options. Your `nx.json` will likely be much shorter. diff --git a/nx-dev/nx-dev/public/documentation/shared/getting-started/intro.md b/nx-dev/nx-dev/public/documentation/shared/getting-started/intro.md index d7eafc0900..0082597b43 100644 --- a/nx-dev/nx-dev/public/documentation/shared/getting-started/intro.md +++ b/nx-dev/nx-dev/public/documentation/shared/getting-started/intro.md @@ -16,41 +16,12 @@ the boilerplate. However, the vast majority of the features will work the same w ## Getting Started -These guides will help you get started: +- [Using Nx without plugins](/getting-started/nx-core) will help you understand the core of Nx. +- [Adding Nx to an existing monorepo](/migration/adding-to-monorepo) will show how to add Nx to an existing monorepo. +- [Mental model](/using-nx/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 guides: -- [Installing Nx CLI & creating a new Nx Workspace](/getting-started/nx-setup) -- [Adding Nx to an existing monorepo](/migration/adding-to-monorepo) -- [Using Nx without plugins](/getting-started/nx-core) - [Nx and TypeScript](/getting-started/nx-and-typescript) - [Nx and React](/getting-started/nx-and-react) - [Nx and Angular](/getting-started/nx-and-angular) -- [CI Overview](/using-nx/ci-overview) - -## Features - -**Best-in-Class Support for Monorepos** - -- [Smart rebuilds of affected projects](/using-nx/affected) -- [Computation caching](/using-nx/caching) -- [Distributed task execution](/using-nx/dte) -- [Code sharing and ownership management](/structure/monorepo-tags) - -**Integrated Development Experience** - -- [High-quality editor plugins](/using-nx/console) & [GitHub apps](https://github.com/apps/nx-cloud) -- [Powerful code generators](/generators/using-schematics) -- [Workspace visualizations](/structure/dependency-graph) - -**Supports Your Ecosystem** - -- [Rich plugin ecosystem](/getting-started/nx-devkit) from Nrwl and the [community](/community) -- Consistent dev experience for any framework -- [Automatic upgrade to the latest versions of all frameworks and tools](/using-nx/updating-nx) - -## Learn While Doing - -- [Using Nx without plugins](/getting-started/nx-core) -- [Nx and TypeScript](/getting-started/nx-and-typescript) -- [React: Interactive Nx Tutorial (with videos)](/react-tutorial/01-create-application) -- [Node: Interactive Nx Tutorial (with videos)](/node-tutorial/01-create-application) -- [Angular: Interactive Nx Tutorial (with videos)](/angular-tutorial/01-create-application) diff --git a/nx-dev/nx-dev/public/documentation/shared/getting-started/nx-and-angular.md b/nx-dev/nx-dev/public/documentation/shared/getting-started/nx-and-angular.md index 71c7934152..43ae530c23 100644 --- a/nx-dev/nx-dev/public/documentation/shared/getting-started/nx-and-angular.md +++ b/nx-dev/nx-dev/public/documentation/shared/getting-started/nx-and-angular.md @@ -8,12 +8,10 @@ If you're only interested in improving the performance of your monorepo by using Check out the following guides to get started: -- [Installing Nx CLI & creating a new Nx Workspace](/getting-started/nx-setup) +- [Using Nx without plugins](/getting-started/nx-core) - [Adding Nx to an existing monorepo](/migration/adding-to-monorepo) - [Adding Nx to an Angular CLI project](/migration/migration-angular) - [Migrating from AngularJS](/migration/migration-angularjs) -- [Using Nx without plugins](/getting-started/nx-core) -- [CI Overview](/using-nx/ci-overview) It is also a good idea to read the [mental model guide](/using-nx/mental-model) to understand how Nx works. @@ -23,8 +21,6 @@ Nx plugins helps you develop [Angular](/angular/overview) applications with full modern tools and libraries like [Jest](/jest/overview), [Cypress](/cypress/overview), [ESLint](/linter/eslint), Storybook, [NgRx](/angular/guides/misc-ngrx) and more. -### 10-min Video Overview - Check out the following to get started: diff --git a/nx-dev/nx-dev/public/documentation/shared/getting-started/nx-and-react.md b/nx-dev/nx-dev/public/documentation/shared/getting-started/nx-and-react.md index ef1064ad00..202babf572 100644 --- a/nx-dev/nx-dev/public/documentation/shared/getting-started/nx-and-react.md +++ b/nx-dev/nx-dev/public/documentation/shared/getting-started/nx-and-react.md @@ -8,11 +8,9 @@ If you're only interested in improving the performance of your monorepo by using Check out the following guides to get started: -- [Installing Nx CLI & creating a new Nx Workspace](/getting-started/nx-setup) +- [Using Nx without plugins](/getting-started/nx-core) - [Adding Nx to an existing monorepo](/migration/adding-to-monorepo) - [Migrating from CRA](/migration/migration-cra) -- [Using Nx without plugins](/getting-started/nx-core) -- [CI Overview](/using-nx/ci-overview) It is also a good idea to read the [mental model guide](/using-nx/mental-model) to understand how Nx works. @@ -21,9 +19,7 @@ It is also a good idea to read the [mental model guide](/using-nx/mental-model) Nx plugins help you develop [React](/react/overview) applications with fully integrated support for modern tools and libraries like [Jest](/jest/overview), [Cypress](/cypress/overview), Storybook, [ESLint](/linter/eslint), and more. Nx also supports React -frameworks like [Gatsby](/gatsby/overview), [Next.js](/guides/nextjs), Remix, and has great support for React Native. - -### 10-min Video Overview +frameworks like [Gatsby](/gatsby/overview), [Next.js](/guides/nextjs), Remix, and has great support for [React Native](/react-native/overview). diff --git a/nx-dev/nx-dev/public/documentation/shared/guides/nx-and-ts.md b/nx-dev/nx-dev/public/documentation/shared/guides/nx-and-ts.md index 7370247af5..9620b32981 100644 --- a/nx-dev/nx-dev/public/documentation/shared/guides/nx-and-ts.md +++ b/nx-dev/nx-dev/public/documentation/shared/guides/nx-and-ts.md @@ -10,7 +10,7 @@ The `@nrwl/js` package ships with corresponding generators and executors that be `@nrwl/js` is particularly useful if you want to -- Create framework agnostic TypeScript libraries within an existing Nx workspace (say to use in your React, Node or Angular app) +- Create framework-agnostic TypeScript libraries within an existing Nx workspace (say to use in your React, Node or Angular app) - Publish TypeScript packages to NPM To get started with TypeScript packages in Nx, either add the `@nrwl/js` package to an existing Nx workspace or generate a new Nx workspace using the `--preset=ts` preset. diff --git a/nx-dev/nx-dev/public/documentation/shared/nx-core.md b/nx-dev/nx-dev/public/documentation/shared/nx-core.md index d4bcc64444..818cefc2f4 100644 --- a/nx-dev/nx-dev/public/documentation/shared/nx-core.md +++ b/nx-dev/nx-dev/public/documentation/shared/nx-core.md @@ -10,7 +10,7 @@ of Nx are completely generic and can be used with any technology or tool. ### Creating a New Workspace -Running `yarn create nx-workspace --preset=core` creates an empty workspace. +Running `npx create-nx-workspace@latest --preset=core` creates an empty workspace. This is what is generated: @@ -58,8 +58,6 @@ package.json } ``` -Finally, `workspace.json` lists the workspace projects, and since we have none, it is empty. - ### Creating an NPM Package Running `nx g npm-package simple` results in: @@ -88,17 +86,12 @@ The generated `simple/package.json`: ``` With this you can invoke any script defined in `packages/simple/package.json` via Nx. For instance, you can invoke the `test` -script by running `yarn nx test simple`. And if you invoke this command a second time, the results are retrieved from +script by running `nx test simple`. And if you invoke this command a second time, the results are retrieved from cache. In this example, we used a generator to create the package, but you could have also created it by hand or copied it from another project. -The change in `workspace.json` is the only thing required to make Nx aware of the `simple` package. As long as you -include the project in `workspace.json`, Nx will include that project source in its graph computation and source -code analysis. It will, for instance, analyze the project's source code, and it will know when it can reuse the -computation from the cache and when it has to recompute it from scratch. - ### Creating Second NPM Package and Enabling Yarn Workspaces Running `nx g npm-package complex` results in: @@ -117,7 +110,7 @@ tsconfig.base.json package.json ``` -Now let's modify `packages/complex/index.js` to include `require('@myorg/simple')`. If you run `yarn nx test complex`, +Now let's modify `packages/complex/index.js` to include `require('@myorg/simple')`. If you run `nx test complex`, you will see an error saying that `@myorg/simple` cannot be resolved. This is expected. Nx analyzes your source to enable computation caching, it knows what projects are affected by your PR, @@ -139,17 +132,9 @@ To make it work, add a dependency from `complex` to `simple` in `packages/comple } ``` -Then add the following to the root `package.json` (which enables Yarn Workspaces). - -```json -{ - "workspaces": ["packages/*"] -} -``` - Finally, run `yarn`. -`yarn nx test complex` works now. +`nx test complex` works now. ## Using Yarn/PNPM/Lerna @@ -162,7 +147,7 @@ elegant way. [Read about the relationship between Nx and Yarn/Lerna/PNPM](/guide ### Nx Understands How Your Workspace Is Structured -If you run `yarn nx dep-graph` you will see that `complex` has a dependency on `simple`. Any change to `simple` will +If you run `nx dep-graph` you will see that `complex` has a dependency on `simple`. Any change to `simple` will invalidate the computation cache for `complex`, but changes to `complex` won't invalidate the cache for `simple`. In contrast to more basic monorepo tools, Nx doesn't just analyze `package.json` files. It does much more. Nx also knows @@ -170,19 +155,19 @@ that adding a `require()` creates a dependency and that some dependencies cannot ### Nx Orchestrates Tasks -Running `yarn nx run-many --target=test --all` will test all projects in parallel. +Running `nx run-many --target=test --all` will test all projects in parallel. -Running `yarn nx run-many --target=build --projects=app1,app2` will build `proj1` and `proj2` and their -dependencies in parallel. Note that if `app1` depends on the output of its dependency (e.g., `shared-components`), Nx -will build `shared-components` first and only then will build the app. +Often, tests for different projects can run independently, but builds can't. If you, say, have two applications `app1` and `app2` depending on the `shared-components` library, it's possible that the library has to be built first before the two applications can be built. And that's what `nx run-many --target=build --projects=app1,app2` will do. + +With Nx, you never have to worry about preparing your workspace before running a particular command. Nx will do it for you. ### Nx Knows What Is Affected -Running `yarn nx affected --target=test` will test all the projects affected by the current PR. +Running `nx affected --target=test` will test all the projects affected by the current PR. ### Nx Caches and Distributes Tasks -Running `yarn nx build app1` will cache the file artifacts and the terminal output, so if you run it again the command +Running `nx run-many --target=build --all` will cache the file artifacts and the terminal output, so if you run it again the command will execute instantly because the results will be retrieved from cache. If you use `Nx Cloud` the cache will be shared between you, your teammates, and the CI agents. Nx can also distribute tasks across multiple machines while preserving the developer experience of running it on a single machine. diff --git a/nx-dev/nx-dev/public/documentation/shared/using-nx/dte.md b/nx-dev/nx-dev/public/documentation/shared/using-nx/dte.md index 6f0bc6d699..6aa9d232a0 100644 --- a/nx-dev/nx-dev/public/documentation/shared/using-nx/dte.md +++ b/nx-dev/nx-dev/public/documentation/shared/using-nx/dte.md @@ -27,4 +27,8 @@ it locally. ## Example -- [This is an example repo](https://github.com/vsavkin/interstellar) showing how easy it is to set up distributed task execution, showing the performance gains, and comparing to sharding/binnig. +[This is an example repo](https://github.com/vsavkin/interstellar) showing how easy it is to set up distributed task execution, showing the performance gains, and comparing to sharding/binnig. + +These are the savings you get by enabling Distributed Task Execution in your CI config: + +![DTE](/shared/using-nx/dte.png) diff --git a/nx-dev/nx-dev/public/documentation/shared/using-nx/dte.png b/nx-dev/nx-dev/public/documentation/shared/using-nx/dte.png new file mode 100644 index 0000000000..d5e9cd4eb6 Binary files /dev/null and b/nx-dev/nx-dev/public/documentation/shared/using-nx/dte.png differ