From 1ec7244c6abae84e63614eecbf5843f6225ebedb Mon Sep 17 00:00:00 2001 From: Chau Tran Date: Tue, 15 Feb 2022 07:59:12 -0600 Subject: [PATCH] docs(nest): update Nest plugin overview (#8903) * docs(nest): update Nest plugin overview * docs(nest): add back application proxies Co-authored-by: Chau Tran --- docs/shared/nest-plugin.md | 258 +++++++++++++++---------------------- 1 file changed, 106 insertions(+), 152 deletions(-) diff --git a/docs/shared/nest-plugin.md b/docs/shared/nest-plugin.md index e75fa3735e..4291bafb24 100644 --- a/docs/shared/nest-plugin.md +++ b/docs/shared/nest-plugin.md @@ -11,189 +11,143 @@ Nest.js is a framework designed for building scalable server-side applications. Many conventions and best practices used in Angular applications can be also be used in Nest. -## Installing the Nest Plugin +## Setting Up Nest -Installing the Nest plugin to a workspace can be done with the following: +To create a new workspace with Nest, run the following command: -```bash -yarn add -D @nrwl/nest +```shell +npx create-nx-workspace my-workspace --preset=nest ``` -```bash +Yarn users can use the following command instead: + +```shell +yarn create nx-workspace my-workspace --preset=nest +``` + +To add the Nest plugin to an existing workspace, run one the following commands: + +```shell npm install -D @nrwl/nest ``` -## Applications - -Generating new applications can be done with the following: - -```bash -nx generate @nrwl/nest:application +```shell +yarn add -D @nrwl/nest ``` -This creates the following app structure: +### Create Applications -```treeview -my-org/ -├── apps/ - └── nest-app/ - ├── jest.config.js - ├── src/ - │ ├── app/ - │ │ ├── app.controller.ts - │ │ ├── app.controller.spec.ts - │ │ ├── app.module.ts - │ │ ├── app.service.ts - │ │ └── app.service.spec.ts - │ ├── assets/ - │ ├── environments/ - │ └── main.ts - ├── tsconfig.app.json - ├── tsconfig.json - ├── tsconfig.spec.json - └── tslint.json -``` +You can add a new Nest application with the following command: -The `main.ts` content should look similar to this: - -```typescript -import { NestFactory } from '@nestjs/core'; - -import { AppModule } from './app/app.module'; - -async function bootstrap() { - const app = await NestFactory.create(AppModule); - const globalPrefix = 'api'; - app.setGlobalPrefix(globalPrefix); - const port = process.env.port || 3333; - await app.listen(port, () => { - console.log('Listening at http://localhost:' + port + '/' + globalPrefix); - }); -} - -bootstrap(); +```shell +nx g @nrwl/nest:app my-nest-app ``` #### Application Proxies Generating Nest applications has an option to configure other projects in the workspace to proxy API requests. This can be done by passing the `--frontendProject` with the project name you wish to enable proxy support for. -```bash -nx generate @nrwl/nest:application --frontendProject my-angular-app +```shell +nx g @nrwl/nest:app my-nest-app --frontendProject my-angular-app ``` -### Application commands +### Create Libraries -When a Nest application is added, the following architect commands are available for execution: +You can add a new Nest library with the following command: -#### build - -```bash -nx build +```shell +nx g @nrwl/nest:lib my-nest-lib ``` -The build command will compile the application using Webpack. It supports a production configuration by building with the following command: +To make the library `buildable`, use the following command: -```bash -nx build --configuration=production +```shell +nx g @nrwl/nest:lib my-nest-lib --buildable ``` -Additional configurations can be added in the project.json. Changing the `--configuration` flag with the new configuration name will run that config. +To make the library `publishable`, use the following command: -#### serve - -```bash -nx serve +```shell +nx g @nrwl/nest:lib my-nest-lib --publishable --importPath=@my-workspace/my-nest-lib ``` -The serve command runs the `build` target, and executes the application. +> Read more about [building and publishing libraries here](/structure/buildable-and-publishable-libraries). -By default, the serve command will run in watch mode. This allows code to be changed, and the Nest application to be rebuilt automatically. -Nest applications also have the `inspect` flag set, so you can attach your debugger to the running instance. - -##### Debugging - -Debugging is set to use a random port that is available on the system. The port can be changed by setting the port option in the `serve` architect in the project.json. Or by running the serve command with `--port `. - -For additional information on how to debug Node applications, see the [Node.js debugging getting started guide](https://nestjs.org/en/docs/guides/debugging-getting-started/#inspector-clients). - -##### Waiting for other builds - -Setting the `waitUntilTargets` option with an array of projects (with the following format: `"project:architect"`) will execute those commands before serving the Nest application. - -#### lint - -The lint command will run linting within the scope of the Nest app. - -```bash -nx lint -``` - -#### test - -Test will execute Jest tests within the scope of the Nest app. - -```bash -nx test -``` - -## Libraries - -Nest libraries are a good way to separate features within your organization. To create a Nest library run the following command: - -```bash -nx generate @nrwl/nest:library -``` - -Nest libraries can also be generated with an included controller, service or making the module global with their respective flags. - -```bash -nx generate @nrwl/nest:library [--controller] [--service] [--global] - -``` - -#### Buildable libraries - -Libraries can also be enabled to be built separately from apps. To create a buildable library, add the `--buildable` flag to the generate command above. - -```bash -nx generate @nrwl/nest:library --buildable -``` - -### Library commands - -When a Nest library is added, the following architect commands are available for execution: - -#### lint - -The lint command will run linting within the scope of the Nest library. - -```bash -nx lint -``` - -#### test - -Test will execute Jest tests within the scope of the Nest library. - -```bash -nx test -``` - -> Note: By default, Nest libraries are generated with Jest's test environment set to `node` - -#### build - -The build command will only be available if the library was generated with the `--buildable` flag. - -Buildable Nest libraries use TypeScript to compile the source. The tsconfig files that are generated with the library allow customization of the compiled output. - -```bash -nx build -``` - -## Nest Generators +### Nest Generators The Nest plugin for Nx extends the generators provided by Nest. Any commands that can be used with the Nest CLI can also be used with the `nx` command. The `--sourceRoot` flag should be used for all Nest generators. > The `--sourceRoot` command should point to the source directory of a Nest library or application within an Nx workspace. + +## Using Nest + +### Build + +You can build an application with the following command: + +```shell +nx build my-nest-app +``` + +This applies to `buildable` libraries as well + +```shell +nx build my-nest-lib +``` + +#### Waiting for other builds + +Setting the `waitUntilTargets` option with an array of projects (with the following format: `"project:architect"`) will execute those commands before serving the Nest application. + +### Serve + +You can serve an application with the following command: + +```shell +nx serve my-nest-app +``` + +The `serve` command runs the `build` target, and executes the application. + +By default, the serve command will run in `watch` mode. This allows code to be changed, and the Nest application to be rebuilt automatically. + +#### Debugging + +Nest applications also have the `inspect` flag set, so you can attach your debugger to the running instance. + +Debugging is set to use a random port that is available on the system. The port can be changed by setting the port option in the `serve` architect in the workspace.json. Or by running the serve command with `--port `. + +For additional information on how to debug Node applications, see the [Node.js debugging getting started guide](https://nestjs.org/en/docs/guides/debugging-getting-started/#inspector-clients). + +### Lint + +You can lint an application with the following command: + +```shell +nx lint my-nest-app +``` + +You can lint a library with the following command: + +```shell +nx lint my-nest-lib +``` + +### Unit Test + +You can run unit test for an application with the following command: + +```shell +nx test my-nest-app +``` + +You can run unit test for a library with the following command: + +```shell +nx test my-nest-lib +``` + +## More Documentation + +- [Todo Tutorial](/node-tutorial/01-create-application) +- [Using Jest](/jest/overview)