diff --git a/.vitepress/config/en.ts b/.vitepress/config/en.ts index 53d64059828..dbef288b1e1 100644 --- a/.vitepress/config/en.ts +++ b/.vitepress/config/en.ts @@ -224,6 +224,10 @@ export const enConfig = defineLocaleConfig("root", { text: "Isolated Declarations", link: "/docs/guide/usage/transformer/isolated-declarations", }, + { + text: "Runtime Helpers", + link: "/docs/guide/usage/transformer/runtime-helpers", + }, ], }, { diff --git a/src/docs/guide/usage/transformer.md b/src/docs/guide/usage/transformer.md index fa917e8385a..d096f4240b5 100644 --- a/src/docs/guide/usage/transformer.md +++ b/src/docs/guide/usage/transformer.md @@ -22,6 +22,10 @@ Use the umbrella crate [oxc][url-oxc-crate] with the `transformer` feature. Rust usage example can be found [here](https://github.com/oxc-project/oxc/blob/main/crates/oxc_transformer/examples/transformer.rs). +## Runtime Helpers + +The transformer may inject imports from [`@oxc-project/runtime`](./transformer/runtime-helpers), a package containing Oxc's runtime helpers. See the [runtime helpers guide](./transformer/runtime-helpers) for how to handle this. + ## Integrations - [`unplugin-oxc`](https://npmx.dev/package/unplugin-oxc) diff --git a/src/docs/guide/usage/transformer/runtime-helpers.md b/src/docs/guide/usage/transformer/runtime-helpers.md new file mode 100644 index 00000000000..96a07fa5486 --- /dev/null +++ b/src/docs/guide/usage/transformer/runtime-helpers.md @@ -0,0 +1,41 @@ +# Runtime Helpers + +The transformer may inject import statements from `@oxc-project/runtime`, a package containing Oxc's runtime helpers. There are two ways to handle this. + +## Bundling the Helpers + +If you are using a bundler, the runtime helpers will be resolved and bundled into your output. This is the only option for non-Node apps. For Node apps and libraries, this is also suitable when you don't want to manage the runtime version yourself. + +No additional setup is required — your bundler will handle the imports automatically. + +## Externalizing the Helpers + +Alternatively, you can add `@oxc-project/runtime` to your dependencies and externalize the imports. You need to select the runtime version that matches your `oxc-transform` version (see [version compatibility](#version-compatibility) below). + +The benefit of this approach is deduplication: when a user depends on multiple libraries that were transformed with Oxc, the runtime helpers are shared rather than duplicated in each bundle. + +::: code-group + +```sh [npm] +npm add @oxc-project/runtime +``` + +```sh [pnpm] +pnpm add @oxc-project/runtime +``` + +```sh [yarn] +yarn add @oxc-project/runtime +``` + +```sh [bun] +bun add @oxc-project/runtime +``` + +::: + +## Version Compatibility + +| `oxc-transform` | `@oxc-project/runtime` | +| --------------- | ---------------------- | +| 0.115.0 | 0.115.0 |