diff --git a/packages/plugin-dts/README.md b/packages/plugin-dts/README.md index 9d0e1055a..0ac5172a6 100644 --- a/packages/plugin-dts/README.md +++ b/packages/plugin-dts/README.md @@ -2,13 +2,166 @@ Rslib Banner -# Rslib +# rsbuild-plugin-dts -Rslib is a library development tool powered by [Rsbuild](https://rsbuild.dev). It allows library developers to leverage the knowledge and ecosystem of webpack and Rspack. +An [Rsbuild plugin](https://www.npmjs.com/package/rsbuild-plugin-dts) to emit declaration files for TypeScript which is built-in in Rslib. -## Documentation +## Using in Rslib -https://lib.rsbuild.dev/ +Read [DTS](https://lib.rsbuild.dev/guide/advanced/dts) and [lib.dts](https://lib.rsbuild.dev/config/lib/dts) for more details. + +## Using in Rsbuild + +Install: + +```bash +npm add rsbuild-plugin-dts -D +``` + +Add plugin to `rsbuild.config.ts`: + +```ts +// rsbuild.config.ts +import { pluginDts } from 'rsbuild-plugin-dts'; + +export default { + plugins: [pluginDts()], +}; +``` + +## Options + +### bundle + +- **Type:** `boolean` +- **Default:** `false` + +Whether to bundle the DTS files. + +If you want to [bundle DTS](https://lib.rsbuild.dev/guide/advanced/dts#bundle-dts) files, you should: + +1. Install `@microsoft/api-extractor` as a development dependency, which is the underlying tool used for bundling DTS files. + +```bash +npm add @microsoft/api-extractor -D +``` + +2. Set `bundle` to `true`. + +```js +pluginDts({ + bundle: true, +}); +``` + +### distPath + +- **Type:** `string` + +The output directory of DTS files. The default value follows the priority below: + +1. The `distPath` value of the plugin options. +2. The `declarationDir` value in the `tsconfig.json` file. +3. The [output.distPath.root](https://rsbuild.dev/config/output/dist-path) value of Rsbuild configuration. + +```js +pluginDts({ + distPath: './dist-types', +}); +``` + +### build + +- **Type:** `boolean` +- **Default:** `false` + +Determines whether to generate DTS files while building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details. + +When this option is enabled, you must explicitly set `declarationDir` or `outDir` in `tsconfig.json` in order to meet the build requirements. + +### abortOnError + +- **Type:** `boolean` +- **Default:** `true` + +Whether to abort the build process when an error occurs during DTS generation. + +By default, type errors will cause the build to fail. + +When `abortOnError` is set to `false`, the build will still succeed even if there are type issues in the code. + +```js +pluginDts({ + abortOnError: false, +}); +``` + +### dtsExtension + +- **Type:** `string` +- **Default:** `'.d.ts'` + +The extension of the DTS file. + +```js +pluginDts({ + dtsExtension: '.d.mts', +}); +``` + +### autoExternal + +- **Type:** `boolean` +- **Default:** `true` + +Whether to automatically externalize dependencies of different dependency types and do not bundle them into the DTS file. + +The default value of `autoExternal` is `true`, which means the following dependency types will not be bundled: + +- `dependencies` +- `optionalDependencies` +- `peerDependencies` + +And the following dependency types will be bundled: + +- `devDependencies` + +```js +pluginDts({ + autoExternal: { + dependencies: true, + optionalDependencies: true, + peerDependencies: true, + devDependencies: false, + }, +}); +``` + +### banner + +- **Type:** `string` +- **Default:** `undefined` + +Inject content into the top of each DTS file. + +```js +pluginDts({ + banner: '/** @banner */', +}); +``` + +### footer + +- **Type:** `string` +- **Default:** `undefined` + +Inject content into the bottom of each DTS file. + +```js +pluginDts({ + footer: '/** @footer */', +}); +``` ## Contributing @@ -16,4 +169,4 @@ Please read the [Contributing Guide](https://github.com/web-infra-dev/rslib/blob ## License -Rslib is [MIT licensed](https://github.com/web-infra-dev/rslib/blob/main/LICENSE). +[MIT licensed](https://github.com/web-infra-dev/rslib/blob/main/LICENSE). diff --git a/packages/plugin-dts/src/index.ts b/packages/plugin-dts/src/index.ts index 99bc3236c..2cee27645 100644 --- a/packages/plugin-dts/src/index.ts +++ b/packages/plugin-dts/src/index.ts @@ -50,7 +50,7 @@ export const PLUGIN_DTS_NAME = 'rsbuild:dts'; // use ts compiler API to generate bundleless dts // use ts compiler API and api-extractor to generate dts bundle // TODO: deal alias in dts -export const pluginDts = (options: PluginDtsOptions): RsbuildPlugin => ({ +export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({ name: PLUGIN_DTS_NAME, setup(api) { diff --git a/website/docs/en/_meta.json b/website/docs/en/_meta.json index d03862962..988672017 100644 --- a/website/docs/en/_meta.json +++ b/website/docs/en/_meta.json @@ -8,10 +8,5 @@ "text": "Config", "link": "/config/", "activeMatch": "/config/" - }, - { - "text": "API", - "link": "/api/javascript-api/core", - "activeMatch": "/api/" } ] diff --git a/website/docs/en/config/lib/auto-external.mdx b/website/docs/en/config/lib/auto-external.mdx index a2f78b924..cd9dc0c53 100644 --- a/website/docs/en/config/lib/auto-external.mdx +++ b/website/docs/en/config/lib/auto-external.mdx @@ -1,3 +1,7 @@ +--- +overviewHeaders: [2, 3] +--- + # lib.autoExternal - **Type:** diff --git a/website/docs/en/config/lib/banner.mdx b/website/docs/en/config/lib/banner.mdx index 04832d619..5e229341e 100644 --- a/website/docs/en/config/lib/banner.mdx +++ b/website/docs/en/config/lib/banner.mdx @@ -1,3 +1,7 @@ +--- +overviewHeaders: [2, 3] +--- + # lib.banner - **Type:** diff --git a/website/docs/en/config/lib/dts.mdx b/website/docs/en/config/lib/dts.mdx index 2d5594da4..ecac3e3b7 100644 --- a/website/docs/en/config/lib/dts.mdx +++ b/website/docs/en/config/lib/dts.mdx @@ -1,3 +1,7 @@ +--- +overviewHeaders: [2, 3] +--- + # lib.dts - **Type:** @@ -5,9 +9,9 @@ ```ts type Dts = | { - build?: boolean; bundle?: boolean; distPath?: string; + build?: boolean; abortOnError?: boolean; autoExtension?: boolean; } @@ -17,3 +21,172 @@ type Dts = - **Default:** `undefined` Configure the generation of the TypeScript declaration files. + +## Boolean Type + +DTS generation is an optional feature, you can set `dts: true` to enable [bundleless DTS](/guide/advanced/dts#bundleless-dts) generation. + +```ts title="rslib.config.ts" {5} +export default { + lib: [ + { + format: 'esm', + dts: true, + }, + ], +}; +``` + +If you want to disable DTS generation, you can set `dts: false` or do not specify the `dts` option. + +```ts title="rslib.config.ts" {5} +export default { + lib: [ + { + format: 'esm', + dts: false, + }, + ], +}; +``` + +## Object Type + +If you want to customize the DTS generation, you can set the `dts` option to an object. + +### dts.bundle + +- **Type:** `boolean` +- **Default:** `false` + +Whether to bundle the DTS files. + +#### Example + +If you want to [bundle DTS](/guide/advanced/dts#bundle-dts) files, you should: + +1. Install `@microsoft/api-extractor` as a development dependency, which is the underlying tool used for bundling DTS files. + +import { PackageManagerTabs } from '@theme'; + + + +2. Set `dts.bundle` to `true`. + +```ts title="rslib.config.ts" {5-7} +export default { + lib: [ + { + format: 'esm', + dts: { + bundle: true, + }, + }, + ], +}; +``` + +::: note + +[@microsoft/api-extractor](https://github.com/microsoft/rushstack/tree/main/apps/api-extractor) only supports bundle DTS for single entry. If you want to generate bundle DTS for multiple entries, you can add extra lib configuration in [lib](/config/lib) field to split multiple entries into multiple lib configurations. + +::: + +#### Handle Third-Party Packages + +When we bundle DTS files, we should specify which third-party package types need to be bundled, refer to the [Handle Third-Party Dependencies](/guide/advanced/third-party-deps) documentation for more details about externals related configurations. + +### dts.distPath + +- **Type:** `string` + +The output directory of DTS files. + +#### Default Value + +The default value follows the priority below: + +1. The `dts.distPath` value in the current lib configuration. +2. The `declarationDir` value in the `tsconfig.json` file. +3. The [output.distPath.root](/config/rsbuild/output#outputdistpath) value in the current lib configuration. + +#### Example + +```ts title="rslib.config.ts" {5-7} +export default { + lib: [ + { + format: 'esm', + dts: { + distPath: './dist-types', + }, + }, + ], +}; +``` + +### dts.build + +- **Type:** `boolean` +- **Default:** `false` + +Determines whether to generate DTS files while building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details. + +::: note + +When this option is enabled, you must explicitly set `declarationDir` or `outDir` in `tsconfig.json` in order to meet the build requirements. + +::: + +### dts.abortOnError + +- **Type:** `boolean` +- **Default:** `true` + +Whether to abort the build process when an error occurs during DTS generation. + +By default, type errors will cause the build to fail. + +When `abortOnError` is set to `false` like below, the build will still succeed even if there are type issues in the code. + +```ts title="rslib.config.ts" {5-7} +export default { + lib: [ + { + format: 'esm', + dts: { + abortOnError: false, + }, + }, + ], +}; +``` + +::: warning + +When this configuration is disabled, there is no guarantee that the type files will be generated correctly. + +::: + +### dts.autoExtension + +- **Type:** `boolean` +- **Default:** `false` + +Whether to automatically set the DTS file extension based on the [format](/config/lib/format) option. + +#### Default Extension + +By default that when `dts.autoExtension` is `false`, the DTS file extension will be `.d.ts`. + +When `dts.autoExtension` is set to `true`, the DTS file extension will be: + +- `.d.ts` with `esm` format and `.d.cts` with `cjs` format when `type: module` in `package.json`. + +- `.d.ts` with `cjs` format and `.d.mts` with `esm` format when `type: commonjs` or no `type` field in `package.json`. + +::: note + +It follows the same logic as [lib.autoExtension](/config/lib/auto-extension), but the default value is different since the DTS file extension may cause some issues with different module resolution strategies. + +::: diff --git a/website/docs/en/config/lib/footer.mdx b/website/docs/en/config/lib/footer.mdx index 33f8f059e..e323cb44c 100644 --- a/website/docs/en/config/lib/footer.mdx +++ b/website/docs/en/config/lib/footer.mdx @@ -1,3 +1,7 @@ +--- +overviewHeaders: [2, 3] +--- + # lib.footer - **Type:** diff --git a/website/docs/en/config/rsbuild/source.mdx b/website/docs/en/config/rsbuild/source.mdx index 6bb69dcce..d6c50d6b9 100644 --- a/website/docs/en/config/rsbuild/source.mdx +++ b/website/docs/en/config/rsbuild/source.mdx @@ -13,7 +13,7 @@ Configure the source code parsing and compilation options. Create aliases to import or require certain modules, same as the [resolve.alias](https://rspack.dev/config/resolve#resolvealias) config of Rspack. -It is important to note that `source.alias` differs from [output.externals](/config/rsbuild/output#externals) in the following ways: +It is important to note that `source.alias` differs from [output.externals](/config/rsbuild/output#outputexternals) in the following ways: - The `source.alias` is used when bundling target code into the product (when [lib.bundle](/config/lib/bundle) is set to `true`). It allows you to replace the target module you want to include in the output with another module. diff --git a/website/docs/en/guide/advanced/assets.mdx b/website/docs/en/guide/advanced/assets.mdx index 5d1b13d50..9d385f181 100644 --- a/website/docs/en/guide/advanced/assets.mdx +++ b/website/docs/en/guide/advanced/assets.mdx @@ -1 +1,7 @@ # Assets + +::: note + +Features about assets are not fully supported yet. + +::: diff --git a/website/docs/en/guide/advanced/dts.mdx b/website/docs/en/guide/advanced/dts.mdx index 0a863508d..d0fa1a9ef 100644 --- a/website/docs/en/guide/advanced/dts.mdx +++ b/website/docs/en/guide/advanced/dts.mdx @@ -1 +1,65 @@ # DTS + +This chapter introduces what TypeScript Declaration Files (DTS) are and how to generate DTS files in Rslib. + +## What is DTS + +TypeScript Declaration Files (DTS) provide type information for JavaScript code. DTS files typically have a `.d.ts` extension. They allow the TypeScript compiler to understand the type structure of JavaScript code, enabling features like: + +1. **Type Checking**: Provide type information for JavaScript code, helping developers catch potential type errors at compile time. +2. **Code Completion**: Enhance code editor features like autocomplete and code navigation. +3. **Documentation Generation**: Generate documentation for JavaScript code, providing better developer experience. +4. **IDE Support**: Improve the developer experience in IDEs like Visual Studio Code, WebStorm, and others. +5. **Library Consumption**: Make it easier for other developers to use and understand your library. + +## What are Bundle DTS and Bundleless DTS + +### Bundle DTS + +Bundle DTS involves bundling multiple TypeScript declaration files into a single declaration file. + +- **Pros:** + + - **Simplified Management**: Simplifies the management and referencing of type files. + - **Easy Distribution**: Reduces the number of files users need to handle when using the library. + +- **Cons:** + - **Complex Generation**: Generating and maintaining a single bundle file can become complex in large projects. + - **Debugging Challenges**: Debugging type issues may not be as intuitive as with separate files. + +### Bundleless DTS + +Bundleless DTS involves generating a separate declaration file for each module in the library, just like `tsc` does. + +- **Pros:** + + - **Modular**: Each module has its own type definitions, making maintenance and debugging easier. + - **Flexibility**: Suitable for large projects, avoiding the complexity of a single file. + +- **Cons:** + - **Multiple Files**: Users may need to handle multiple declaration files when using the library. + - **Complex Management**: May require additional configuration to correctly reference all files. + +## How to Generate DTS in Rslib + +Rslib defaults to generating bundleless DTS, which using [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) and bundle DTS is also supported by [API Extractor](https://api-extractor.com/). + +If you want to generate bundleless DTS, you can: + +- Set `dts: true` or `dts: { bundle: false }` in the Rslib configuration file. + +If you want to generate bundle DTS, you can: + +1. Install `@microsoft/api-extractor` as a development dependency, which is the underlying tool used for bundling DTS files. + +import { PackageManagerTabs } from '@theme'; + + + +2. Set `dts: { bundle: true }` in the Rslib configuration file. + +::: tip + +You can refer to [lib.dts](/config/lib/dts) for more details about DTS configuration. + +::: diff --git a/website/docs/en/guide/advanced/output-compatibility.mdx b/website/docs/en/guide/advanced/output-compatibility.mdx index 425ff6210..da92f9213 100644 --- a/website/docs/en/guide/advanced/output-compatibility.mdx +++ b/website/docs/en/guide/advanced/output-compatibility.mdx @@ -11,7 +11,7 @@ By setting [lib.syntax](/config/lib/syntax), you can choose the syntax to which Rslib also supports using a [.browserslistrc](https://github.com/browserslist/browserslist#config-file) file to specify settings. Note that [lib.syntax](/config/lib/syntax) takes precedence over `.browserslistrc`. If both are present, `lib.syntax` will be used. -By default, the syntax is set to `ESNext`, which will only supports only the latest version of mainstream browsers (Chrome / Firefox / Edge / macOS Safari / iOS Safari) or Node.js according to [output.target](/config/rsbuild/output#target). +By default, the syntax is set to `ESNext`, which will only supports only the latest version of mainstream browsers (Chrome / Firefox / Edge / macOS Safari / iOS Safari) or Node.js according to [output.target](/config/rsbuild/output#outputtarget). ## Polyfill diff --git a/website/docs/en/guide/solution.mdx b/website/docs/en/guide/solution.mdx index 2da58e655..341504f57 100644 --- a/website/docs/en/guide/solution.mdx +++ b/website/docs/en/guide/solution.mdx @@ -6,9 +6,9 @@ In this chapter, we will introduce how to use Rslib to development libraries for Rslib outputs code for the browser by default, so no additional configuration is necessary to get started. -When developing a library that runs in the browser, you can package it in both [ESM](/guide/basic/output-format#esm--cjs) and [CJS](/guide/basic/output-format#esm--cjs) formats for integration with application bundlers. Configuring the package [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) to ESM output allows for better tree shaking. Additionally, you can create [UMD](/guide/basic/output-format#umd) format output for direct browser use and even generate [Module Federation ](/guide/advanced/module-federation) formats for dynamic loading by other applications. Configure [Browserslist](/config/rsbuild/output#browserslist) according to the target browser support to determine the downgrade syntax of the output, or adding [polyfill](/guide/advanced/output-compatibility) for API compatibility. +When developing a library that runs in the browser, you can package it in both [ESM](/guide/basic/output-format#esm--cjs) and [CJS](/guide/basic/output-format#esm--cjs) formats for integration with application bundlers. Configuring the package [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) to ESM output allows for better tree shaking. Additionally, you can create [UMD](/guide/basic/output-format#umd) format output for direct browser use and even generate [Module Federation ](/guide/advanced/module-federation) formats for dynamic loading by other applications. Configure [Browserslist](https://rsbuild.dev/guide/advanced/browserslist) according to the target browser support to determine the downgrade syntax of the output, or adding [polyfill](/guide/advanced/output-compatibility) for API compatibility. -When publishing to npm, you can choose not to [minify](/config/rsbuild/output#minify) your code or to minify it while providing a [sourcemap](/config/rsbuild/output#sourcemap) to enhance the debugging experience for users of your library. For styling, you can use [CSS](/guide/advanced/css), or [CSS pre-processors](/guide/advanced/css#preprocessors) like Sass, Less, or Stylus, or apply [PostCSS](/guide/advanced/css#postcss) for CSS post-processing. Tools like [Tailwind CSS](/guide/advanced/css#tailwind-css) can also help in building your styles. Using [CSS modules](/guide/advanced/css#css-modules) to create CSS modules is another option. +When publishing to npm, you can choose not to [minify](/config/rsbuild/output#outputminify) your code or to minify it while providing a [sourcemap](/config/rsbuild/output#outputsourcemap) to enhance the debugging experience for users of your library. For styling, you can use [CSS](/guide/advanced/css), or [CSS pre-processors](/guide/advanced/css#preprocessors) like Sass, Less, or Stylus, or apply [PostCSS](/guide/advanced/css#postcss) for CSS post-processing. Tools like [Tailwind CSS](/guide/advanced/css#tailwind-css) can also help in building your styles. Using [CSS modules](/guide/advanced/css#css-modules) to create CSS modules is another option. In terms of resource management, Rslib handles [static assets](/guide/advanced/assets) used in your code, such as SVG and PNG files. You can also build a component library of [React](/guide/solution/react), [Preact](https://github.com/web-infra-dev/rslib/tree/main/examples/preact-component-bundle-false), or other frameworks, using [Storybook](/guide/advanced/storybook) for UI component development and testing. @@ -19,7 +19,7 @@ Refer to the solutions in this chapter to learn how to use Rslib to develop brow ## Node.js Target -By setting set [target](/config/rsbuild/output#target) to `"node"` to development libraries for Node.js. +By setting set [target](/config/rsbuild/output#outputtarget) to `"node"` to development libraries for Node.js. You can create a [pure ESM](/guide/basic/output-format#esm--cjs) package or a [dual package](/guide/basic/output-format#esm--cjs) that supports both ESM and CJS as needed. In CJS output, `import.meta.url` will be automatically [shimmed](/config/lib/shims) for compatibility and `__dirname` and `__filename` got an optional ESM shims to ensure proper use across different module system. Node.js's built-in packages will be [externalized by default](/guide/advanced/third-party-deps), simplifying the configuration. diff --git a/website/docs/en/guide/solution/nodejs.mdx b/website/docs/en/guide/solution/nodejs.mdx index d0b2008d1..b62fb3179 100644 --- a/website/docs/en/guide/solution/nodejs.mdx +++ b/website/docs/en/guide/solution/nodejs.mdx @@ -52,9 +52,9 @@ export default defineConfig({ ## Target for Node.js -Rslib set [target](/config/rsbuild/output#target) to `"node"` by default, which is different from the default target of Rsbuild. +Rslib set [target](/config/rsbuild/output#outputtarget) to `"node"` by default, which is different from the default target of Rsbuild. -Rslib adjusts many configurations for Node.js. For example, [output.externals](/config/rsbuild/output#target) will exclude built-in Node.js modules, and [shims](/config/lib/shims) will add a shim for `import.meta.url` in CJS output by default. +Rslib adjusts many configurations for Node.js. For example, [output.externals](/config/rsbuild/output#outputtarget) will exclude built-in Node.js modules, and [shims](/config/lib/shims) will add a shim for `import.meta.url` in CJS output by default. ### Externals diff --git a/website/docs/en/guide/solution/react.mdx b/website/docs/en/guide/solution/react.mdx index f1dbb1248..8e1ecd3f5 100644 --- a/website/docs/en/guide/solution/react.mdx +++ b/website/docs/en/guide/solution/react.mdx @@ -21,7 +21,7 @@ Then select `React` when prompted to "Select template". ## Use Rslib in an Existing Project -To develop a React library, you need to set the [target](/config/rsbuild/output#target) to `"web"` in `rslib.config.ts`. This is crucial because Rslib sets the `target` to `"node"` by default, which differs from the default target of Rsbuild. +To develop a React library, you need to set the [target](/config/rsbuild/output#outputtarget) to `"web"` in `rslib.config.ts`. This is crucial because Rslib sets the `target` to `"node"` by default, which differs from the default target of Rsbuild. To compile React (JSX and TSX), you need to register the Rsbuild [React Plugin](https://rsbuild.dev/plugins/list/plugin-react). The plugin will automatically add the necessary configuration for React builds. diff --git a/website/docs/en/guide/start/glossary.mdx b/website/docs/en/guide/start/glossary.mdx index 69715f152..0b2637843 100644 --- a/website/docs/en/guide/start/glossary.mdx +++ b/website/docs/en/guide/start/glossary.mdx @@ -21,6 +21,10 @@ CJS stands for [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-m Bundleless refers to a development approach that avoids the traditional practice of bundling multiple JavaScript / TypeScript files into a single or fewer output files before serving them to the client. Instead, it aims to serve individual modules directly. +## DTS + +DTS stands for [TypeScript Declaration Files](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html), providing type information for JavaScript code. + ## Module Federation