Skip to content

Commit 9b169c9

Browse files
SoonIterSoonIter
committed
docs: assets
1 parent e2ab583 commit 9b169c9

File tree

7 files changed

+356
-3
lines changed

7 files changed

+356
-3
lines changed

‎tests/integration/asset/json/src/index.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1-
import a from './assets/data.json';
1+
import { bar, foo } from './assets/data.json';
22

3-
a;
3+
console.log(foo);
4+
console.log(bar);

‎website/docs/zh/config/rsbuild/output.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,12 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge';
44

55
与构建产物相关的选项。
66

7+
## output.assetPrefix <RsbuildDocBadge path="/config/output/asset-prefix" text="output.charset" />
8+
9+
使用该选项设置静态资源的 URL 前缀，比如设置为 CDN 地址。
10+
11+
在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 默认会将 `output.assetPrefix` 设置为 `"auto"`。
12+
713
## output.charset <RsbuildDocBadge path="/config/output/charset" text="output.charset" />
814

915
指定输出文件的 [字符编码](https://developer.mozilla.org/en-US/docs/Glossary/Character_encoding)，以确保它们在不同的环境中能够正确显示。
@@ -24,6 +30,8 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge';
2430

2531
设置图片、字体、媒体等静态资源被自动内联为 base64 的体积阈值。
2632

33+
在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 默认会将 `output.dataUriLimit` 设置为 `0`，不内联任何静态资源，以便于应用侧的构建工具处理和优化。
34+
2735
## output.distPath <RsbuildDocBadge path="/config/output/dist-path" text="output.distPath" />
2836

2937
设置构建产物的输出目录，Rsbuild 会根据产物的类型输出到对应的子目录下。

‎website/docs/zh/guide/advanced/_meta.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
"third-party-deps",
33
"output-compatibility",
44
"dts",
5+
"static-assets",
6+
"svgr-files",
7+
"json-files",
58
"module-federation",
69
"storybook"
710
]

‎website/docs/zh/guide/advanced/json-files.mdx‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# 引用 JSON 文件
2+
3+
Rslib 支持在代码中引用 JSON 文件。
4+
5+
## JSON 文件
6+
7+
你可以直接在 JavaScript 文件中引用 JSON 文件。
8+
9+
### 示例
10+
11+
```json title="example.json"
12+
{
13+
"name": "foo",
14+
"items": [1, 2]
15+
}
16+
```
17+
18+
```js title="index.js"
19+
import example from './example.json';
20+
21+
console.log(example.name); // 'foo';
22+
console.log(example.items); // [1, 2];
23+
```
24+
25+
### 具名引用
26+
27+
Rslib 同样支持通过 named import 来引用 JSON 文件：
28+
29+
```js
30+
import { name } from './example.json';
31+
32+
console.log(name); // 'foo';
33+
```
34+
35+
:::warning
36+
37+
Bundleless 下，JSON 文件仅支持具名引用。
38+
39+
:::

