docs: add swc, devtools docs

Author: kamilmysliwiec

content/controllers.md

@@ -67,7 +67,7 @@ This method will return a 200 status code and the associated response, which in
 
 > warning **Warning** Nest detects when the handler is using either `@Res()` or `@Next()`, indicating you have chosen the library-specific option. If both approaches are used at the same time, the Standard approach is **automatically disabled** for this single route and will no longer work as expected. To use both approaches at the same time (for example, by injecting the response object to only set cookies/headers but still leave the rest to the framework), you must set the `passthrough` option to `true` in the `@Res({{ '{' }} passthrough: true {{ '}' }})` decorator.
 
-<app-banner-enterprise></app-banner-enterprise>
+<app-banner-devtools></app-banner-devtools>
 
 #### Request object
 

content/devtools/ci-cd.md

@@ -0,0 +1,226 @@
+### CI/CD integration
+
+> info **Hint** This chapter covers the Nest Devtools integration with the Nest framework. If you are looking for the Devtools application, please visit the [Devtools](https://devtools.nestjs.com) website.
+
+CI/CD integration is available for users with the **[Enterprise](/settings)** plan.
+
+#### Publishing graphs
+
+Let's first configure the application bootstrap file (`main.ts`) to use the `GraphPublisher` class (exported from the `@nestjs/devtools-integration` - see previous chapter for more details), as follows:
+
+```typescript
+async function bootstrap() {
+  const shouldPublishGraph = process.env.PUBLISH_GRAPH === "true";
+
+  const app = await NestFactory.create(AppModule, {
+    snapshot: true,
+    preview: shouldPublishGraph,
+  });
+
+  if (shouldPublishGraph) {
+    await app.init();
+
+    const publishOptions = { ... } // NOTE: this options object will vary depending on the CI/CD provider you're using
+    const graphPublisher = new GraphPublisher(app);
+    await graphPublisher.publish(publishOptions);
+
+    await app.close();
+  } else {
+    await app.listen(3000);
+  }
+}
+```
+
+As we can see, we're using the `GraphPublisher` here to publish our serialized graph to the centralized registry. The `PUBLISH_GRAPH` is a custom environment variable that will let us control whether the graph should be published (CI/CD workflow), or not (regular application bootstrap). Also, we set the `preview` attribute here to `true`. With this flag enabled, our application will bootstrap in the preview mode - which basically means that constructors (and lifecycle hooks) of all controllers, enhancers, and providers in our application will not be executed. Note - this isn't **required**, but makes things simpler for us since in this case we won't really have to connect to the database etc. when running our application in the CI/CD pipeline.
+
+The `publishOptions` object will vary depending on the CI/CD provider you're using. We will provide you with instructions for the most popular CI/CD providers below, in later sections.
+
+Once the graph is successfully published, you'll see the following output in your workflow view:
+
+<figure><img src="/assets/devtools/graph-published-terminal.png" /></figure>
+
+Every time our graph is published, we should see a new entry in the project's corresponding page:
+
+<figure><img src="/assets/devtools/project.png" /></figure>
+
+#### Reports
+
+Devtools generate a report for every build **IF** there's a corresponding snapshot already stored in the centralized registry. So for example, if you create a PR against the `master` branch for which the graph was already published - then the application will be able to detect differences and generate a report. Otherwise, the report will not be generated.
+
+To see reports, navigate to the project's corresponding page (see organizations).
+
+<figure><img src="/assets/devtools/report.png" /></figure>
+
+#### Build preview
+
+For every published graph we can go back in time and preview how it looked before by clicking at the **Preview** button. Furthermore, if the report was generated, we should see the differences higlighted on our graph:
+
+- green nodes represent added elements
+- light white nodes represent updated elements
+- red nodes represent deleted elements
+
+See screenshot below:
+
+<figure><img src="/assets/devtools/nodes-selection.png" /></figure>
+
+#### Integrations: Github Actions
+
+First let's start from creating a new Github workflow in the `.github/workflows` directory in our project and call it, for example, `publish-graph.yml`. Inside this file, let's use the following definition:
+
+```yaml
+name: Devtools
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - '*'
+
+jobs:
+  publish:
+    if: github.actor!= 'dependabot[bot]'
+    name: Publish graph
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+      - name: Setup Environment (PR)
+        if: {{ '${{' }} github.event_name == 'pull_request' {{ '}}' }}
+        shell: bash
+        run: |
+          echo "COMMIT_SHA={{ '${{' }} github.event.pull_request.head.sha {{ '}}' }}" >>\${GITHUB_ENV}
+      - name: Setup Environment (Push)
+        if: {{ '${{' }} github.event_name == 'push' {{ '}}' }}
+        shell: bash
+        run: |
+          echo "COMMIT_SHA=\${GITHUB_SHA}" >> \${GITHUB_ENV}
+      - name: Publish
+        run: PUBLISH_GRAPH=true npm run start
+        env:
+          DEVTOOLS_API_KEY: CHANGE_THIS_TO_YOUR_API_KEY
+          REPOSITORY_NAME: {{ '${{' }} github.event.repository.name {{ '}}' }}
+          BRANCH_NAME: {{ '${{' }} github.head_ref || github.ref_name {{ '}}' }}
+          TARGET_SHA: {{ '${{' }} github.event.pull_request.base.sha {{ '}}' }}
+```
+
+Ideally, `DEVTOOLS_API_KEY` environment variable should be retrieved from Github Secrets, read more [here](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) .
+
+This workflow will run per each pull request that's targeting the `master` branch OR in case there's a direct commit to the `master` branch. Feel free to align this configuration to whatever your project needs. What's essential here is that we provide necessary environment varaiables for our `GraphPublisher` class (to run).
+
+However, there's one variable that needs to be updated before we can start using this workflow - `DEVTOOLS_API_KEY`. We can generate an API key dedicated for our project on this **page** .
+
+Lastly, let's navigate to the `main.ts` file again and update the `publishOptions` object we previously left empty.
+
+```typescript
+const publishOptions = {
+  apiKey: process.env.DEVTOOLS_API_KEY,
+  repository: process.env.REPOSITORY_NAME,
+  owner: process.env.GITHUB_REPOSITORY_OWNER,
+  sha: process.env.COMMIT_SHA,
+  target: process.env.TARGET_SHA,
+  trigger: process.env.GITHUB_BASE_REF ? 'pull' : 'push',
+  branch: process.env.BRANCH_NAME,
+};
+```
+
+For the best developer experience, make sure to integrate the **Github application** for your project by clicking on the "Integrate Github app" button (see screenshot below). Note - this isn't required.
+
+<figure><img src="/assets/devtools/integrate-github-app.png" /></figure>
+
+With this integration, you'll be able to see the status of the preview/report generation process right in your pull request:
+
+<figure><img src="/assets/devtools/actions-preview.png" /></figure>
+
+#### Integrations: Gitlab Pipelines
+
+First let's start from creating a new Gitlab CI configuration file in the root directory of our project and call it, for example, `.gitlab-ci.yml`. Inside this file, let's use the following definition:
+
+```typescript
+const publishOptions = {
+  apiKey: process.env.DEVTOOLS_API_KEY,
+  repository: process.env.REPOSITORY_NAME,
+  owner: process.env.GITHUB_REPOSITORY_OWNER,
+  sha: process.env.COMMIT_SHA,
+  target: process.env.TARGET_SHA,
+  trigger: process.env.GITHUB_BASE_REF ? 'pull' : 'push',
+  branch: process.env.BRANCH_NAME,
+};
+```
+
+> info **Hint** Ideally, `DEVTOOLS_API_KEY` environment variable should be retrieved from secrets.
+
+This workflow will run per each pull request that's targeting the `master` branch OR in case there's a direct commit to the `master` branch. Feel free to align this configuration to whatever your project needs. What's essential here is that we provide necessary environment variables for our `GraphPublisher` class (to run).
+
+However, there's one variable (in this workflow definition) that needs to be updated before we can start using this workflow - `DEVTOOLS_API_KEY`. We can generate an API key dedicated for our project on this **page** .
+
+Lastly, let's navigate to the `main.ts` file again and update the `publishOptions` object we previously left empty.
+
+```yaml
+image: node:16
+
+stages:
+  - build
+
+cache:
+  key:
+    files:
+      - package-lock.json
+  paths:
+    - node_modules/
+
+workflow:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: always
+    - if: $CI_COMMIT_BRANCH == "master" && $CI_PIPELINE_SOURCE == "push"
+      when: always
+    - when: never
+
+install_dependencies:
+  stage: build
+  script:
+    - npm ci
+
+publish_graph:
+  stage: build
+  needs:
+    - install_dependencies
+  script: npm run start
+  variables:
+    PUBLISH_GRAPH: 'true'
+    DEVTOOLS_API_KEY: 'CHANGE_THIS_TO_YOUR_API_KEY'
+```
+
+#### Other CI/CD tools
+
+Nest Devtools CI/CD integration can be used with any CI/CD tool of your choice (e.g., [Bitbucket Pipelines](https://bitbucket.org/product/features/pipelines) , [CircleCI](https://circleci.com/), etc) so don't feel limited to providers we described here.
+
+Look at the following `publishOptions` object configuration to understand what information is required to publish the graph for a given commit/build/PR.
+
+```typescript
+const publishOptions = {
+  apiKey: process.env.DEVTOOLS_API_KEY,
+  repository: process.env.CI_PROJECT_NAME,
+  owner: process.env.CI_PROJECT_ROOT_NAMESPACE,
+  sha: process.env.CI_COMMIT_SHA,
+  target: process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA,
+  trigger: process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA ? 'pull' : 'push',
+  branch:
+    process.env.CI_COMMIT_BRANCH ??
+    process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME,
+};
+```
+
+Most of this information is provided through CI/CD built-in environment variables (see [CircleCI built-in environment list](https://circleci.com/docs/variables/#built-in-environment-variables) and [Bitbucket variables](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/) ).
+
+When it comes to the pipeline configuration for publishing graphs, we recommend using the following triggers:
+
+- `push` event - only if the current branch represents a deployment environment, for example `master`, `main`, `staging`, `production`, etc.
+- `pull request` event - always, or when the **target branch** represents a deployment environment (see above)

content/devtools/overview.md

@@ -0,0 +1,101 @@
+### Overview
+
+> info **Hint** This chapter covers the Nest Devtools integration with the Nest framework. If you are looking for the Devtools application, please visit the [Devtools](https://devtools.nestjs.com) website.
+
+To start debugging your local application, open up the `main.ts` file and make sure to set the `snapshot` attribute to `true` in the application options object, as follows:
+
+```typescript
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, {
+    snapshot: true,
+  });
+  await app.listen(3000);
+}
+```
+
+This will instruct the framework to collect necessary metadata that will let Nest Devtools visualize your application's graph.
+
+Next up, let's install the required dependency:
+
+```bash
+$ npm i @nestjs/devtools-integration
+```
+
+> warning **Warning** If you're using `@nestjs/graphql` package in your application, make sure to install the upcoming `next` version (`npm i @nestjs/graphql@next`).
+
+With this dependency in place, let's open up the `app.module.ts` file and import the `DevtoolsModule` that we just installed:
+
+```typescript
+@Module({
+  imports: [
+    DevtoolsModule.register({
+      http: process.env.NODE_ENV !== 'production',
+    }),
+  ],
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule {}
+```
+
+> warning **Warning** The reason we are checking the `NODE_ENV` environment variable here is that you should never use this module in production!
+
+Once the `DevtoolsModule` is imported and your application is up and running (`npm run start:dev`), you should be able to navigate to [Devtools](https://devtools.nestjs.com) URL and see the instrospected graph.
+
+<figure><img src="/assets/devtools/modules-graph.png" /></figure>
+
+So as we can see, `DevtoolsModule` makes your application expose an additional HTTP server (on port 8000) that the Devtools application will use to introspect your app.
+
+Just to double-check that everything works as expected, change the graph view to "Classes". You should see the following screen:
+
+<figure><img src="/assets/devtools/classes-graph.png" /></figure>
+
+To focus on a specific node, click on the rectangle and the graph will show a popup window with the **"Focus"** button. You can also use the search bar (located in the sidebar) to find a specific node.
+
+> info **Hint** If you click on the **Inspect** button, application will take you to the `/debug` page with that specific node selected.
+
+<figure><img src="/assets/devtools/node-popup.png" /></figure>
+
+Using the form controls located in the sidebar (on the left), you can control edges proximity to, for example, visualize a specific application sub-tree:
+
+<figure><img src="/assets/devtools/subtree-view.png" /></figure>
+
+#### Routes explorer
+
+When you navigate to the **Routes explorer** page, you should see all of the registered entrypoints:
+
+<figure><img src="/assets/devtools/routes.png" /></figure>
+
+#### Sandbox
+
+To execute JavaScript code on the fly & interact with your application in real-time, navigate to the **Sandbox** page:
+
+<figure><img src="/assets/devtools/sandbox.png" /></figure>
+
+#### Bootstrap performance analyzer
+
+To see a list of all class nodes (controllers, providers, enhancers, etc.) and their corresponding instantiation times, navigate to the **Bootstrap performance** page:
+
+<figure><img src="/assets/devtools/bootstrap-performance.png" /></figure>
+
+#### Audit
+
+To see the auto-generated audit - errors/warnings/hints that the application came up with while analyzing your serialized graph, navigate to the **
+Audit** page:
+
+<figure><img src="/assets/devtools/audit.png" /></figure>
+
+#### Preview static files
+
+To save a serialized graph to a file, use the following code:
+
+```typescript
+await app.listen(3000); // OR await app.init()
+writeFileSync('./graph.json', app.get(SerializedGraph).toString());
+```
+
+> info **Hint** `SerializedGraph` is exported from the `@nestjs/core` package.
+
+Then you can drag and drop this/upload this file:
+
+<figure><img src="/assets/devtools/drag-and-drop.png" /></figure>

content/interceptors.md

@@ -28,7 +28,7 @@ This approach means that the `intercept()` method effectively **wraps** the requ
 
 Consider, for example, an incoming `POST /cats` request. This request is destined for the `create()` handler defined inside the `CatsController`. If an interceptor which does not call the `handle()` method is called anywhere along the way, the `create()` method won't be executed. Once `handle()` is called (and its `Observable` has been returned), the `create()` handler will be triggered. And once the response stream is received via the `Observable`, additional operations can be performed on the stream, and a final result returned to the caller.
 
-<app-banner-shop></app-banner-shop>
+<app-banner-devtools></app-banner-devtools>
 
 #### Aspect interception
 

content/modules.md

@@ -99,7 +99,7 @@ export class CatsModule {}
 
 Now any module that imports the `CatsModule` has access to the `CatsService` and will share the same instance with all other modules that import it as well.
 
-<app-banner-enterprise></app-banner-enterprise>
+<app-banner-devtools></app-banner-devtools>
 
 #### Module re-exporting