nx/packages/schematics

Angular Extensions: Schematics

Nx (Angular Extensions) is a set of libraries and schematics for the Angular framework.

Installing

Add the following dependencies to your project's package.json and run npm install:

{
  dependencies: {
    "@nrwl/schematics": "https://github.com/nrwl/schematics-build"
  }
}

Schematics

Installing Nrwl/Schematics

To be able to do ng new proj --collection=@nrwl/schematics, the @nrwl/schematics must be available in the current context. There are multiple ways to achieve this.

Global Install

Use Yarn instead of Npm. Global install with peer dependencies is broken on NPM--it works fine with yarn.

yarn global add @angular/cli
yarn global add @nrwl/schematics
ng new proj --collection=@nrwl/schematics

While things are in flux, use the following three commands instead:

yarn global add nrwl/fix-cli-build
yarn global add nrwl/schematics-build
ng new proj --collection=@nrwl/schematics

Local Install

mkdir context
cd context
touch package.json

Update package.json to look like this:

{
  "name": "context",
  "version": "0.0.1",
  "devDependencies": {
    "@angular/cli": "nrwl/fix-cli-build",
    "@nrwl/schematics": "nrwl/schematics-build"
  }
}

cd ../
./context/node_modules/.bin/ng new proj --collection=@nrwl/schematics
rm -rf context

Nrwl Workspace

The default layout generated by the CLI is good for small applications, but does not work that well for large enterprise apps, where many teams works on many apps composed of many shared libraries.

"Nrwl Workspace" is a set of schematics making the CLI more suitable for such applications. It creates a monorepo like experience on top of the CLI.

Create an Empty Workspace

Run ng new proj --collection=@nrwl/schematics, and you will see the following files created:

.angular-cli.json
tslint.json
test.js
tsconfig.json
tsconfig.app.json
tsconfig.spec.json
tsconfig.e2e.json
apps/
libs/

It's similar to the standard CLI projects with a few changes:

• We have the apps dir where all applications are placed
• We have the libs dir where all libraries are placed
• Some files have moved to the root: tsconfigs, test.js, so all apps and libs share them.

Create an App

Run schematics @nrwl/schematics:app --name=myapp, and you will see the following files created:

apps/myapp/src/main.ts
apps/myapp/src/app/app.module.ts
apps/myapp/src/app/app.component.ts
apps/myapp/e2e/app.po.ts

You can build/serve/test the app by passing the app name.

ng build --app=myapp

As with the standard CLI, running ng build without specifying an app will build the first app in .angular-cli.json.

Create a Lib

Run schematics @nrwl/schematics:lib --name=mylib, and you will see the following files created:

libs/mylib/src/mylib.ts
libs/mylib/src/mylib.spec.ts
libs/mylib/index.ts

If you run ng test, it will run the tests for the lib and for the app.

CLI only generates bundles. This means that you cannot build the lib itself. You can only do it by building an app that depends on it.

So if you update app.module.ts to contain:

import { MyLib } from 'mylib';

And then run ng build --app=myapp, it will build mylib and include it in the app's bundle.

Covert and Existing App into a Nx Workspace

If you have an existing CLI project, you can convert it into an Nx Workspace like this.

First, make sure you have @nrwl/schematics installed. Either run:

yarn global add @nrwl/schematics

Or run the following in the project dir:

yarn add @nrwl/schematics

Now, run:

schematics @nrwl/schematics:convert-to-workspace

• Your project files will be moved under:apps/projectName
• Some files have moved to the root: tsconfigs, test.js, so all apps and libs share them.
• package.json and .angular-cli.json will be updated

NgRx

Root

Run schematics @nrwl/schematics:ngrx --module=src/app/app.module.ts --root, and you will see the following files created:

/src/app/+state/app.actions.ts
/src/app/+state/app.effects.ts
/src/app/+state/app.effects.spec.ts
/src/app/+state/app.init.ts
/src/app/+state/app.interfaces.ts
/src/app/+state/app.reducer.ts
/src/app/+state/app.reducer.spec.ts

Also, app.module.ts will have StoreModule.forRoot and EffectsModule.forRoot configured.

onlyEmptyRoot

Run schematics @nrwl/schematics:ngrx --module=src/app/app.module.ts --onlyEmptyRoot to only add the StoreModule.forRoot and EffectsModule.forRoot calls without generating any new files.

Feature

Run schematics @nrwl/schematics:ngrx --module=src/app/mymodule/mymodule.module.ts , and you will see the following files created:

/src/app/mymodule/+state/app.actions.ts
/src/app/mymodule/+state/app.effects.ts
/src/app/mymodule/+state/app.effects.spec.ts
/src/app/mymodule/+state/app.init.ts
/src/app/mymodule/+state/app.interfaces.ts
/src/app/mymodule/+state/app.reducer.ts
/src/app/mymodule/+state/app.reducer.spec.ts

Also, mymodule.module.ts will have StoreModule.forFeature and EffectsModule.forFeature configured.

onlyAddFiles

Add --onlyAddFiles to generate files without adding imports to the module.

upgrade-shell

Run schematics @nrwl/schematics:upgrade-shell --module=src/app/app.module.ts --angularJsImport=legacy --angularJsCmpSelector=rootLegacyCmp and you will see the following files created:

/src/app/legacy-setup.ts
/src/app/hybrid.spec.ts

legacy-setup.ts contains all the downgraded and upgraded components.

src/app/module.ts has been modified to bootstrap a hybrid app instead of AppComponent.

/src/app/hybrid.spec.ts contains the spec verifying that the hybrid application runs properly.

For simple scenarios, no modification is necessary in /src/app/legacy-setup.ts.

Open /src/app/hybrid.spec.ts to update the expectation in the test and run ng test. It should pass.