From 655aa7a7e39dbb6632ed268bbebc05335a3f9226 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leosvel=20P=C3=A9rez=20Espinosa?= Date: Tue, 11 Jul 2023 14:38:10 +0100 Subject: [PATCH] docs(js): add docs about @nx/js:tsc batch execution --- docs/generated/packages/js/executors/tsc.json | 2 +- docs/shared/incremental-builds.md | 22 +++++++++++++- packages/js/docs/tsc-examples.md | 30 +++++++++++++++++++ 3 files changed, 52 insertions(+), 2 deletions(-) diff --git a/docs/generated/packages/js/executors/tsc.json b/docs/generated/packages/js/executors/tsc.json index 61f9e1b61d88a6..4842f122725ce5 100644 --- a/docs/generated/packages/js/executors/tsc.json +++ b/docs/generated/packages/js/executors/tsc.json @@ -172,7 +172,7 @@ ] } }, - "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Using TypeScript Transformer Plugins\" %}\n\n`@nx/js:tsc` can run the [TypeScript Transformers](https://github.com/madou/typescript-transformer-handbook) by using the `transformers` option.\n\n```json {% fileName=\"libs/ts-lib/project.json\" %}\n{\n \"build\": {\n \"executor\": \"@nx/js:tsc\",\n \"options\": {\n \"outputPath\": \"dist/libs/ts-lib\",\n \"main\": \"libs/ts-lib/src/index.ts\",\n \"tsConfig\": \"libs/ts-lib/tsconfig.lib.json\",\n \"assets\": [\"libs/ts-lib/*.md\"],\n \"transformers\": [\n \"@nestjs/swagger/plugin\",\n {\n \"name\": \"@automapper/classes/transformer-plugin\",\n \"options\": {}\n }\n ]\n }\n }\n}\n```\n\n{% /tab %}\n{% tab label=\"Inline libraries\" %}\n\n`@nx/js:tsc` can inline non-buildable libraries by opt-in to **Inlining** mode with `external` option.\n\n```json {% fileName=\"libs/ts-lib/project.json\" %}\n{\n \"build\": {\n \"executor\": \"@nx/js:tsc\",\n \"options\": {\n \"outputPath\": \"dist/libs/ts-lib\",\n \"main\": \"libs/ts-lib/src/index.ts\",\n \"tsConfig\": \"libs/ts-lib/tsconfig.lib.json\",\n \"assets\": [\"libs/ts-lib/*.md\"],\n \"external\": \"all\"\n }\n }\n}\n```\n\n```shell\nnpx nx build ts-lib --external=all\n```\n\n`@nx/js:tsc` can also inline buildable libraries by setting `external: 'none'`\n\n```json {% fileName=\"libs/ts-lib/project.json\" %}\n{\n \"build\": {\n \"executor\": \"@nx/js:tsc\",\n \"options\": {\n \"outputPath\": \"dist/libs/ts-lib\",\n \"main\": \"libs/ts-lib/src/index.ts\",\n \"tsConfig\": \"libs/ts-lib/tsconfig.lib.json\",\n \"assets\": [\"libs/ts-lib/*.md\"],\n \"external\": \"none\"\n }\n }\n}\n```\n\n```shell\nnpx nx build ts-lib --external=none\n```\n\n{% /tab %}\n{% /tabs %}\n", + "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Using TypeScript Transformer Plugins\" %}\n\n`@nx/js:tsc` can run the [TypeScript Transformers](https://github.com/madou/typescript-transformer-handbook) by using the `transformers` option.\n\n```json {% fileName=\"libs/ts-lib/project.json\" %}\n{\n \"build\": {\n \"executor\": \"@nx/js:tsc\",\n \"options\": {\n \"outputPath\": \"dist/libs/ts-lib\",\n \"main\": \"libs/ts-lib/src/index.ts\",\n \"tsConfig\": \"libs/ts-lib/tsconfig.lib.json\",\n \"assets\": [\"libs/ts-lib/*.md\"],\n \"transformers\": [\n \"@nestjs/swagger/plugin\",\n {\n \"name\": \"@automapper/classes/transformer-plugin\",\n \"options\": {}\n }\n ]\n }\n }\n}\n```\n\n{% /tab %}\n{% tab label=\"Inline libraries\" %}\n\n`@nx/js:tsc` can inline non-buildable libraries by opt-in to **Inlining** mode with `external` option.\n\n```json {% fileName=\"libs/ts-lib/project.json\" %}\n{\n \"build\": {\n \"executor\": \"@nx/js:tsc\",\n \"options\": {\n \"outputPath\": \"dist/libs/ts-lib\",\n \"main\": \"libs/ts-lib/src/index.ts\",\n \"tsConfig\": \"libs/ts-lib/tsconfig.lib.json\",\n \"assets\": [\"libs/ts-lib/*.md\"],\n \"external\": \"all\"\n }\n }\n}\n```\n\n```shell\nnpx nx build ts-lib --external=all\n```\n\n`@nx/js:tsc` can also inline buildable libraries by setting `external: 'none'`\n\n```json {% fileName=\"libs/ts-lib/project.json\" %}\n{\n \"build\": {\n \"executor\": \"@nx/js:tsc\",\n \"options\": {\n \"outputPath\": \"dist/libs/ts-lib\",\n \"main\": \"libs/ts-lib/src/index.ts\",\n \"tsConfig\": \"libs/ts-lib/tsconfig.lib.json\",\n \"assets\": [\"libs/ts-lib/*.md\"],\n \"external\": \"none\"\n }\n }\n}\n```\n\n```shell\nnpx nx build ts-lib --external=none\n```\n\n{% /tab %}\n{% tab label=\"Batch mode execution\" %}\n\nThe `@nx/js:tsc` executor supports running multiple tasks in a single process. When running in batch mode, the executor uses the [TypeScript APIs for incremental builds](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript). This results in a much faster build time when compared to the default implementation (the bigger the task graph to run, the more the performance improvements).\n\n> **Note:** Executing tasks in batch mode is an experimental feature.\n\nTo run your builds using the batch implementation, set the `NX_BATCH_MODE` environment variable to `true`:\n\n```shell\nNX_BATCH_MODE=true nx build my-project\n```\n\nFor optimal performance, you could set the `clean` option to `false`. Otherwise, the executor cleans the output folder before running the build, which results in the loss of the [`.tsbuildinfo` file](https://www.typescriptlang.org/tsconfig/#tsBuildInfoFile) and, consequently, the loss of important optimizations performed by TypeScript. This is not a requirement. Even if the `clean` option is not set to `false` there are other important optimizations that are performed by the batch implementation.\n\n```json {% fileName=\"libs/ts-lib/project.json\" %}\n{\n \"build\": {\n \"executor\": \"@nx/js:tsc\",\n \"options\": {\n \"outputPath\": \"dist/libs/ts-lib\",\n \"main\": \"libs/ts-lib/src/index.ts\",\n \"tsConfig\": \"libs/ts-lib/tsconfig.lib.json\",\n \"assets\": [\"libs/ts-lib/*.md\"],\n \"clean\": false\n }\n }\n}\n```\n\n{% /tab %}\n{% /tabs %}\n", "presets": [] }, "description": "Build a project using TypeScript.", diff --git a/docs/shared/incremental-builds.md b/docs/shared/incremental-builds.md index 087017fc4ddf6f..f3263696508c71 100644 --- a/docs/shared/incremental-builds.md +++ b/docs/shared/incremental-builds.md @@ -66,7 +66,27 @@ The downsides of incremental builds: If you are only planning to use incremental builds to speed up your CI, then the watch mode concern is irrelevant, and the only thing you need to assess is whether the benefits of skipping the compilation outweigh the costs of initializing the TypeScript compiler several times. -## Custom Serve Target +## Use the `@nx/js:tsc` Batch Implementation + +{% callout type="check" title="Available since Nx 16.5.0" %} +The `@nx/js:tsc` batch implementation was introduced in Nx **16.5.0**. +{% /callout %} + +If you're using the `@nx/js:tsc` to build your projects, you can opt-in to use its batch implementation. The batch implementation uses the [TypeScript APIs for incremental builds](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript) and batches the execution of the tasks into a single process. This results in a much faster build time when compared to the default implementation (the bigger the task graph to run, the more the performance improvements). + +> **Note:** Executing tasks in batch mode is an experimental feature. + +To run your builds using the batch implementation, set the `NX_BATCH_MODE` environment variable to `true`: + +```shell +NX_BATCH_MODE=true nx build my-project +``` + +For optimal performance, you could set the `clean` option to `false`. Otherwise, the executor cleans the output folder before running the build, which results in the loss of the [`.tsbuildinfo` file](https://www.typescriptlang.org/tsconfig/#tsBuildInfoFile) and, consequently, the loss of important optimizations performed by TypeScript. This is not a requirement. Even if the `clean` option is not set to `false` there are other important optimizations that are performed by the batch implementation. + +You can get a sense of the performance improvements over using the `@nx/js:tsc` default implementation in the following example repository: https://github.com/nrwl/large-ts-monorepo. + +## Custom Serve Target with Webpack If you are implementing a custom serve command, you can use `WebpackNxBuildCoordinationPlugin` provided by `@nx/webpack`. It's a webpack plugin you can use to coordinate the compiling of the libs and the webpack linking. diff --git a/packages/js/docs/tsc-examples.md b/packages/js/docs/tsc-examples.md index 824e4a890d82c2..e5edabf5a09198 100644 --- a/packages/js/docs/tsc-examples.md +++ b/packages/js/docs/tsc-examples.md @@ -71,5 +71,35 @@ npx nx build ts-lib --external=all npx nx build ts-lib --external=none ``` +{% /tab %} +{% tab label="Batch mode execution" %} + +The `@nx/js:tsc` executor supports running multiple tasks in a single process. When running in batch mode, the executor uses the [TypeScript APIs for incremental builds](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript). This results in a much faster build time when compared to the default implementation (the bigger the task graph to run, the more the performance improvements). + +> **Note:** Executing tasks in batch mode is an experimental feature. + +To run your builds using the batch implementation, set the `NX_BATCH_MODE` environment variable to `true`: + +```shell +NX_BATCH_MODE=true nx build my-project +``` + +For optimal performance, you could set the `clean` option to `false`. Otherwise, the executor cleans the output folder before running the build, which results in the loss of the [`.tsbuildinfo` file](https://www.typescriptlang.org/tsconfig/#tsBuildInfoFile) and, consequently, the loss of important optimizations performed by TypeScript. This is not a requirement. Even if the `clean` option is not set to `false` there are other important optimizations that are performed by the batch implementation. + +```json {% fileName="libs/ts-lib/project.json" %} +{ + "build": { + "executor": "@nx/js:tsc", + "options": { + "outputPath": "dist/libs/ts-lib", + "main": "libs/ts-lib/src/index.ts", + "tsConfig": "libs/ts-lib/tsconfig.lib.json", + "assets": ["libs/ts-lib/*.md"], + "clean": false + } + } +} +``` + {% /tab %} {% /tabs %}