Skip to content

Commit 1fb04ea

Browse files
Copiloticlanton
Copilot
and
iclanton
committed
Add documentation for Heft isolated transpile plugin (SWC)
- Create isolated-transpile.md with full plugin documentation - Add plugin to package_index.md - Add plugin to sidebar navigation Co-authored-by: iclanton <5010588+iclanton@users.noreply.github.com>
1 parent e51f576 commit 1fb04ea

3 files changed

Lines changed: 168 additions & 0 deletions

File tree

‎websites/heft.rushstack.io/docs/pages/plugins/isolated-transpile.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
title: Isolated transpile plugin (SWC)
3+
---
4+
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
7+
8+
<!-- prettier-ignore-start -->
9+
| | |
10+
| --- | --- |
11+
| **Plugin package:** | [@rushstack/heft-isolated-typescript-transpile-plugin](https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-isolated-typescript-transpile-plugin) |
12+
| **Plugin name:** | [swc-isolated-transpile-plugin](https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-isolated-typescript-transpile-plugin/heft-plugin.json) implemented by [SwcIsolatedTranspilePlugin.ts](https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-isolated-typescript-transpile-plugin/src/SwcIsolatedTranspilePlugin.ts) |
13+
| **Plugin config file:** | (none) |
14+
| **heft.json options:** | [swc-isolated-transpile-plugin.schema.json](https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-isolated-typescript-transpile-plugin/src/schemas/swc-isolated-transpile-plugin.schema.json) |
15+
<!-- prettier-ignore-end -->
16+
17+
This plugin uses [SWC](https://swc.rs/) to transpile TypeScript source files into JavaScript, as an
18+
alternative to the standard [TypeScript plugin](./typescript.md). SWC is a high-performance transpiler
19+
written in Rust that can be significantly faster than the TypeScript compiler for the transpilation step.
20+
21+
## When to use it
22+
23+
The isolated transpile plugin is useful when you want to speed up the JavaScript emit step of your build.
24+
In a typical TypeScript build, the TypeScript compiler both type-checks your code _and_ transpiles it to
25+
JavaScript. These two tasks can be separated:
26+
27+
- **Type checking** remains handled by the standard [TypeScript plugin](./typescript.md) with
28+
`emitDeclarationOnly: true` in your **tsconfig.json**
29+
- **Transpilation** is handled by this plugin using SWC, which processes each file independently
30+
(hence "isolated transpile")
31+
32+
Because SWC processes files in isolation, it cannot perform cross-file type checking or certain
33+
TypeScript-specific emit transformations that require type information. However, for many projects
34+
the performance benefit is substantial.
35+
36+
> **Note:** This plugin requires `@rushstack/heft-typescript-plugin` as a peer dependency, since it
37+
> reuses the TypeScript plugin's tsconfig loading infrastructure.
38+
39+
## package.json dependencies
40+
41+
You'll need to add the plugin package to your project:
42+
43+
<Tabs>
44+
<TabItem value="rush-install" label="Rush">
45+
46+
```bash
47+
# If you are using Rush, run this shell command in your project folder:
48+
rush add --package @rushstack/heft-isolated-typescript-transpile-plugin --dev
49+
```
50+
51+
</TabItem>
52+
<TabItem value="npm-install" label="NPM">
53+
54+
```bash
55+
# If you are using vanilla NPM, run this shell command in your project folder:
56+
npm install @rushstack/heft-isolated-typescript-transpile-plugin --save-dev
57+
```
58+
59+
</TabItem>
60+
</Tabs>
61+
62+
You must also have `@rushstack/heft-typescript-plugin` installed, since it is a peer dependency.
63+
64+
## Configuration
65+
66+
Your [heft.json config file](../configs/heft_json.md) should invoke both the TypeScript plugin
67+
(for type checking and declaration emit) and this plugin (for JavaScript transpilation):
68+
69+
**&lt;project folder&gt;/config/heft.json**
70+
71+
```js
72+
{
73+
"$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
74+
75+
"phasesByName": {
76+
"build": {
77+
"cleanFiles": [
78+
{ "sourcePath": "dist" },
79+
{ "sourcePath": "lib" },
80+
{ "sourcePath": "lib-commonjs" }
81+
],
82+
"tasksByName": {
83+
"typescript": {
84+
"taskPlugin": {
85+
"pluginPackage": "@rushstack/heft-typescript-plugin"
86+
}
87+
},
88+
"swc-transpile": {
89+
"taskDependencies": ["typescript"],
90+
"taskPlugin": {
91+
"pluginPackage": "@rushstack/heft-isolated-typescript-transpile-plugin",
92+
"options": {
93+
"emitKinds": [
94+
{
95+
"outDir": "lib-commonjs",
96+
"formatOverride": "CommonJS",
97+
"targetOverride": "ES2017"
98+
},
99+
{
100+
"outDir": "lib",
101+
"formatOverride": "ESNext",
102+
"targetOverride": "ES2017"
103+
}
104+
]
105+
}
106+
}
107+
}
108+
}
109+
}
110+
}
111+
}
112+
```
113+
114+
When using this plugin, you should configure the TypeScript plugin to only emit declarations by setting
115+
`"emitDeclarationOnly": true` in your **tsconfig.json**, since the JavaScript output will be produced
116+
by SWC instead.
117+
118+
## heft.json plugin options
119+
120+
```js
121+
// JSON Schema: swc-isolated-transpile-plugin.schema.json
122+
"options": {
123+
/**
124+
* (Optional) The path to the tsconfig.json file. If not specified, the default
125+
* tsconfig.json resolution is used.
126+
*/
127+
// "tsConfigPath": "./tsconfig.json",
128+
129+
/**
130+
* (REQUIRED) An array of emit configurations. Each entry specifies an output
131+
* directory, module format, and target.
132+
*/
133+
"emitKinds": [
134+
{
135+
/**
136+
* The output directory for the transpiled files, relative to the project folder.
137+
*/
138+
"outDir": "lib-commonjs",
139+
140+
/**
141+
* The module format for transpiled files. Uses TypeScript's ModuleKind names.
142+
* Supported values: "CommonJS", "ES2015", "ES2020", "ES2022", "ESNext",
143+
* "Node16", "NodeNext", "AMD", "UMD"
144+
*/
145+
"formatOverride": "CommonJS",
146+
147+
/**
148+
* The target ECMAScript version for transpiled files. Uses TypeScript's
149+
* ScriptTarget names.
150+
* Supported values: "ES3", "ES5", "ES2015", "ES2016", "ES2017", "ES2018",
151+
* "ES2019", "ES2020", "ES2021", "ES2022", "ES2023", "ES2024", "ESNext"
152+
*/
153+
"targetOverride": "ES2017"
154+
}
155+
]
156+
}
157+
```
158+
159+
## See also
160+
161+
- [TypeScript plugin](./typescript.md) - The standard TypeScript compiler plugin
162+
- [SWC documentation](https://swc.rs/)

‎websites/heft.rushstack.io/docs/pages/plugins/package_index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ title: Plugin package index
99
| [@rushstack/heft-api-extractor-plugin](https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-api-extractor-plugin) | [api-extractor-plugin](./api-extractor.md) |
1010
| [@rushstack/heft-jest-plugin](https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-jest-plugin) | [jest-plugin](./jest.md) |
1111
| [@rushstack/heft-dev-cert-plugin](https://github.com/microsoft/rushstack/tree/main/heft-plugins/heft-dev-cert-plugin) | [trust-dev-certificate-plugin](./dev-cert.md) <br/> [untrust-dev-certificate-plugin](./dev-cert.md) |
12+
| [@rushstack/heft-isolated-typescript-transpile-plugin](https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-isolated-typescript-transpile-plugin) | [swc-isolated-transpile-plugin](./isolated-transpile.md) |
1213
| [@rushstack/heft-lint-plugin](https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-lint-plugin) | [lint-plugin](./lint.md) |
1314
| [@rushstack/heft-rspack-plugin](https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-rspack-plugin) | [rspack-plugin](./rspack.md) |
1415
| [@rushstack/heft-sass-plugin](https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-sass-plugin) | [sass-plugin](./sass.md) |

‎websites/heft.rushstack.io/sidebars.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,11 @@ const sidebars = {
8383
label: 'ESlint / TSLint',
8484
id: 'pages/plugins/lint'
8585
},
86+
{
87+
type: 'doc',
88+
label: 'Isolated transpile (SWC)',
89+
id: 'pages/plugins/isolated-transpile'
90+
},
8691
{
8792
type: 'doc',
8893
label: 'Node.js service',

0 commit comments

Comments
 (0)