diff --git a/pages/heft/architecture.md b/pages/heft/architecture.md index 5747aefcc..cee48a911 100644 --- a/pages/heft/architecture.md +++ b/pages/heft/architecture.md @@ -7,11 +7,11 @@ navigation_source: docs_nav ## Terminology Heft's operation is organized around the following concepts: -- **action** - a Heft command-line name (as formalized by Rush Stack's [ts-command-line](https://www.npmjs.com/package/@rushstack/ts-command-line) system). For example, the "test" action appears in the `heft test --clean` command. Actions are the user interface, essentially macros tailored for typical developer activities. +- **action** - a Heft command-line verb (as formalized by Rush Stack's [ts-command-line](https://www.npmjs.com/package/@rushstack/ts-command-line) system). For example, the "test" action appears in the `heft test --clean` command. Actions are the user interface, essentially macros tailored for typical developer activities. - **plugin** - a TypeScript class that implements the `IHeftPlugin` contract to provide arbitrary functionality. Plugins are loaded optionally based on Heft's configuration. You can create your own NPM package that exports custom plugins for Heft to use. See [Core Plugins]({% link pages/heft/core_plugins.md %}) for a list of the built-in plugins. - **hook** - Heft leverages Webpack's [tapable](https://www.npmjs.com/package/tapable) system for enabling plugins to register handlers for various events during the build. - **task** - a Heft operation that produces an output, typically by invoking some tool. For example, `typescript` and `eslint` are Heft tasks. Unlike in other systems, Heft's tasks are not a coding contract or TypeScript interface; for example the `TypeScriptPlugin` implements three separate tasks (`typescript`, `eslint`, and `tslint`) whose code is closely integrated. -- **stage** - a larger sequence of work encompassing multiple Heft tasks. When invoking Heft, the command line typically selects a meaningful set of stages to run. The stage names are also used to group logging output. Examples of Heft stages: "clean", "compile", "bundle", "test" +- **stage** - a larger sequence of work encompassing multiple Heft tasks. When invoking Heft, the command line typically selects a meaningful set of stages to run. The stage names are also used to group logging output. Examples of Heft stages: "clean", "build", "test"   > **Future plans:** Today Rush commands can only invoke Heft actions. However, in the future we want to implement a "multiphase build" feature that will enable Rush to orchestrate more granular steps of work. For example, once a library dependency has compiled its output, Rush could start building the application before the library finishes running its unit tests. This feature will bring some additional jargon: diff --git a/pages/heft/core_plugins.md b/pages/heft/core_plugins.md index 3f2999162..e51749c85 100644 --- a/pages/heft/core_plugins.md +++ b/pages/heft/core_plugins.md @@ -8,11 +8,11 @@ navigation_source: docs_nav | ------------- | ------------- | | [ApiExtractorPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/ApiExtractorPlugin/ApiExtractorPlugin.ts) | Implements the [api-extractor]({% link pages/heft_tasks/api-extractor.md %}) task | | [BasicConfigureWebpackPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/Webpack/BasicConfigureWebpackPlugin.ts) | Used to configure the [webpack]({% link pages/heft_tasks/webpack.md %}) task by loading a static **webpack.config.js** file (instead of building a dynamic configuration at runtime) | -| [CleanPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/CleanPlugin.ts) | Deletes temporary files from a previous build | +| [CleanPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/CleanPlugin.ts) | Deletes output files from a previous build | | [CopyStaticAssetsPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/CopyStaticAssetsPlugin.ts) | Implements the [copy-static-assets]({% link pages/heft_tasks/copy-static-assets.md %}) task | | [JestPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/JestPlugin/JestPlugin.ts) | Implements the [jest]({% link pages/heft_tasks/jest.md %}) task | | [PackageJsonConfigurationPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/PackageJsonConfigurationPlugin.ts) | Disables the [typescript]({% link pages/heft_tasks/typescript.md %}) tasks's symlinking optimization for published projects, because publishing workflows do not handle symlinks properly | -| [ProjectActionConfigurationFilesPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/ActionConfigurationLoaders/ProjectActionConfigurationFilesPlugin.ts) | Reads project-specific config files for Heft "actions" such as **clean.json**, **typescript.json**, **copy-static-assets.json**, and **webpack.json** | -| [RushActionConfigurationFilesPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/ActionConfigurationLoaders/RushActionConfigurationFilesPlugin.ts) | Reads Rush monorepo config files for Heft "actions" such as **clean.json**, **typescript.json**, **copy-static-assets.json**, and **webpack.json** | +| [ProjectJsonConfigurationFilesPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/JsonConfigurationLoaders/ProjectJsonConfigurationFilesPlugin.ts) | Reads Heft-specific config files that apply to a single project. | +| [RushJsonConfigurationFilesPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/JsonConfigurationLoaders/RushJsonConfigurationFilesPlugin.ts) | Reads Heft-specific config files that are shared across all projects in a monorepo. | | [TypeScriptPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/TypeScriptPlugin/TypeScriptPlugin.ts) | Implements the [typescript]({% link pages/heft_tasks/typescript.md %}), [eslint]({% link pages/heft_tasks/eslint.md %}), and [tslint]({% link pages/heft_tasks/tslint.md %}) tasks | | [WebpackPlugin](https://github.com/microsoft/rushstack/blob/master/apps/heft/src/plugins/Webpack/WebpackPlugin.ts) | Implements the [webpack]({% link pages/heft_tasks/webpack.md %}) task | diff --git a/pages/heft_configs/typescript_json.md b/pages/heft_configs/typescript_json.md index 3656868f5..e9978b43b 100644 --- a/pages/heft_configs/typescript_json.md +++ b/pages/heft_configs/typescript_json.md @@ -50,7 +50,7 @@ navigation_source: docs_nav // "disableTslint": true, /** - * Set this to change the maximum number of file handles that will be opened for writing. + * Set this to change the maximum number of file handles that will be opened concurrently for writing. * The default is 50. */ // "maxWriteParallelism": 50 diff --git a/pages/heft_tasks/api-extractor.md b/pages/heft_tasks/api-extractor.md index 3b2648f0d..426e0d5d8 100644 --- a/pages/heft_tasks/api-extractor.md +++ b/pages/heft_tasks/api-extractor.md @@ -30,6 +30,7 @@ We recommend to use API Extractor for every TypeScript library project, especial There isn't a Heft-specific file for this task. Heft looks for API Extractor's config file [config/api-extractor.json](https://api-extractor.com/pages/commands/config_file/). This file can be created by invoking the [api-extractor init](https://api-extractor.com/pages/commands/api-extractor_init/) command. + ## package.json dependencies None -- Heft loads the `@microsoft/api-extractor` package from the `@microsoft/rush-stack-compiler-*` bundle. See the [typescript]({% link pages/heft_tasks/typescript.md %}) task documentation for details. diff --git a/pages/heft_tasks/copy-static-assets.md b/pages/heft_tasks/copy-static-assets.md index b85f433c6..2a0c22009 100644 --- a/pages/heft_tasks/copy-static-assets.md +++ b/pages/heft_tasks/copy-static-assets.md @@ -6,6 +6,7 @@ navigation_source: docs_nav This is a lightweight task that simply copies input files into output folders. + ## When to use it This task is mainly used to copy assets into the compiler's target folder so that they can be referenced by compiled code. In Heft's standard configuration, the TypeScript compiler reads **src/\*\*/.ts** inputs and writes **lib/\*\*/.js** outputs. For example, a React project may have a file that loads an **src/index.css** asset like this: @@ -29,6 +30,7 @@ When Webpack is invoked on **lib/index.js**, it will process the resulting `requ Configure this task using the [copy-static-assets.json]({% link pages/heft_configs/copy-static-assets_json.md %}) config file. + ## package.json dependencies None - this feature is implemented internally by Heft. diff --git a/pages/heft_tasks/eslint.md b/pages/heft_tasks/eslint.md index 8d2084b5f..0ce2ad2c3 100644 --- a/pages/heft_tasks/eslint.md +++ b/pages/heft_tasks/eslint.md @@ -6,9 +6,10 @@ navigation_source: docs_nav This task invokes the [ESLint](https://eslint.org/) tool which reports errors about common coding problems. + ## When to use it -ESLint fits together with several other tools as part of Rush Stack's strategy for code validation: +ESLint fits together with several other tools as part of Rush Stack's recommended strategy for code validation: - [Prettier](https://prettier.io/): This tool manages trivial syntax aspects such as spaces, commas, and semicolons. Because these aspects normally don't affect code semantics, we never bother the developer with error messages about it, nor is it part of the build. Instead, Prettier reformats the code automatically via a `git commit` hook (and also whenever you save a file, if you enable the editor extension). @@ -18,6 +19,8 @@ ESLint fits together with several other tools as part of Rush Stack's strategy f - [API Extractor]({% link pages/heft_tasks/api-extractor.md %}): This is an additional validation check for library packages only. It ensures their API contracts are well-formed and properly documented. +Although it's recommended to set up your build system in this way, Heft doesn't require a particular approach. Each of these components is optional, and other configurations are possible. For example, older code bases may need to use [TSLint]({% link pages/heft_tasks/tslint.md %}) instead of ESLint. + ## Config files @@ -42,6 +45,7 @@ module.exports = { }; ``` + ## package.json dependencies Heft loads the `eslint` package from the `@microsoft/rush-stack-compiler-*` bundle. See the [typescript]({% link pages/heft_tasks/typescript.md %}) task documentation for details. diff --git a/pages/heft_tasks/jest.md b/pages/heft_tasks/jest.md index 865ae668a..a4e757882 100644 --- a/pages/heft_tasks/jest.md +++ b/pages/heft_tasks/jest.md @@ -35,6 +35,7 @@ Generally your Jest configuration should simply extend Heft's standard preset: ***Note:** If you find yourself frequently adding lots of custom settings to this file, please create a GitHub issue and tell us about it. Our aim is to provide a configuration that minimizes the need for project-specific customizations.* + ## package.json dependencies Heft has direct dependencies on the Jest packages that it needs, so you don't need to add Jest to your project's **package.json** file. diff --git a/pages/heft_tasks/tslint.md b/pages/heft_tasks/tslint.md index 4b55e88fe..69f93d6e3 100644 --- a/pages/heft_tasks/tslint.md +++ b/pages/heft_tasks/tslint.md @@ -18,6 +18,7 @@ New projects should use the [eslint]({% link pages/heft_tasks/eslint.md %}) task There isn't a Heft-specific file for this task. Heft looks for TSLint's config file [tslint.json](https://palantir.github.io/tslint/usage/configuration/). + ## package.json dependencies None -- Heft loads the `tslint` package from the `@microsoft/rush-stack-compiler-*` bundle. See the [typescript]({% link pages/heft_tasks/typescript.md %}) task documentation for details. diff --git a/pages/heft_tasks/typescript.md b/pages/heft_tasks/typescript.md index b585c3a43..0fa10bf00 100644 --- a/pages/heft_tasks/typescript.md +++ b/pages/heft_tasks/typescript.md @@ -50,6 +50,7 @@ To use this system, your **tsconfig.json** file should extend from one of the `i For advanced scenarios, Heft also provides an optional [typescript.json]({% link pages/heft_configs/typescript_json.md %}) config file that can be used to configure toolchain features such as multiple emit targets for the TypeScript compiler. + ## package.json dependencies Heft itself does not require your project to depend on the `typescript` NPM package. Instead, the TypeScript task will follow the `"extends"` references from **tsconfig.json**, and then call `require("typescript")` from that folder (**<project folder>/node_modules/@microsoft/rush-stack-compiler-3.9/** in the above example). This reduces **package.json** boilerplate in a large monorepo. diff --git a/pages/heft_tasks/webpack.md b/pages/heft_tasks/webpack.md index e77fdf4f7..9aca7760e 100644 --- a/pages/heft_tasks/webpack.md +++ b/pages/heft_tasks/webpack.md @@ -59,6 +59,7 @@ module.exports = { }; ``` + ## package.json dependencies None -- Heft loads the `@microsoft/api-extractor` package from the `@microsoft/rush-stack-compiler-*` bundle. See the [typescript]({% link pages/heft_tasks/typescript.md %}) task documentation for details.