docs(core): add a plugin about using nx without plugins
This commit is contained in:
Victor Savkin
Victor Savkin
parent
09fe7ab55c
commit
a20f326ac4
@ -41,6 +41,7 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore
|
||||
## Learn Nx Fundamentals
|
||||
|
||||
- [Interactive Nx Tutorial (with videos)](/{{framework}}/tutorial/01-create-application)
|
||||
- [Using Nx Core Without Plugins](/{{framework}}/core-concepts/nx-core)
|
||||
- [Free Nx Course on YouTube](https://www.youtube.com/watch?time_continue=49&v=2mYLe9Kp9VM&feature=emb_logo)
|
||||
- [45-Minute Walkthrough on YouTube](https://www.youtube.com/watch?v=h5FIGDn5YM0)
|
||||
- [Nx CLI](/{{framework}}/getting-started/nx-cli)
|
||||
|
||||
@ -4,6 +4,8 @@
|
||||
|
||||
In this tutorial you use Nx to build a full-stack application out of common libraries using modern technologies like Cypress and Nest.
|
||||
|
||||
> This tutorial uses several Nx plugins to provide a rich dev experience. **All the plugins are optional.** [Read about using Nx Core without plugins](/{{framework}}/core-concepts/nx-core).
|
||||
|
||||
## Create a new workspace
|
||||
|
||||
**Start by creating a new workspace.**
|
||||
|
||||
@ -96,6 +96,11 @@
|
||||
"id": "configuration",
|
||||
"file": "angular/guides/configuration"
|
||||
},
|
||||
{
|
||||
"name": "Nx Core",
|
||||
"id": "nx-core",
|
||||
"file": "shared/nx-core"
|
||||
},
|
||||
{
|
||||
"name": "Nx Plugins and Devkit",
|
||||
"id": "nx-devkit",
|
||||
@ -1378,6 +1383,11 @@
|
||||
"id": "configuration",
|
||||
"file": "react/guides/configuration"
|
||||
},
|
||||
{
|
||||
"name": "Nx Core",
|
||||
"id": "nx-core",
|
||||
"file": "shared/nx-core"
|
||||
},
|
||||
{
|
||||
"name": "Nx Plugins and Devkit",
|
||||
"id": "nx-devkit",
|
||||
@ -2624,6 +2634,11 @@
|
||||
"id": "configuration",
|
||||
"file": "node/guides/configuration"
|
||||
},
|
||||
{
|
||||
"name": "Nx Core",
|
||||
"id": "nx-core",
|
||||
"file": "shared/nx-core"
|
||||
},
|
||||
{
|
||||
"name": "Nx Plugins and Devkit",
|
||||
"id": "nx-devkit",
|
||||
|
||||
@ -37,6 +37,7 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore
|
||||
## Learn Nx Fundamentals
|
||||
|
||||
- [Interactive Nx Tutorial (with videos)](/{{framework}}/tutorial/01-create-application)
|
||||
- [Using Nx Core Without Plugins](/{{framework}}/core-concepts/nx-core)
|
||||
- [Free Nx Course on YouTube](https://www.youtube.com/watch?time_continue=49&v=2mYLe9Kp9VM&feature=emb_logo)
|
||||
- [Nx CLI](/{{framework}}/getting-started/nx-cli)
|
||||
- [Configuration Files](/{{framework}}/core-concepts/configuration)
|
||||
|
||||
@ -4,6 +4,8 @@
|
||||
|
||||
In this tutorial you use Nx to build a server application out of common libraries using modern technologies.
|
||||
|
||||
> This tutorial uses several Nx plugins to provide a rich dev experience. **All the plugins are optional.** [Read about using Nx Core without plugins](/{{framework}}/core-concepts/nx-core).
|
||||
|
||||
## Create a New Workspace
|
||||
|
||||
**Start by creating a new workspace.**
|
||||
|
||||
@ -42,6 +42,7 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore
|
||||
## Learn Nx Fundamentals
|
||||
|
||||
- [Interactive Nx Tutorial (with videos)](/{{framework}}/tutorial/01-create-application)
|
||||
- [Using Nx Core Without Plugins](/{{framework}}/core-concepts/nx-core)
|
||||
- [Free Nx Course on Egghead: Scale React Development with Nx](https://egghead.io/playlists/scale-react-development-with-nx-4038)
|
||||
- [45-Minute Walkthrough](https://www.youtube.com/watch?v=jCf92IyR-GE)
|
||||
- [Nx CLI](/{{framework}}/getting-started/nx-cli)
|
||||
|
||||
@ -6,6 +6,8 @@ In this tutorial you use Nx to build a full-stack application out of common libr
|
||||
|
||||
> Next.js: Nx also has first-class Next.js support. Read more about it [here](/{{framework}}/next/overview)
|
||||
|
||||
> This tutorial uses several Nx plugins to provide a rich dev experience. **All the plugins are optional.** [Read about using Nx Core without plugins](/{{framework}}/core-concepts/nx-core).
|
||||
|
||||
## Create a new workspace
|
||||
|
||||
Start by creating a new workspace.
|
||||
|
||||
235
docs/shared/nx-core.md
Normal file
235
docs/shared/nx-core.md
Normal file
@ -0,0 +1,235 @@
|
||||
# Using Nx Core Without Plugins
|
||||
|
||||
The core of Nx is generic, simple, and unobtrusive. Nx Plugins, although very useful for many projects, are completely
|
||||
optional. This guide will walk you through creating a simple Nx workspace with no plugins.
|
||||
|
||||
## Using Nx Core
|
||||
|
||||
### Creating a New Workspace
|
||||
|
||||
Running `yarn create nx-workspace --preset=npm` creates an empty workspace.
|
||||
|
||||
This is what is generated:
|
||||
|
||||
```text
|
||||
packages/
|
||||
nx.json
|
||||
workspace.json
|
||||
tsconfig.base.json
|
||||
package.json
|
||||
```
|
||||
|
||||
`package.json` contains Nx packages.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "myorg",
|
||||
"version": "0.0.0",
|
||||
"license": "MIT",
|
||||
"scripts": {},
|
||||
"private": true,
|
||||
"devDependencies": {
|
||||
"@nrwl/cli": "12.8.0",
|
||||
"@nrwl/tao": "12.8.0",
|
||||
"@nrwl/workspace": "12.8.0",
|
||||
"@types/node": "14.14.33",
|
||||
"typescript": "~4.3.5"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`nx.json` contains the Nx CLI configuration.
|
||||
|
||||
```json
|
||||
{
|
||||
"extends": "@nrwl/workspace/presets/npm.json",
|
||||
"npmScope": "myorg",
|
||||
"tasksRunnerOptions": {
|
||||
"default": {
|
||||
"runner": "@nrwl/workspace/tasks-runners/default",
|
||||
"options": {
|
||||
"cacheableOperations": ["build", "lint", "test", "e2e"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```text
|
||||
packages/
|
||||
simple/
|
||||
index.js
|
||||
package.json
|
||||
nx.json
|
||||
workspace.json
|
||||
tsconfig.base.json
|
||||
package.json
|
||||
```
|
||||
|
||||
The generated `simple/package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@myorg/simple",
|
||||
"version": "1.0.0",
|
||||
"scripts": {
|
||||
"test": "node index.js"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
And `workspace.json` gets updated to:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"projects": {
|
||||
"simple": {
|
||||
"root": "packages/simple"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With this you can invoke any script defined in `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
|
||||
cache.
|
||||
|
||||
In this example, we used a generator to create the package, but you could also have created it by hand or have 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 into `workspace.json`, Nx will include that project source into 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:
|
||||
|
||||
```text
|
||||
packages/
|
||||
simple/
|
||||
index.js
|
||||
package.json
|
||||
complex/
|
||||
index.js
|
||||
package.json
|
||||
nx.json
|
||||
workspace.json
|
||||
tsconfig.base.json
|
||||
package.json
|
||||
```
|
||||
|
||||
Now let's modify `packages/complex/index.js` to include `require('@myorg/simple')`. If you run `npx 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,
|
||||
but it **does not** change how your npm scripts run. Whatever tools you use in your npm scripts will run exactly as they
|
||||
would without Nx. **Nx Core doesn't replace your tools and doesn't change how they work.**
|
||||
|
||||
To make it work add a dependency from `complex` to `simple` in `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@myorg/complex",
|
||||
"version": "1.0.0",
|
||||
"scripts": {
|
||||
"test": "node index.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"@myorg/simple": "*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then add the following to the root `package.json` (which enables Yarn Workspaces).
|
||||
|
||||
```json
|
||||
{
|
||||
"workspaces": ["packages/*"]
|
||||
}
|
||||
```
|
||||
|
||||
Finally, run `yarn`.
|
||||
|
||||
`npx nx test complex` works now.
|
||||
|
||||
## Non-JS Projects
|
||||
|
||||
In this example both projects use JavaScript, but we could have created, say, a Rust project instead. The only thing we
|
||||
would have to do is to manually define targets.
|
||||
|
||||
This is an example of manually defining a target ([read more about it](/{{framework}}/workspace/run-commands-executor)):
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"projects": {
|
||||
"simple": {
|
||||
"root": "packages/simple",
|
||||
"targets": {
|
||||
"test": {
|
||||
"executor": "@nrwl/workspace:run-commands",
|
||||
"options": {
|
||||
"command": "npm run test"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Using Yarn/PNPM/Lerna
|
||||
|
||||
The example uses Yarn to connect the two packages. Most of the time, however, there are better ways to do it. The React,
|
||||
Node, Angular plugins for Nx allow different projects in your workspace to import each other without having to maintain
|
||||
cumbersome `package.json` files. Instead, they use Webpack, Rollup and Jest plugins to enable this use case in a more
|
||||
elegant way. [Read about the relationship between Nx and Yarn/Lerna/PNPM](/{{framework}}/guides/lerna-and-nx).
|
||||
|
||||
## What Nx Provides
|
||||
|
||||
If you run `npx 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 JS monorepo tools, Nx doesn't just analyze `package.json` files. It does much more. Nx also
|
||||
knows that adding a `require()` creates a dependency and that some dependencies cannot even be expressed in the source
|
||||
code. This is crucial for the following reasons:
|
||||
|
||||
- Often, configuration files aren't packages. They aren't built and aren't published. Your packages can depend on them.
|
||||
Nx can recognize this dependency and take it into consideration for `affected:*` and cache computations.
|
||||
- Many workspaces have non-JS projects, so you cannot define the deps between them and your JS projects
|
||||
using `package.json`.
|
||||
- Aux packages (e.g., e2e tests or demo applications) aren't publishable. You could create fake `package.json` files for
|
||||
them, but with Nx you don't have to.
|
||||
- You may have a de-facto dependency (where Project A depends on B without a dependency in `package.json`). This would
|
||||
break other monorepo tools because they would not know that changing B changes the behavior of A. This isn’t the case
|
||||
with Nx.
|
||||
|
||||
### Some Things You Can Do
|
||||
|
||||
- `npx nx run-many --target --test --all --parallel` tests all projects in parallel.
|
||||
- `npx nx affected --target --test --all` tests all the projects affected by the current PR. To see this in action,
|
||||
check in all your changes, and create a new branch.
|
||||
|
||||
## Adding Plugins
|
||||
|
||||
As you can see, the core of Nx is generic, simple, and unobtrusive. Nx Plugins are completely optional, but they can
|
||||
really level up your developer experience. Watch the video below to see Nx plugins in action.
|
||||
|
||||
[Read more about Nx plugins](/{{framework}}/core-concepts/nx-devkit).
|
||||
|
||||
## Adding Nx to Existing Workspaces
|
||||
|
||||
The following 10-min video walks you through the steps of adding Nx to a Lerna repo and showing many affordances Nx
|
||||
offers. Although the video uses Lerna, everything said applies to Yarn Workspaces or PNPM. Basically, any time you
|
||||
hear "Lerna" you can substitute it for Yarn or PNPM.
|
||||
|
||||
<iframe width="560" height="315" src="https://www.youtube.com/embed/BO1rwynFBLM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
||||
@ -68,26 +68,6 @@ Type: `boolean`
|
||||
|
||||
Only register the root state management setup or feature state.
|
||||
|
||||
### ~~onlyAddFiles~~
|
||||
|
||||
Default: `false`
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
**Deprecated:** Use the `skipImport` option instead.
|
||||
|
||||
Only add new NgRx files, without changing the module file (e.g., `--onlyAddFiles`).
|
||||
|
||||
### ~~onlyEmptyRoot~~
|
||||
|
||||
Default: `false`
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
**Deprecated:** Use the `minimal` option instead.
|
||||
|
||||
Do not generate any files. Only generate `StoreModule.forRoot` and `EffectsModule.forRoot` (e.g., `--onlyEmptyRoot`).
|
||||
|
||||
### root
|
||||
|
||||
Default: `false`
|
||||
|
||||
@ -1,8 +1,6 @@
|
||||
# daemon
|
||||
|
||||
EXPERIMENTAL: Nx Daemon
|
||||
|
||||
The Nx Daemon is a local server which runs in the background in order to intelligently cache information about the workspace's project graph.
|
||||
EXPERIMENTAL: Nx DaemonThe Nx Daemon is a local server which runs in the background in order to intelligently cache information about the workspace's project graph.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -41,6 +41,7 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore
|
||||
## Learn Nx Fundamentals
|
||||
|
||||
- [Interactive Nx Tutorial (with videos)](/{{framework}}/tutorial/01-create-application)
|
||||
- [Using Nx Core Without Plugins](/{{framework}}/core-concepts/nx-core)
|
||||
- [Free Nx Course on YouTube](https://www.youtube.com/watch?time_continue=49&v=2mYLe9Kp9VM&feature=emb_logo)
|
||||
- [45-Minute Walkthrough on YouTube](https://www.youtube.com/watch?v=h5FIGDn5YM0)
|
||||
- [Nx CLI](/{{framework}}/getting-started/nx-cli)
|
||||
|
||||
@ -4,6 +4,8 @@
|
||||
|
||||
In this tutorial you use Nx to build a full-stack application out of common libraries using modern technologies like Cypress and Nest.
|
||||
|
||||
> This tutorial uses several Nx plugins to provide a rich dev experience. **All the plugins are optional.** [Read about using Nx Core without plugins](/{{framework}}/core-concepts/nx-core).
|
||||
|
||||
## Create a new workspace
|
||||
|
||||
**Start by creating a new workspace.**
|
||||
|
||||
@ -96,6 +96,11 @@
|
||||
"id": "configuration",
|
||||
"file": "angular/guides/configuration"
|
||||
},
|
||||
{
|
||||
"name": "Nx Core",
|
||||
"id": "nx-core",
|
||||
"file": "shared/nx-core"
|
||||
},
|
||||
{
|
||||
"name": "Nx Plugins and Devkit",
|
||||
"id": "nx-devkit",
|
||||
@ -1373,6 +1378,11 @@
|
||||
"id": "configuration",
|
||||
"file": "react/guides/configuration"
|
||||
},
|
||||
{
|
||||
"name": "Nx Core",
|
||||
"id": "nx-core",
|
||||
"file": "shared/nx-core"
|
||||
},
|
||||
{
|
||||
"name": "Nx Plugins and Devkit",
|
||||
"id": "nx-devkit",
|
||||
@ -2614,6 +2624,11 @@
|
||||
"id": "configuration",
|
||||
"file": "node/guides/configuration"
|
||||
},
|
||||
{
|
||||
"name": "Nx Core",
|
||||
"id": "nx-core",
|
||||
"file": "shared/nx-core"
|
||||
},
|
||||
{
|
||||
"name": "Nx Plugins and Devkit",
|
||||
"id": "nx-devkit",
|
||||
|
||||
@ -68,26 +68,6 @@ Type: `boolean`
|
||||
|
||||
Only register the root state management setup or feature state.
|
||||
|
||||
### ~~onlyAddFiles~~
|
||||
|
||||
Default: `false`
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
**Deprecated:** Use the `skipImport` option instead.
|
||||
|
||||
Only add new NgRx files, without changing the module file (e.g., `--onlyAddFiles`).
|
||||
|
||||
### ~~onlyEmptyRoot~~
|
||||
|
||||
Default: `false`
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
**Deprecated:** Use the `minimal` option instead.
|
||||
|
||||
Do not generate any files. Only generate `StoreModule.forRoot` and `EffectsModule.forRoot` (e.g., `--onlyEmptyRoot`).
|
||||
|
||||
### root
|
||||
|
||||
Default: `false`
|
||||
|
||||
@ -1,8 +1,6 @@
|
||||
# daemon
|
||||
|
||||
EXPERIMENTAL: Nx Daemon
|
||||
|
||||
The Nx Daemon is a local server which runs in the background in order to intelligently cache information about the workspace's project graph.
|
||||
EXPERIMENTAL: Nx DaemonThe Nx Daemon is a local server which runs in the background in order to intelligently cache information about the workspace's project graph.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -37,6 +37,7 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore
|
||||
## Learn Nx Fundamentals
|
||||
|
||||
- [Interactive Nx Tutorial (with videos)](/{{framework}}/tutorial/01-create-application)
|
||||
- [Using Nx Core Without Plugins](/{{framework}}/core-concepts/nx-core)
|
||||
- [Free Nx Course on YouTube](https://www.youtube.com/watch?time_continue=49&v=2mYLe9Kp9VM&feature=emb_logo)
|
||||
- [Nx CLI](/{{framework}}/getting-started/nx-cli)
|
||||
- [Configuration Files](/{{framework}}/core-concepts/configuration)
|
||||
|
||||
@ -4,6 +4,8 @@
|
||||
|
||||
In this tutorial you use Nx to build a server application out of common libraries using modern technologies.
|
||||
|
||||
> This tutorial uses several Nx plugins to provide a rich dev experience. **All the plugins are optional.** [Read about using Nx Core without plugins](/{{framework}}/core-concepts/nx-core).
|
||||
|
||||
## Create a New Workspace
|
||||
|
||||
**Start by creating a new workspace.**
|
||||
|
||||
@ -68,26 +68,6 @@ Type: `boolean`
|
||||
|
||||
Only register the root state management setup or feature state.
|
||||
|
||||
### ~~onlyAddFiles~~
|
||||
|
||||
Default: `false`
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
**Deprecated:** Use the `skipImport` option instead.
|
||||
|
||||
Only add new NgRx files, without changing the module file (e.g., `--onlyAddFiles`).
|
||||
|
||||
### ~~onlyEmptyRoot~~
|
||||
|
||||
Default: `false`
|
||||
|
||||
Type: `boolean`
|
||||
|
||||
**Deprecated:** Use the `minimal` option instead.
|
||||
|
||||
Do not generate any files. Only generate `StoreModule.forRoot` and `EffectsModule.forRoot` (e.g., `--onlyEmptyRoot`).
|
||||
|
||||
### root
|
||||
|
||||
Default: `false`
|
||||
|
||||
@ -1,8 +1,6 @@
|
||||
# daemon
|
||||
|
||||
EXPERIMENTAL: Nx Daemon
|
||||
|
||||
The Nx Daemon is a local server which runs in the background in order to intelligently cache information about the workspace's project graph.
|
||||
EXPERIMENTAL: Nx DaemonThe Nx Daemon is a local server which runs in the background in order to intelligently cache information about the workspace's project graph.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -42,6 +42,7 @@ Nx works especially well for [monorepos](/{{framework}}/core-concepts/why-monore
|
||||
## Learn Nx Fundamentals
|
||||
|
||||
- [Interactive Nx Tutorial (with videos)](/{{framework}}/tutorial/01-create-application)
|
||||
- [Using Nx Core Without Plugins](/{{framework}}/core-concepts/nx-core)
|
||||
- [Free Nx Course on Egghead: Scale React Development with Nx](https://egghead.io/playlists/scale-react-development-with-nx-4038)
|
||||
- [45-Minute Walkthrough](https://www.youtube.com/watch?v=jCf92IyR-GE)
|
||||
- [Nx CLI](/{{framework}}/getting-started/nx-cli)
|
||||
|
||||
@ -6,6 +6,8 @@ In this tutorial you use Nx to build a full-stack application out of common libr
|
||||
|
||||
> Next.js: Nx also has first-class Next.js support. Read more about it [here](/{{framework}}/next/overview)
|
||||
|
||||
> This tutorial uses several Nx plugins to provide a rich dev experience. **All the plugins are optional.** [Read about using Nx Core without plugins](/{{framework}}/core-concepts/nx-core).
|
||||
|
||||
## Create a new workspace
|
||||
|
||||
Start by creating a new workspace.
|
||||
|
||||
235
nx-dev/nx-dev/public/documentation/latest/shared/nx-core.md
Normal file
235
nx-dev/nx-dev/public/documentation/latest/shared/nx-core.md
Normal file
@ -0,0 +1,235 @@
|
||||
# Using Nx Core Without Plugins
|
||||
|
||||
The core of Nx is generic, simple, and unobtrusive. Nx Plugins, although very useful for many projects, are completely
|
||||
optional. This guide will walk you through creating a simple Nx workspace with no plugins.
|
||||
|
||||
## Using Nx Core
|
||||
|
||||
### Creating a New Workspace
|
||||
|
||||
Running `yarn create nx-workspace --preset=npm` creates an empty workspace.
|
||||
|
||||
This is what is generated:
|
||||
|
||||
```text
|
||||
packages/
|
||||
nx.json
|
||||
workspace.json
|
||||
tsconfig.base.json
|
||||
package.json
|
||||
```
|
||||
|
||||
`package.json` contains Nx packages.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "myorg",
|
||||
"version": "0.0.0",
|
||||
"license": "MIT",
|
||||
"scripts": {},
|
||||
"private": true,
|
||||
"devDependencies": {
|
||||
"@nrwl/cli": "12.8.0",
|
||||
"@nrwl/tao": "12.8.0",
|
||||
"@nrwl/workspace": "12.8.0",
|
||||
"@types/node": "14.14.33",
|
||||
"typescript": "~4.3.5"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`nx.json` contains the Nx CLI configuration.
|
||||
|
||||
```json
|
||||
{
|
||||
"extends": "@nrwl/workspace/presets/npm.json",
|
||||
"npmScope": "myorg",
|
||||
"tasksRunnerOptions": {
|
||||
"default": {
|
||||
"runner": "@nrwl/workspace/tasks-runners/default",
|
||||
"options": {
|
||||
"cacheableOperations": ["build", "lint", "test", "e2e"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```text
|
||||
packages/
|
||||
simple/
|
||||
index.js
|
||||
package.json
|
||||
nx.json
|
||||
workspace.json
|
||||
tsconfig.base.json
|
||||
package.json
|
||||
```
|
||||
|
||||
The generated `simple/package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@myorg/simple",
|
||||
"version": "1.0.0",
|
||||
"scripts": {
|
||||
"test": "node index.js"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
And `workspace.json` gets updated to:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"projects": {
|
||||
"simple": {
|
||||
"root": "packages/simple"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With this you can invoke any script defined in `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
|
||||
cache.
|
||||
|
||||
In this example, we used a generator to create the package, but you could also have created it by hand or have 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 into `workspace.json`, Nx will include that project source into 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:
|
||||
|
||||
```text
|
||||
packages/
|
||||
simple/
|
||||
index.js
|
||||
package.json
|
||||
complex/
|
||||
index.js
|
||||
package.json
|
||||
nx.json
|
||||
workspace.json
|
||||
tsconfig.base.json
|
||||
package.json
|
||||
```
|
||||
|
||||
Now let's modify `packages/complex/index.js` to include `require('@myorg/simple')`. If you run `npx 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,
|
||||
but it **does not** change how your npm scripts run. Whatever tools you use in your npm scripts will run exactly as they
|
||||
would without Nx. **Nx Core doesn't replace your tools and doesn't change how they work.**
|
||||
|
||||
To make it work add a dependency from `complex` to `simple` in `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@myorg/complex",
|
||||
"version": "1.0.0",
|
||||
"scripts": {
|
||||
"test": "node index.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"@myorg/simple": "*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then add the following to the root `package.json` (which enables Yarn Workspaces).
|
||||
|
||||
```json
|
||||
{
|
||||
"workspaces": ["packages/*"]
|
||||
}
|
||||
```
|
||||
|
||||
Finally, run `yarn`.
|
||||
|
||||
`npx nx test complex` works now.
|
||||
|
||||
## Non-JS Projects
|
||||
|
||||
In this example both projects use JavaScript, but we could have created, say, a Rust project instead. The only thing we
|
||||
would have to do is to manually define targets.
|
||||
|
||||
This is an example of manually defining a target ([read more about it](/{{framework}}/workspace/run-commands-executor)):
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 2,
|
||||
"projects": {
|
||||
"simple": {
|
||||
"root": "packages/simple",
|
||||
"targets": {
|
||||
"test": {
|
||||
"executor": "@nrwl/workspace:run-commands",
|
||||
"options": {
|
||||
"command": "npm run test"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Using Yarn/PNPM/Lerna
|
||||
|
||||
The example uses Yarn to connect the two packages. Most of the time, however, there are better ways to do it. The React,
|
||||
Node, Angular plugins for Nx allow different projects in your workspace to import each other without having to maintain
|
||||
cumbersome `package.json` files. Instead, they use Webpack, Rollup and Jest plugins to enable this use case in a more
|
||||
elegant way. [Read about the relationship between Nx and Yarn/Lerna/PNPM](/{{framework}}/guides/lerna-and-nx).
|
||||
|
||||
## What Nx Provides
|
||||
|
||||
If you run `npx 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 JS monorepo tools, Nx doesn't just analyze `package.json` files. It does much more. Nx also
|
||||
knows that adding a `require()` creates a dependency and that some dependencies cannot even be expressed in the source
|
||||
code. This is crucial for the following reasons:
|
||||
|
||||
- Often, configuration files aren't packages. They aren't built and aren't published. Your packages can depend on them.
|
||||
Nx can recognize this dependency and take it into consideration for `affected:*` and cache computations.
|
||||
- Many workspaces have non-JS projects, so you cannot define the deps between them and your JS projects
|
||||
using `package.json`.
|
||||
- Aux packages (e.g., e2e tests or demo applications) aren't publishable. You could create fake `package.json` files for
|
||||
them, but with Nx you don't have to.
|
||||
- You may have a de-facto dependency (where Project A depends on B without a dependency in `package.json`). This would
|
||||
break other monorepo tools because they would not know that changing B changes the behavior of A. This isn’t the case
|
||||
with Nx.
|
||||
|
||||
### Some Things You Can Do
|
||||
|
||||
- `npx nx run-many --target --test --all --parallel` tests all projects in parallel.
|
||||
- `npx nx affected --target --test --all` tests all the projects affected by the current PR. To see this in action,
|
||||
check in all your changes, and create a new branch.
|
||||
|
||||
## Adding Plugins
|
||||
|
||||
As you can see, the core of Nx is generic, simple, and unobtrusive. Nx Plugins are completely optional, but they can
|
||||
really level up your developer experience. Watch the video below to see Nx plugins in action.
|
||||
|
||||
[Read more about Nx plugins](/{{framework}}/core-concepts/nx-devkit).
|
||||
|
||||
## Adding Nx to Existing Workspaces
|
||||
|
||||
The following 10-min video walks you through the steps of adding Nx to a Lerna repo and showing many affordances Nx
|
||||
offers. Although the video uses Lerna, everything said applies to Yarn Workspaces or PNPM. Basically, any time you
|
||||
hear "Lerna" you can substitute it for Yarn or PNPM.
|
||||
|
||||
<iframe width="560" height="315" src="https://www.youtube.com/embed/BO1rwynFBLM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
||||
Loading…
x
Reference in New Issue
Block a user