‎website/docs/zh/guide/advanced/static-assets.mdx‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# 引用静态资源
2+
3+
Rslib 支持在代码中引用图片、字体、音频、视频等类型的静态资源。
4+
5+
## 静态资源格式
6+
7+
以下是 Rslib 默认支持的静态资源格式：
8+
9+
- **图片**：png、jpg、jpeg、gif、svg、bmp、webp、ico、apng、avif、tif、tiff、jfif、pjpeg、pjp、cur。
10+
- **字体**：woff、woff2、eot、ttf、otf、ttc。
11+
- **音频**：mp3、wav、flac、aac、m4a、opus。
12+
- **视频**：mp4、webm、ogg、mov。
13+
14+
如果你需要引用其他格式的静态资源，请参考 [扩展静态资源类型](#扩展静态资源类型)。
15+
16+
## 在 JS 文件中引用
17+
18+
在 JS 文件中，可以直接通过 `import` 的方式引用相对路径下的静态资源：
19+
20+
```tsx
21+
// 引用 src/assets 目录下的 logo.png 图片
22+
import logo from './assets/logo.png';
23+
24+
console.log(logo); // "/static/logo.[hash].png"
25+
26+
export default = () => <img src={logo} />;
27+
```
28+
29+
也可以使用**路径别名**来引用：
30+
31+
```tsx
32+
import logo from '@/assets/logo.png';
33+
34+
console.log(logo); // "/static/logo.[hash].png"
35+
36+
export default = () => <img src={logo} />;
37+
```
38+
39+
在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 会将产物视为需要被其他打包工具再次消费的中间产物，会将源文件转化为一个 JS 文件和一个根据 [output.distPath](/config/rsbuild/output#outputdistpath) 输出的静态资源文件，用于保留对静态资源的 `import` 语句。
40+
41+
import { Tabs, Tab } from '@theme';
42+
43+
<Tabs>
44+
<Tab label="dist/index.mjs">
45+
46+
```tsx
47+
import logo from './assets/logo.mjs';
48+
49+
console.log(logo);
50+
```
51+
52+
</Tab>
53+
<Tab label="dist/assets/logo.mjs">
54+
55+
```tsx
56+
import logo_rslib_entry_namespaceObject from '../static/svg/logo.svg';
57+
export { logo_rslib_entry_namespaceObject as default };
58+
```
59+
60+
</Tab>
61+
</Tabs>
62+
63+
## 在 CSS 文件中引用
64+
65+
在 CSS 文件中，可以引用相对路径下的静态资源：
66+
67+
```css title="src/index.css"
68+
.logo {
69+
background-image: url('./assets/logo.png');
70+
}
71+
```
72+
73+
也支持使用**路径别名**来引用：
74+
75+
```css title="src/index.css"
76+
.logo {
77+
background-image: url('@/assets/logo.png');
78+
}
79+
```
80+
81+
在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 会将产物视为需要被其他打包工具再次消费的中间产物，会通过设置 [output.assetPrefix](/config/rsbuild/output#outputassetprefix) 为 `"auto"` 使 CSS 产物中保留相对引用路径。
82+
83+
```css title="dist/index.css"
84+
.logo {
85+
background-image: url('./static/image/logo.png');
86+
}
87+
```
88+
89+
90+
如果需要在 CSS 文件中引用绝对路径下的静态资源：
91+
92+
```css
93+
@font-face {
94+
font-family: DingTalk;
95+
src: url('/image/font/foo.ttf');
96+
}
97+
```
98+
99+
默认情况下，Rslib 内置的 `css-loader` 会解析 `url()` 中的绝对路径并寻找指定的模块。如果你希望跳过绝对路径的解析，可以配置 [`tools.cssLoader`](/config/rsbuild/tools#toolscssloader) 来过滤指定的路径，被过滤的路径将被原样保留在代码中。
100+
101+
```ts
102+
export default {
103+
tools: {
104+
cssLoader: {
105+
url: {
106+
filter: (url) => {
107+
if (/\/image\/font/.test(url)) {
108+
return false;
109+
}
110+
return true;
111+
},
112+
},
113+
},
114+
},
115+
};
116+
```
117+
118+
## 静态资源内联
119+
120+
在开发组件库场景，这种会被其他打包工具再次消费的中间产物时，一般不会内联静态资源，交给应用侧的构建工具处理和优化。
121+
122+
自动内联的体积阈值可以通过 [output.dataUriLimit](/config/rsbuild/output#outputdataurilimit) 配置项修改。在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 默认会将 `output.dataUriLimit` 设置为 `0`，不内联任何静态资源。
123+
124+
## 构建产物目录
125+
126+
当静态资源被引用后，会自动被输出到构建产物的目录下，你可以：
127+
128+
- 通过 [output.filename](/config/rsbuild/output#outputfilename) 来修改产物的文件名。
129+
- 通过 [output.distPath](/config/rsbuild/output#outputdistpath) 来修改产物的输出路径。
130+
131+
## 类型声明
132+
133+
当你在 TypeScript 代码中引用静态资源时，TypeScript 可能会提示该模块缺少类型定义：
134+
135+
```
136+
TS2307: Cannot find module './logo.png' or its corresponding type declarations.
137+
```
138+
139+
此时你需要为静态资源添加类型声明文件，请在项目中创建 `src/env.d.ts` 文件，并添加相应的类型声明。
140+
141+
- 方法一：如果项目里安装了 `@rslib/core` 包，你可以直接引用 `@rslib/core` 提供的**预设类型**：
142+
143+
```ts
144+
/// <reference types="@rslib/core/types" />
145+
```
146+
147+
- 方法二：手动添加需要的类型声明：
148+
149+
```ts title="src/env.d.ts"
150+
// 以 png 图片为例
151+
declare module '*.png' {
152+
const url: string;
153+
export default url;
154+
}
155+
```
156+
157+
添加类型声明后，如果依然存在上述错误提示，请尝试重启当前 IDE，或者调整 `env.d.ts` 所在的目录，使 TypeScript 能够正确识别类型定义。
158+
159+
## 扩展静态资源类型
160+
161+
如果 Rslib 内置的静态资源类型不能满足你的需求，可以通过以下方式扩展额外的静态资源类型。
162+
163+
### 使用 `source.assetsInclude`
164+
165+
通过 [source.assetsInclude](/config/rsbuild/source#sourceassetsinclude) 配置项，你可以指定需要被视为静态资源的额外文件类型。
166+
167+
```ts title="rslib.config.ts"
168+
export default {
169+
source: {
170+
assetsInclude: /\.pdf$/,
171+
},
172+
};
173+
```
174+
175+
添加以上配置后，你就可以在代码里引用 `*.pdf` 文件了，比如：
176+
177+
```js
178+
import myFile from './static/myFile.pdf';
179+
180+
console.log(myFile); // "/static/assets/myFile.[hash].pdf"
181+
```
182+
183+
### 使用 `tools.rspack`
184+
185+
可以通过 [tools.rspack](/config/rsbuild/tools#toolsrspack) 来修改内置的 Rspack 配置，并添加自定义的静态资源处理规则。
186+
187+
比如，把 `*.pdf` 文件当做静态资源输出到产物目录，可以添加以下配置：
188+
189+
```ts title="rslib.config.ts"
190+
export default {
191+
tools: {
192+
rspack(config, { addRules }) {
193+
addRules([
194+
{
195+
test: /\.pdf$/,
196+
// 将资源转换为单独的文件，并且导出产物地址
197+
type: 'asset/resource',
198+
},
199+
]);
200+
},
201+
},
202+
};
203+
```
204+
205+
关于 asset modules 的更多介绍，请参考 [Rspack - Asset modules](https://rspack.dev/guide/features/asset-module)。

‎website/docs/zh/guide/advanced/svgr-files.mdx‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# 引用 SVGR
2+
3+
默认情况下，Rslib 会将 SVG 图片当作静态资源处理。
4+
5+
通过添加 [@rsbuild/plugin-svgr](https://rsbuild.dev/zh/plugins/list/plugin-svgr) 插件，Rslib 支持调用 [SVGR](https://react-svgr.com/)，将 SVG 图片转换为一个 React 组件使用。
6+
7+
## 快速开始
8+
9+
### 安装插件
10+
11+
你可以通过如下的命令安装插件:
12+
13+
import { PackageManagerTabs } from '@theme';
14+
15+
<PackageManagerTabs command="add @rsbuild/plugin-svgr -D" />
16+
17+
### 注册插件
18+
19+
你可以在 `rslib.config.ts` 文件中注册插件：
20+
21+
```ts title="rslib.config.ts"
22+
import { pluginSvgr } from '@rsbuild/plugin-svgr';
23+
24+
export default {
25+
plugins: [pluginSvgr()],
26+
};
27+
```
28+
29+
## 示例
30+
31+
## Bundle 模式
32+
33+
在 Bundle 模式下，支持 [Rsbuild SVGR 插件](https://rsbuild.dev/zh/plugins/list/plugin-svgr) 下的所有用法，唯一的区别是当以 URL 形式使用 SVG 文件时，Rslib 会按照 [引用静态资源](/guide/advanced/static-assets) 在产物中对应保留静态资源的 `import` 语句。
34+
35+
下面是一个使用示例：
36+
37+
```jsx title="App.jsx"
38+
import Logo from './logo.svg?react';
39+
40+
export const App = () => <Logo />;
41+
```
42+
43+
如果导入的路径不包含 `?react` 后缀，那么 SVG 会被当做普通的静态资源来处理，保留对静态资源的 `import` 语句。
44+
45+
```js
46+
import logoURL from './static/logo.svg';
47+
48+
console.log(logoURL);
49+
```
50+
51+
## Bundleless 模式
52+
53+
在 Bundleless 模式下，由于每个文件都是独立经过代码转换，因此不支持 `?react` 和 `?url` 的引用形式，但支持下面两种使用形式：
54+
55+
### 具名导入
56+
57+
`@rsbuild/plugin-svgr` 支持具名导入 `ReactComponent` 来使用 SVGR，你需要设置 [svgrOptions.exportType](https://rsbuild.dev/zh/plugins/list/plugin-svgr#svgroptionsexporttype) 为 `'named'`：
58+
59+
```js
60+
pluginSvgr({
61+
svgrOptions: {
62+
exportType: 'named',
63+
},
64+
});
65+
```
66+
67+
```jsx title="App.jsx"
68+
import { ReactComponent as Logo } from './logo.svg';
69+
70+
export const App = () => <Logo />;
71+
```
72+
73+
所有的 `.svg` 文件都会被转换成 React 组件，你可以通过设置 [exclude](https://rsbuild.dev/zh/plugins/list/plugin-svgr#exclude) 来排除不需要转换的文件。
74+
75+
### 混合导入
76+
77+
如果你的库中同时存在 url 和 React 组件两种引入形式，你也可以通过混合导入的方式来使用：
78+
79+
```ts
80+
pluginSvgr({
81+
mixedImport: true,
82+
svgrOptions: {
83+
exportType: 'named',
84+
},
85+
});
86+
```
87+
88+
此时引用的 SVG 文件会同时导出 URL 和 React 组件：
89+
90+
```js
91+
import logoUrl, { ReactComponent as Logo } from './logo.svg';
92+
93+
console.log(logoUrl); // -> string
94+
console.log(Logo); // -> React component
95+
```
96+
97+
更多信息可以参考 [mixedImport](https://rsbuild.dev/zh/plugins/list/plugin-svgr#mixedimport) 选项。

‎website/docs/zh/guide/solution/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
## Browser target
66

7-
开发在浏览器中运行的库时，可以将其打包为 [ESM](/guide/basic/output-format#esm--cjs) 和 [CJS](/guide/basic/output-format#esm--cjs) 格式，用于与 app 的 bundler 集成。将包 [conditional-exports](https://nodejs.org/api/packages.html#conditional-exports) 配置为 ESM 输出可以更好地进行 treeshaking。此外，你可以创建 [UMD](/guide/basic/output-format#umd) 格式输出以供浏览器直接使用，甚至可以生成 [模块联邦](/guide/advanced/module-federation) 格式以供其他应用程序动态加载。根据目标浏览器支持配置 [Browserslist](https://rsbuild.dev/zh/guide/advanced/browserslist)以确定输出的降级语法，或添加 [polyfill](/guide/advanced/output-compatibility) 用于兼容 API。
7+
开发在浏览器中运行的库时，可以将其打包为 [ESM](/guide/basic/output-format#esm--cjs) 和 [CJS](/guide/basic/output-format#esm--cjs) 格式，用于与 app 的打包工具集成。将包 [conditional-exports](https://nodejs.org/api/packages.html#conditional-exports) 配置为 ESM 输出可以更好地进行 treeshaking。此外，你可以创建 [UMD](/guide/basic/output-format#umd) 格式输出以供浏览器直接使用，甚至可以生成 [模块联邦](/guide/advanced/module-federation) 格式以供其他应用程序动态加载。根据目标浏览器支持配置 [Browserslist](https://rsbuild.dev/zh/guide/advanced/browserslist)以确定输出的降级语法，或添加 [polyfill](/guide/advanced/output-compatibility) 用于兼容 API。
88

99
发布到 npm 时，你可以选择不压缩代码或[压缩代码](/config/rsbuild/output#outputminify)，同时提供[sourcemap](/config/rsbuild/output#outputsourcema) 以增强库使用者的调试体验。样式上，可以使用 CSS 或 CSS 预处理器，如 Sass、Less 或 Stylus 等，或使用 PostCSS 用于 CSS 后处理。 Tailwind CSS 等工具也可以帮助你构建样式，也可以使用 CSS Modules。
1010

0 commit comments

Comments
 (0)