From 256c551c88a478868b3d2addfebd4078260d3561 Mon Sep 17 00:00:00 2001 From: neverland Date: Thu, 24 Oct 2024 12:04:15 +0800 Subject: [PATCH] docs: update guide for additional asset types (#3811) --- .../docs/en/config/source/assets-include.mdx | 1 + website/docs/en/guide/basic/static-assets.mdx | 38 +++++++++++++------ website/docs/en/guide/migration/vite.mdx | 3 +- .../docs/zh/config/source/assets-include.mdx | 1 + website/docs/zh/guide/basic/static-assets.mdx | 36 +++++++++++++----- website/docs/zh/guide/migration/vite.mdx | 1 + 6 files changed, 58 insertions(+), 22 deletions(-) diff --git a/website/docs/en/config/source/assets-include.mdx b/website/docs/en/config/source/assets-include.mdx index 1c91a63145..5228922cac 100644 --- a/website/docs/en/config/source/assets-include.mdx +++ b/website/docs/en/config/source/assets-include.mdx @@ -2,6 +2,7 @@ - **Type:** [Rspack.RuleSetCondition](https://rspack.dev/config/module#condition) - **Default:** `undefined` +- **Version:** `>= 1.0.18` Include additional files that should be treated as static assets. diff --git a/website/docs/en/guide/basic/static-assets.mdx b/website/docs/en/guide/basic/static-assets.mdx index 05b0e28b9d..db162d6d8e 100644 --- a/website/docs/en/guide/basic/static-assets.mdx +++ b/website/docs/en/guide/basic/static-assets.mdx @@ -130,7 +130,7 @@ For example, in an HTML template, the `./public/favicon.ico` file can be referen Here are some notes on using the `public` folder: -- When referencing resources in the public folder via URL, please use absolute paths instead of relative paths to ensure that the resources can be accessed correctly after deployment. +- When referencing assets in the public folder via URL, please use absolute paths instead of relative paths to ensure that the assets can be accessed correctly after deployment. ```html title="src/index.html" @@ -194,9 +194,33 @@ After adding the type declaration, if the type error still exists, you can try t ## Extend Asset Types -If the built-in asset types in Rsbuild cannot meet your requirements, you can modify the built-in Rspack configuration and extend the asset types you need using [tools.rspack](/config/tools/rspack). +If the built-in asset types in Rsbuild cannot meet your requirements, you can extend additional static asset types in the following ways. -For example, if you want to treat `*.pdf` files as assets and directly output them to the dist directory, you can add the following configuration: +### Use `source.assetsInclude` + +By using the [source.assetsInclude](/config/source/assets-include) config, you can specify additional file types to be treated as static assets. + +```ts title="rsbuild.config.ts" +export default { + source: { + assetsInclude: /\.pdf$/, + }, +}; +``` + +After adding the above configuration, you can import `*.pdf` files in your code, for example: + +```js +import myFile from './static/myFile.pdf'; + +console.log(myFile); // "/static/myFile.6c12aba3.pdf" +``` + +### Use `tools.rspack` + +You can modify the built-in Rspack configuration and add custom static assets handling rules via [tools.rspack](/config/tools/rspack). + +For example, to treat `*.pdf` files as assets and output them to the dist directory, you can add the following configuration: ```ts title="rsbuild.config.ts" export default { @@ -214,14 +238,6 @@ export default { }; ``` -After adding the above configuration, you can import `*.pdf` files in your code, for example: - -```js -import myFile from './static/myFile.pdf'; - -console.log(myFile); // "/static/myFile.6c12aba3.pdf" -``` - For more information about asset modules, please refer to [Rspack - Asset modules](https://rspack.dev/guide/features/asset-module). ## Custom Rules diff --git a/website/docs/en/guide/migration/vite.mdx b/website/docs/en/guide/migration/vite.mdx index 6761798fb0..4c32ee9ac5 100644 --- a/website/docs/en/guide/migration/vite.mdx +++ b/website/docs/en/guide/migration/vite.mdx @@ -111,6 +111,7 @@ Here is the corresponding Rsbuild configuration for Vite configuration: | plugins | [plugins](/config/plugins) | | envDir | [Env Directory](/guide/advanced/env-vars#env-directory) | | publicDir | [server.publicDir](/config/server/public-dir) | +| assetsInclude | [source.assetsInclude](/config/source/assets-include) | | resolve.alias | [source.alias](/config/source/alias) | | resolve.conditions | [tools.rspack.resolve.conditionNames](/config/tools/rspack) | | resolve.mainFields | [tools.rspack.resolve.mainFields](/config/tools/rspack) | @@ -148,7 +149,7 @@ Here is the corresponding Rsbuild configuration for Vite configuration: Notes: -- The above table does not cover all configurations of Vue CLI, feel free to add more. +- The above table does not cover all configurations of Vite, feel free to add more. ## Environment Variables diff --git a/website/docs/zh/config/source/assets-include.mdx b/website/docs/zh/config/source/assets-include.mdx index 9b3e019578..0e58810dfb 100644 --- a/website/docs/zh/config/source/assets-include.mdx +++ b/website/docs/zh/config/source/assets-include.mdx @@ -2,6 +2,7 @@ - **类型：** [Rspack.RuleSetCondition](https://rspack.dev/config/module#condition) - **默认值：** `undefined` +- **版本：** `>= 1.0.18` 指定需要被视为静态资源的额外文件类型。 diff --git a/website/docs/zh/guide/basic/static-assets.mdx b/website/docs/zh/guide/basic/static-assets.mdx index c14d3d5961..76903e9f5e 100644 --- a/website/docs/zh/guide/basic/static-assets.mdx +++ b/website/docs/zh/guide/basic/static-assets.mdx @@ -194,9 +194,33 @@ declare module '*.png' { ## 扩展静态资源类型 -如果 Rsbuild 内置的静态资源类型不能满足你的需求，那么你可以通过 [tools.rspack](/config/tools/rspack) 来修改内置的 Rspack 配置，并扩展你需要的静态资源类型。 +如果 Rsbuild 内置的静态资源类型不能满足你的需求，可以通过以下方式扩展额外的静态资源类型。 -比如，你需要把 `*.pdf` 文件当做静态资源直接输出到产物目录，可以添加以下配置： +### 使用 `source.assetsInclude` + +通过 [source.assetsInclude](/config/source/assets-include) 配置项，你可以指定需要被视为静态资源的额外文件类型。 + +```ts title="rsbuild.config.ts" +export default { + source: { + assetsInclude: /\.pdf$/, + }, +}; +``` + +添加以上配置后，你就可以在代码里引用 `*.pdf` 文件了，比如： + +```js +import myFile from './static/myFile.pdf'; + +console.log(myFile); // "/static/myFile.6c12aba3.pdf" +``` + +### 使用 `tools.rspack` + +可以通过 [tools.rspack](/config/tools/rspack) 来修改内置的 Rspack 配置，并添加自定义的静态资源处理规则。 + +比如，把 `*.pdf` 文件当做静态资源输出到产物目录，可以添加以下配置： ```ts title="rsbuild.config.ts" export default { @@ -214,14 +238,6 @@ export default { }; ``` -添加以上配置后，你就可以在代码里引用 `*.pdf` 文件了，比如： - -```js -import myFile from './static/myFile.pdf'; - -console.log(myFile); // "/static/myFile.6c12aba3.pdf" -``` - 关于 asset modules 的更多介绍，请参考 [Rspack - Asset modules](https://rspack.dev/guide/features/asset-module)。 ## 自定义规则 diff --git a/website/docs/zh/guide/migration/vite.mdx b/website/docs/zh/guide/migration/vite.mdx index 2ba9deb9d5..77bff3bc9a 100644 --- a/website/docs/zh/guide/migration/vite.mdx +++ b/website/docs/zh/guide/migration/vite.mdx @@ -111,6 +111,7 @@ Rsbuild 会在构建时自动注入 `