Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update guide for additional asset types #3811

Merged
merged 1 commit into from
Oct 24, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions website/docs/en/config/source/assets-include.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
38 changes: 27 additions & 11 deletions website/docs/en/guide/basic/static-assets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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"
<!-- Wrong -->
Expand Down Expand Up @@ -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 {
Expand All @@ -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
Expand Down
3 changes: 2 additions & 1 deletion website/docs/en/guide/migration/vite.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand Down Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions website/docs/zh/config/source/assets-include.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

- **类型:** [Rspack.RuleSetCondition](https://rspack.dev/config/module#condition)
- **默认值:** `undefined`
- **版本:** `>= 1.0.18`

指定需要被视为静态资源的额外文件类型。

Expand Down
36 changes: 26 additions & 10 deletions website/docs/zh/guide/basic/static-assets.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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)。

## 自定义规则
Expand Down
1 change: 1 addition & 0 deletions website/docs/zh/guide/migration/vite.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,7 @@ Rsbuild 会在构建时自动注入 `<script>` 标签到生成的 HTML 文件中
| plugins | [plugins](/config/plugins) |
| envDir | [Env Directory](/guide/advanced/env-vars#env-目录) |
| 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) |
Expand Down
Loading