docs(guides): updates getting-started guides
This commit is contained in:
Victor Savkin
parent
a672a6df49
commit
ae0ad6d859
@ -1,36 +0,0 @@
|
||||
# Creating an Nx Workspace
|
||||
|
||||
A workspace contains your Angular application (or applications) and any
|
||||
supporting libraries you create.
|
||||
**It is a monorepo for your application domain.**
|
||||
|
||||
With Angular CLI you can add different types of projects to a single
|
||||
workspace (by default you can add applications and libraries).
|
||||
This is great, but is not sufficient to enable the monorepo-style development.
|
||||
Nx adds an extra layer of tooling to make this possible.
|
||||
|
||||
The `@nrwl/schematics` library contains a binary script that provides
|
||||
the command `create-nx-workspace`. That command can be used to create a
|
||||
new Nx Workspace:
|
||||
|
||||
```bash
|
||||
create-nx-workspace myworkspacename
|
||||
```
|
||||
|
||||
This will create a new Nx Workspace using a sandboxed environment...
|
||||
running the Angular CLI `ng new` command under the hood and using
|
||||
the Nx schematics collection.
|
||||
|
||||
> Note: You can use `ng new` if you like, but it relies on globally
|
||||
> installed npm packages. And we know that those can be messy.
|
||||
> If your globally installed npm packages are in a bad shape,
|
||||
> use the `create-nx-workspace` command.
|
||||
|
||||
## Add to an Existing Angular CLI workspace
|
||||
|
||||
If you already started your project with the Angular CLI, you can also
|
||||
add Nx capabilities by running:
|
||||
|
||||
```bash
|
||||
ng add @nrwl/schematics
|
||||
```
|
||||
BIN
docs/getting-started/create-workspace.gif
Normal file
BIN
docs/getting-started/create-workspace.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.8 MiB |
BIN
docs/getting-started/dep-graph.png
Normal file
BIN
docs/getting-started/dep-graph.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 134 KiB |
117
docs/getting-started/getting-started.md
Normal file
117
docs/getting-started/getting-started.md
Normal file
@ -0,0 +1,117 @@
|
||||
# Getting Started
|
||||
|
||||
<iframe src="https://player.vimeo.com/video/237418773" width="100%" height="360" frameborder="0" allowfullscreen></iframe>
|
||||
|
||||
## Installing Nx
|
||||
|
||||
Nx is just a set of power-ups for Angular CLI, **so an Nx workspace is an Angular CLI workspace**. This means that it will be handy to have the Angular CLI installed globally, which can be done via npm or yarn as well.
|
||||
|
||||
```bash
|
||||
npm install -g @angular/cli
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
yarn global add @angular/cli
|
||||
```
|
||||
|
||||
> Note: If you do not have the Angular CLI installed globally you may not be able to use ng from the terminal to run CLI commands within the project. But the `package.json` file comes with npm scripts to run ng commands, so you can run npm start to ng serve and you can run `npm run ng <command>` to run any of the ng commands.
|
||||
|
||||
After you have installed the Angular CLI, install `@nrwl/schematics`.
|
||||
|
||||
```bash
|
||||
npm install -g @nrwl/schematics
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
yarn global add @nrwl/schematics
|
||||
```
|
||||
|
||||
> If you want to work with the version still in development you can use `@nrwl/schematics@next` as the package to install.
|
||||
|
||||
|
||||
## Nx Workspace
|
||||
|
||||
### Creating an Nx Workspace
|
||||
|
||||
To create an Nx workspace, run:
|
||||
|
||||
```bash
|
||||
ng new myworkspace --collection=@nrw/schematics
|
||||
```
|
||||
|
||||
The `ng new` command uses globally-installed packages. Anything installed globally can be in a messy state. If you have any problems running the command above, you can also run:
|
||||
|
||||
```bash
|
||||
create-nx-workspace myworkspacename
|
||||
```
|
||||
|
||||
This command still runs `ng new` under the hood, but it does it in a sandboxed environment, and, as a result, never fails.
|
||||
|
||||
|
||||
### Adding to an Existing Angular CLI workspace
|
||||
|
||||
If you already have a regular Angular CLI project, you can add Nx power-ups by running:
|
||||
|
||||
```bash
|
||||
ng add @nrwl/schematics
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Creating First Application
|
||||
|
||||
Unlike the CLI, an Nx workspace starts blank. There are no applications to build, serve, and test. To create one run:
|
||||
|
||||
```bash
|
||||
ng g application myapp
|
||||
```
|
||||
|
||||
The result will look like this:
|
||||
|
||||
```
|
||||
apps/
|
||||
myapp/
|
||||
src/
|
||||
app/
|
||||
assets/
|
||||
environment/
|
||||
favicon.ico
|
||||
index.html
|
||||
main.ts
|
||||
polyfills.ts
|
||||
styles.css
|
||||
tsconfig.json
|
||||
tsconfig.app.json
|
||||
tsconfig.spec.json
|
||||
tslint.json
|
||||
myapp-e2e/
|
||||
src/
|
||||
tsconfig.json
|
||||
tsconfig.e2e.json
|
||||
tslint.json
|
||||
libs/
|
||||
tools/
|
||||
package.json
|
||||
tsconfig.json
|
||||
tslint.json
|
||||
angular.json
|
||||
nx.json
|
||||
```
|
||||
|
||||
All the files that the CLI would have in a new project are still here, just in a different folder structure which makes it easier to create more apps and libs in the future.
|
||||
|
||||
|
||||
## Serving Application
|
||||
|
||||
Run `ng serve myapp` to serve the newly generated application!
|
||||
|
||||
|
||||
## Use Angular Console
|
||||
|
||||
You can also create a new Nx project using Angular Console--UI for the CLI:
|
||||
|
||||
|
||||
@ -1,45 +0,0 @@
|
||||
# Installation
|
||||
|
||||
<iframe src="https://player.vimeo.com/video/237418773" width="100%" height="360" frameborder="0" allowfullscreen></iframe>
|
||||
|
||||
Nrwl Extensions, or **Nx** for short, is **an extension for the the Angular CLI implementing the monorepo-style development**. It is also **a collection of runtime libraries, linters, and code generators** helping large teams build better with Angular. It is made up of the following packages:
|
||||
|
||||
- **@nrwl/schematics**:Code generators and command-line tools (this is a dev dependency)
|
||||
- **@nrwl/nx**: Helpers and utilities that can be used by your application (this is a runtime dependency)
|
||||
|
||||
Both of these packages are included when creating an Nx Workspace.
|
||||
|
||||
Nx has two tags for available versions:
|
||||
|
||||
- **latest** (current stable version)
|
||||
- **next** (still in development but close!)
|
||||
|
||||
## Installing Nx
|
||||
|
||||
An Nx workspace is an Angular CLI project that has been enhanced to be enterprise ready. Being an Angular CLI project means it will be handy to have the Angular CLI installed globally, which can be done via npm or yarn as well.
|
||||
|
||||
```bash
|
||||
npm install -g @angular/cli
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
yarn global add @angular/cli
|
||||
```
|
||||
|
||||
> Note: If you do not have the Angular CLI installed globally you may not be able to use ng from the terminal to run CLI commands within the project. But the `package.json` file comes with npm scripts to run ng commands, so you can run npm start to ng serve and you can run `npm run ng <command>` to run any of the ng commands.
|
||||
|
||||
After you have installed the Angular CLI, install `@nrwl/schematics`.
|
||||
|
||||
```bash
|
||||
npm install -g @nrwl/schematics
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
yarn global add @nrwl/schematics
|
||||
```
|
||||
|
||||
> If you want to work with the version still in development you can use `@nrwl/schematics@next` as the package to install.
|
||||
BIN
docs/getting-started/lint-error.png
Normal file
BIN
docs/getting-started/lint-error.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 228 KiB |
176
docs/getting-started/nx-and-cli.md
Normal file
176
docs/getting-started/nx-and-cli.md
Normal file
@ -0,0 +1,176 @@
|
||||
# Nx and Angular CLI
|
||||
|
||||
Nx **is not** a replacement for Angular CLI. It's a collection of Angular CLI power-ups (schematics and builders) that transform the CLI into a powerful tool for full-stack development.
|
||||
|
||||
* **An Nx workspace is an Angular CLI workspace.**
|
||||
* You run same `ng build`, `ng serve` commands.
|
||||
* You configure your projects in `angular.json`.
|
||||
* Anything you can do in a standard Angular CLI project, you can also do in an Nx workspace.
|
||||
|
||||
|
||||
## How?
|
||||
|
||||
Angular CLI is extensible. Nx extends what the CLI generates (schematics) and how the CLI runs commands (builders).
|
||||
|
||||
What does Nx add?
|
||||
|
||||
|
||||
|
||||
## Full-Stack Development
|
||||
|
||||
With Nx, you can build a backend application next to your Angular application in the same repository. The backend and the frontend can share code. You can connect them to enable a fantastic development experience.
|
||||
|
||||
*How do you do it?*
|
||||
|
||||
First, generate a node application.
|
||||
|
||||
```bash
|
||||
ng g node-application backend
|
||||
```
|
||||
|
||||
The command will use NestJS by default. If you prefer Express or you want to build your backend from scratch, pass `--framework=express` or `--framework=none`.
|
||||
|
||||
Second, generate an Angular application.
|
||||
|
||||
```bash
|
||||
ng g application frontend
|
||||
```
|
||||
|
||||
Now, add the right proxy configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"/graphql": {
|
||||
"target": "http://localhost:3333",
|
||||
"secure": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Finally, you can run `ng serve backend` and `ng serve frontend`. There is a lot more to full-stack development in Nx, which we will cover the the guides.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Use effective development practices pioneered at Google
|
||||
|
||||
Using Nx, you can implement monorepo-style development--an approach popularized by Google and used by many tech companies today (Facebook, Uber, Twitter, etc..).
|
||||
|
||||
*Doesn't Angular CLI support having multiple projects in the same workspace?*
|
||||
|
||||
Yes, starting with Angular CLI 6 you can add different types of projects to a single workspace (by default you can add applications and libraries). This is great, but is not sufficient to enable the monorepo-style development. Nx adds an extra layer of tooling to make this possible.
|
||||
|
||||
### Analyzing and Visualizing the Dependency Graph
|
||||
|
||||
To be able to support the monorepo-style development, the tools must know how different projects in your workspace depend on each other. Nx uses advanced code analysis to build this dependency graph. Run `yarn dep-graph` to see the dependency diagram of your workspace.
|
||||
|
||||
|
||||
|
||||
|
||||
### Imposing Constraints on the Dependency Graph
|
||||
|
||||
If you partition your code into well-defined cohesive units, even a small organization will end up with a dozen apps and dozens or hundreds of libs. If all of them can depend on each other freely, chaos will ensue and the workspace will become unmanageable.
|
||||
|
||||
To help with that Nx uses code analyses to make sure projects can only depend on each other’s well-defined public API. It also allows you to declaratively impose constraints on how projects can depend on each other.
|
||||
|
||||
For instance, with this configuration, when we import private client code from the admin part of our repo, we will get an error.
|
||||
|
||||
```
|
||||
"nx-enforce-module-boundaries": [
|
||||
true,
|
||||
{
|
||||
"allow": [],
|
||||
"depConstraints": [
|
||||
{
|
||||
"sourceTag": "shared",
|
||||
"onlyDependOnLibsWithTags": ["shared"]
|
||||
},
|
||||
{
|
||||
"sourceTag": "admin",
|
||||
"onlyDependOnLibsWithTags": ["shared", "admin" ]
|
||||
},
|
||||
{
|
||||
"sourceTag": "client",
|
||||
"onlyDependOnLibsWithTags": ["shared", "client" ]
|
||||
},
|
||||
{
|
||||
"sourceTag": "*",
|
||||
"onlyDependOnLibsWithTags": ["*"]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
### Rebuilding and Retesting What is Affected
|
||||
|
||||
To be productive in a monorepo, you need to be able to check that your change is safe, and rebuilding and retesting everything on every change won’t scale. Nx uses code analysis to determine what needs to be rebuilt and retested.
|
||||
|
||||
```
|
||||
yarn affected:build --base=master # reruns build for all the projects affected by a PR
|
||||
|
||||
yarn affected:test --base=master # reruns unit tests for all the projects affected by a PR
|
||||
|
||||
yarn affected:e2e --base=master # reruns e2e tests for all the projects affected by a PR
|
||||
```
|
||||
|
||||
Nx will topologically sort the projects, and will run what it can in parallel.
|
||||
|
||||
|
||||
### Angular CLI = Code Collocation, Nx = Monorepo
|
||||
|
||||
Imagine you have a regular Angular CLI workspace containing tens projects, where each project has its own suite of e2e tests. The CLI doesnt't know how the projects depend on each other, so the only way for you to make sure your PR works is to rebuild and retest all ten projects. This isn't great.
|
||||
|
||||
First, this makes the CI expensive--10 times more expensive in the worse case scenario. Second, e2e tests can be flaky. If you always rerun all the tests in the repo, some tests will be bound to fail for the reasons unrelated to your change.
|
||||
|
||||
> Only the projects affected by your PR should be rebuilt and retested.
|
||||
|
||||
This is a hard requirement for monorepo-style development. Nx implements it.
|
||||
|
||||
|
||||
### Automation
|
||||
|
||||
In addition to using the monorepo, Google is also know for its use of automation. Nx adds powerful capabilities helping your team promote best practices and ensure consistency.
|
||||
|
||||
|
||||
## Use Innovative Tools
|
||||
|
||||
Tools like Apollo, Cypress, Jest, Prettier, and NestJS have gained a lot of popularity.
|
||||
|
||||
It's not the case that Apollo is always better than REST or Cypress is always better than Protractor. There are tradeoffs. But in many situations, for many projects, these innovative tools offer a lot of advantages.
|
||||
|
||||
Adding these tools to the dev workflow is challenging in a regular CLI project. The choice you have is not between Protractor or Cypress, but between a hacked-up setup for Cypress and a great CLI setup for Protractor. Nx changes that!
|
||||
|
||||
When using Nx, adding Cypress or Jest is easy:
|
||||
|
||||
```
|
||||
ng g application myapp --e2eTestRunner=cypress --unitTestRunner=jest
|
||||
```
|
||||
|
||||
Tests can then be run just like you would run them normally:
|
||||
|
||||
```
|
||||
ng test myapp
|
||||
ng e2e myapp
|
||||
```
|
||||
|
||||
## Summarize
|
||||
|
||||
Nx is not a replacement for the CLI. It's a set of Angular CLI power-ups.
|
||||
|
||||
With Nx, you can:
|
||||
|
||||
* Do everything you can do using the CLI
|
||||
* Build full-stack applications using Angular and NestJS
|
||||
* Use scalable development practices such as monorepos
|
||||
* Use innovative tools like Cypress and Jest
|
||||
|
||||
|
||||
### A la carte
|
||||
|
||||
Most importantly, you can use these power-ups a la carte. Just want to build a single Angular application using Cypress? Nx is still an excellent choice for that.
|
||||
|
||||
@ -1,15 +1,27 @@
|
||||
# Nx documentation
|
||||
# Nx
|
||||
|
||||
Welcome to the **Nx** documentation. Nx is an **open source toolkit for enterprise Angular applications** created by [Nrwl](https://nrwl.io), that helps you build professional grade application that are reliable and scalable. Here we cover everything about the product and explains how to work with it.
|
||||
Nx is a set of Angular CLI power-ups that transform the CLI into a powerful tool for full-stack development.
|
||||
|
||||
With Nx, you can:
|
||||
|
||||
* Build full-stack applications using Angular and NestJS
|
||||
* Use effective development practices pioneered at Google
|
||||
* Use innovative tools like Cypress and Jest
|
||||
|
||||
## Getting Started
|
||||
|
||||
To get you started, you might find some of these links relevant:
|
||||
- New to Nx? Have a look at the [Getting Started](getting-started.md) guide.
|
||||
- [How does Nx compare to the off-the-shelf Angular CLI?](nx-and-cli.md)
|
||||
|
||||
## Learn Nx
|
||||
|
||||
- [How does Nx help you build like Google?](nx-and-cli.md)
|
||||
- [How does Nx help you modernize your dev workflow?](nx-and-cli.md)
|
||||
- [API docs](apidocs.md)
|
||||
|
||||
## Community
|
||||
- [Books, talks, and blog posts about Nx](resources.md)
|
||||
|
||||
- New to Nx? Have a look at the [Getting Started](installation.md);
|
||||
- The main documentation is [this way](../documentations/applications.md);
|
||||
- Want to understand the concepts behind Nx? Check the [Fundamentals section](../fundamentals/concepts.md);
|
||||
- Looking for specific guidance see the [Guide section](../guides/different-types-of-libs.md).
|
||||
|
||||
## Contributing
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user