Getting Started with Integrated Repos
Create a New Workspace
Start by creating a new workspace. We can use the following command that will help us set it up.
npx create-nx-workspace@latest myorg --preset=ts
The file structure should look like this:
myorg/
├── packages/
├── tools/
├── nx.json
├── package.json
├── README.md
└── tsconfig.base.json
Create a Package
Nx comes with generators that can help with scaffolding applications. Run this generator to make a new library named is-even
:
npx nx generate @nrwl/js:library is-even --publishable --importPath @myorg/is-even
This command:
- Uses the
@nrwl/js
plugin'slibrary
generator to scaffold a new library namedis-even
. - The
--publishable
flag makes sure we also get apackage.json
generated and apublish
target we can invoke to publish to NPM. - The
--importPath
allows us to define the name of the NPM package.
You should now have the following structure:
packages/
└── is-even/
├── src/
| └── lib/
| | ├── is-even.spec.ts
| | ├── is-even.ts
| └── index.ts
├── project.json
├── package.json
├── ...
└── tsconfig.json
Update is-even.ts
with this content:
export function isEven(x: number): boolean {
return x % 2 === 0;
}
The Nx plugins use a project-level project.json
to manage the metadata around the available targets that can be run for a given project. The generated project.json
for is-even
contains build
, publish
, lint
and test
targets:
{
"name": "is-even",
"targets": {
"build": {
/* ... */
},
"publish": {
/* ... */
},
"lint": {
/* ... */
},
"test": {
/* ... */
}
}
}
You can dive into the various settings to fine-tune the options used for building, publishing, linting or testing the package. The low-level details are being taken care of by the plugin.
Running
npx nx build is-even
builds the src files and places a ready-to-be-published package indist/packages/is-even
at the root of your workspacenpx nx publish is-even
runs a publish script fromdist/packages/is-even
to push your package to NPMnpx nx test is-even
runs the pre-configured Jest tests for the packagenpx nx lint is-even
runs the pre-configured ESLint checks for the package
Local Linking of Packages
The local linking of packages in an integrated monorepo style is handled by Nx automatically by leveraging TypeScript path mappings in the tsconfig.base.json
file.
To illustrate that, let's create another package is-odd
. We can again run the generator for that:
npx nx generate @nrwl/js:library is-odd --publishable --importPath @myorg/is-odd
Note how the tsconfig.base.json
now has two entries:
{
"compileOnSave": false,
"compilerOptions": {
...
"paths": {
"@myorg/is-even": ["packages/is-even/src/index.ts"],
"@myorg/is-odd": ["packages/is-odd/src/index.ts"]
}
}
}
Update the is-odd.ts
implemention in the is-odd
package to import isEven
from the @myorg/is-even
package:
import { isEven } from '@myorg/is-even';
export function isOdd(x: number): boolean {
return !isEven(x);
}
This is all that needs to be done.
Task Dependencies
In a monorepo there are not just dependencies among packages, but also among their tasks.
For example, whenever we build is-odd
we need to ensure that is-even
is built beforehand. Nx can define such task dependencies by adding a targetDefaults
property to nx.json.
In an integrated monorepo style this is already being dealt with by the generators. The current nx.json
file already comes with defaults that work out of the box:
{
...
"targetDefaults": {
"build": {
"dependsOn": ["^build"],
...
},
...
},
...
}
This tells Nx to run the build
target of all the dependent projects first, before the build
target of the package itself is being run.
Remove any existing dist
folder at the root of the workspace and run:
npx nx build is-odd
It will automatically first run npx nx build is-even
, so you should end up with both packages in your dist folder. Note that if is-even
has been built before, it would just be restored out of the cache.
Cache Build Results
To build the is-even
package run:
npx nx build is-even
Run the same command a second time and you'll see the build cache is being used:
~/workspace❯
npx nx build is-even
> nx run is-even:build
Compiling TypeScript files for project "is-even"...
Done compiling TypeScript files for project "is-even".
—————————————————————————————————————————————————————————————————————
> NX Successfully ran target build for project is-even (713ms)
Running Multiple Tasks
To run the build
target for all the packages in the workspace, use:
npx nx run-many --target=build
What you would get is the following:
~/workspace❯
npx nx run-many --target=build
✔ nx run is-even:build [existing outputs match the cache, left as is]
✔ nx run is-odd:build (906ms)
—————————————————————————————————————————————————————————————————
> NX Successfully ran target build for 2 projects (914ms)
Nx read the output from the cache instead of running the command for 1 out of 2 tasks.
Note how on the is-even:build
it didn't run the build but rather pulled it out of the cache because the build has ran before. If you re-run the run-many
command all of the builds would be cached.
You can also only run tasks on packages that got changed by using
npx nx affected --target=build
Learn More
Read about the core features of Nx.
Get a deeper understanding of the mental model.
Learn how to add Nx to your existing repo.
Learn about two styles of monorepos.
A step-by-step tutorial showing how to build an integrated monorepo with React applications sharing code.
A step-by-step tutorial showing how to build an integrated monorepo with Node.js applications sharing code.