From e3565ea244c43a38a8c64313b550b495cd242b58 Mon Sep 17 00:00:00 2001 From: SoonIter Date: Thu, 13 Feb 2025 18:26:11 +0800 Subject: [PATCH 01/13] docs: update the doc --- .../asset/__snapshots__/index.test.ts.snap | 9 +- tests/integration/asset/json/src/index.js | 5 +- website/docs/zh/config/rsbuild/output.mdx | 8 + website/docs/zh/guide/advanced/_meta.json | 3 + website/docs/zh/guide/advanced/json-files.mdx | 101 ++++++ .../docs/zh/guide/advanced/static-assets.mdx | 295 ++++++++++++++++++ website/docs/zh/guide/advanced/svgr-files.mdx | 105 +++++++ website/docs/zh/guide/solution/index.mdx | 2 +- 8 files changed, 524 insertions(+), 4 deletions(-) create mode 100644 website/docs/zh/guide/advanced/json-files.mdx create mode 100644 website/docs/zh/guide/advanced/static-assets.mdx create mode 100644 website/docs/zh/guide/advanced/svgr-files.mdx diff --git a/tests/integration/asset/__snapshots__/index.test.ts.snap b/tests/integration/asset/__snapshots__/index.test.ts.snap index 800bcb601..0e589033d 100644 --- a/tests/integration/asset/__snapshots__/index.test.ts.snap +++ b/tests/integration/asset/__snapshots__/index.test.ts.snap @@ -13,7 +13,14 @@ export { draft_rslib_entry_namespaceObject as default }; `; exports[`use json 1`] = ` -"JSON.parse('{"foo":1,"bar":["2"]}'); +"var data_namespaceObject = { + R: 1, + K: [ + "2" + ] +}; +console.log(data_namespaceObject.R); +console.log(data_namespaceObject.K); " `; diff --git a/tests/integration/asset/json/src/index.js b/tests/integration/asset/json/src/index.js index c14c58d2a..fff715a3c 100644 --- a/tests/integration/asset/json/src/index.js +++ b/tests/integration/asset/json/src/index.js @@ -1,3 +1,4 @@ -import a from './assets/data.json'; +import { bar, foo } from './assets/data.json'; -a; +console.log(foo); +console.log(bar); diff --git a/website/docs/zh/config/rsbuild/output.mdx b/website/docs/zh/config/rsbuild/output.mdx index 75e76d398..f9c216aff 100644 --- a/website/docs/zh/config/rsbuild/output.mdx +++ b/website/docs/zh/config/rsbuild/output.mdx @@ -4,6 +4,12 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge'; 与构建产物相关的选项。 +## output.assetPrefix + +使用该选项设置静态资源的 URL 前缀，比如设置为 CDN 地址。 + +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 默认会将 `output.assetPrefix` 设置为 `"auto"`。 + ## output.charset 指定输出文件的 [字符编码](https://developer.mozilla.org/en-US/docs/Glossary/Character_encoding)，以确保它们在不同的环境中能够正确显示。 @@ -24,6 +30,8 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge'; 设置图片、字体、媒体等静态资源被自动内联为 base64 的体积阈值。 +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 默认会将 `output.dataUriLimit` 设置为 `0`，不内联任何静态资源，以便于应用侧的构建工具处理和优化。 + ## output.distPath 设置构建产物的输出目录，Rsbuild 会根据产物的类型输出到对应的子目录下。 diff --git a/website/docs/zh/guide/advanced/_meta.json b/website/docs/zh/guide/advanced/_meta.json index c9bbf4c49..58d2ca213 100644 --- a/website/docs/zh/guide/advanced/_meta.json +++ b/website/docs/zh/guide/advanced/_meta.json @@ -2,6 +2,9 @@ "third-party-deps", "output-compatibility", "dts", + "static-assets", + "svgr-files", + "json-files", "module-federation", "storybook" ] diff --git a/website/docs/zh/guide/advanced/json-files.mdx b/website/docs/zh/guide/advanced/json-files.mdx new file mode 100644 index 000000000..0c2041187 --- /dev/null +++ b/website/docs/zh/guide/advanced/json-files.mdx @@ -0,0 +1,101 @@ +# 引用 JSON 文件 + +Rslib 支持在代码中引用 JSON 文件。 + +## JSON 文件 + +你可以直接在 JavaScript 文件中引用 JSON 文件。 + +### 默认引用 + +```json title="example.json" +{ + "name": "foo", + "items": [1, 2] +} +``` + +```js title="index.js" +import example from './example.json'; + +console.log(example.name); // 'foo'; +console.log(example.items); // [1, 2]; +``` + +:::warning + +在 Bundle 模式下，JSON 文件支持默认引用和具名引用。 + +在 Bundleless 模式下，JSON 文件仅支持具名引用。 + +::: + +### 具名引用 + +Rslib 同样支持通过 named import 来引用 JSON 文件： + +下面是一个使用示例，假设源码如下： + +import { Tabs, Tab } from '@theme'; + + + +```js +import { name } from './example.json'; + +console.log(name); // 'foo'; + +```` + + +```json title="example.json" +{ + "name": "foo", + "items": [1, 2] +} +```` + + + + +会根据配置文件中的 [产物结构](/guide/basic/output-structure) 配置，打包出如下产物： + + + + + +```tsx +var example_namespaceObject = { + "name": "foo" +}; +console.log(example_namespaceObject.name); +``` + + + + + + + + + + +```tsx +import * as example from './example.js'; + +console.log(example.name); +``` + + + +```tsx +var example_namespaceObject = JSON.parse('{"name":"foo","items":[1,2]}'); +var __webpack_exports__items = example_namespaceObject.items; +var __webpack_exports__name = example_namespaceObject.name; +export { __webpack_exports__items as items, __webpack_exports__name as name }; +``` + + + + + diff --git a/website/docs/zh/guide/advanced/static-assets.mdx b/website/docs/zh/guide/advanced/static-assets.mdx new file mode 100644 index 000000000..21b0ff7a4 --- /dev/null +++ b/website/docs/zh/guide/advanced/static-assets.mdx @@ -0,0 +1,295 @@ +# 引用静态资源 + +Rslib 支持在代码中引用图片、字体、音频、视频等类型的静态资源。 + +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为需要被其他打包工具再次消费的中间产物。 + +## 静态资源格式 + +以下是 Rslib 默认支持的静态资源格式： + +- **图片**：png、jpg、jpeg、gif、svg、bmp、webp、ico、apng、avif、tif、tiff、jfif、pjpeg、pjp、cur。 +- **字体**：woff、woff2、eot、ttf、otf、ttc。 +- **音频**：mp3、wav、flac、aac、m4a、opus。 +- **视频**：mp4、webm、ogg、mov。 + +如果你需要引用其他格式的静态资源，请参考 [扩展静态资源类型](#扩展静态资源类型)。 + +## 在 JS 文件中引用 + +在 JS 文件中，可以直接通过 `import` 的方式引用相对路径下的静态资源： + +```tsx +// 引用 src/assets 目录下的 logo.png 图片 +import logo from './assets/logo.png'; + +console.log(logo); // "/static/logo.[hash].png" + +export default = () => ; +``` + +也可以使用**路径别名**来引用： + +```tsx +import logo from '@/assets/logo.png'; + +console.log(logo); // "/static/logo.[hash].png" + +export default = () => ; +``` + +Rslib 会将源文件转化为一个 JS 文件和一个根据 [output.distPath](/config/rsbuild/output#outputdistpath) 输出的静态资源文件，用于保留对静态资源的 `import` 语句。 + +下面是一个使用示例，假设源码如下： + +import { Tabs, Tab } from '@theme'; + + + +```tsx +import logo from './assets/logo.svg'; + +console.log(logo); + +```` + + + + + + +会根据配置文件中的 [产物结构](/guide/basic/output-structure) 配置，打包出如下产物： + + + + + +```tsx +import logo_rslib_entry_namespaceObject from './static/svg/logo.svg'; + +console.log(logo_rslib_entry_namespaceObject) +```` + + + + + + + + + + + + + +```tsx +import logo from './assets/logo.mjs'; + +console.log(logo); +``` + + + + +```tsx +import logo_rslib_entry_namespaceObject from '../static/svg/logo.svg'; +export { logo_rslib_entry_namespaceObject as default }; +``` + + + + + + + + + + +## 在 CSS 文件中引用 + +在 CSS 文件中，可以引用相对路径下的静态资源： + +```css title="src/index.css" +.logo { + background-image: url('./assets/logo.png'); +} +``` + +也支持使用**路径别名**来引用： + +```css title="src/index.css" +.logo { + background-image: url('@/assets/logo.png'); +} +``` + +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为需要被其他打包工具再次消费的中间产物，会通过设置 [output.assetPrefix](/config/rsbuild/output#outputassetprefix) 为 `"auto"` 来使 CSS 产物中保留相对引用路径。 + +下面是一个使用示例，假设源码如下： + + + +```css +.logo { + background-image: url('./assets/logo.png'); +} +``` + + + + + + +会打包出如下产物： + + + + + +```css +.logo { + background-image: url('./static/image/logo.png'); +} +``` + + + + + + + + + +--- + +### 在 CSS 中忽略某些文件引用 + +如果需要在 CSS 文件中引用绝对路径下的静态资源： + +```css +@font-face { + font-family: DingTalk; + src: url('/image/font/foo.ttf'); +} +``` + +默认情况下，Rslib 内置的 `css-loader` 会解析 `url()` 中的绝对路径并寻找指定的模块。如果你希望跳过绝对路径的解析，可以配置 [`tools.cssLoader`](/config/rsbuild/tools#toolscssloader) 来过滤指定的路径，被过滤的路径将被原样保留在代码中。 + +```ts +export default { + tools: { + cssLoader: { + url: { + filter: (url) => { + if (/\/image\/font/.test(url)) { + return false; + } + return true; + }, + }, + }, + }, +}; +``` + +## 静态资源内联 + +在开发组件库这种会被其他打包工具再次消费的中间产物时，一般不会内联静态资源，交给应用侧的构建工具处理和优化。 + +自动内联的体积阈值可以通过 [output.dataUriLimit](/config/rsbuild/output#outputdataurilimit) 配置项修改，在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 默认会将 `output.dataUriLimit` 设置为 `0`，不内联任何静态资源。 + +## 构建产物目录 + +当静态资源被引用后，会自动被输出到构建产物的目录下，你可以： + +- 通过 [output.filename](/config/rsbuild/output#outputfilename) 来修改产物的文件名。 +- 通过 [output.distPath](/config/rsbuild/output#outputdistpath) 来修改产物的输出路径。 + +## 类型声明 + +当你在 TypeScript 代码中引用静态资源时，TypeScript 可能会提示该模块缺少类型定义： + +``` +TS2307: Cannot find module './logo.png' or its corresponding type declarations. +``` + +此时你需要为静态资源添加类型声明文件，请在项目中创建 `src/env.d.ts` 文件，并添加相应的类型声明。 + +- 方法一：如果项目里安装了 `@rslib/core` 包，你可以直接引用 `@rslib/core` 提供的**预设类型**： + +```ts +/// +``` + +- 方法二：手动添加需要的类型声明： + +```ts title="src/env.d.ts" +// 以 png 图片为例 +declare module '*.png' { + const url: string; + export default url; +} +``` + +添加类型声明后，如果依然存在上述错误提示，请尝试重启当前 IDE，或者调整 `env.d.ts` 所在的目录，使 TypeScript 能够正确识别类型定义。 + +## 扩展静态资源类型 + +如果 Rslib 内置的静态资源类型不能满足你的需求，可以通过以下方式扩展额外的静态资源类型。 + +### 使用 `source.assetsInclude` + +通过 [source.assetsInclude](/config/rsbuild/source#sourceassetsinclude) 配置项，你可以指定需要被视为静态资源的额外文件类型。 + +```ts title="rslib.config.ts" +export default { + source: { + assetsInclude: /\.pdf$/, + }, +}; +``` + +添加以上配置后，你就可以在代码里引用 `*.pdf` 文件了，比如： + +```js +import myFile from './static/myFile.pdf'; + +console.log(myFile); // "/static/assets/myFile.[hash].pdf" +``` + +### 使用 `tools.rspack` + +可以通过 [tools.rspack](/config/rsbuild/tools#toolsrspack) 来修改内置的 Rspack 配置，并添加自定义的静态资源处理规则。 + +比如，把 `*.pdf` 文件当做静态资源输出到产物目录，可以添加以下配置： + +```ts title="rslib.config.ts" +export default { + tools: { + rspack(config, { addRules }) { + addRules([ + { + test: /\.pdf$/, + // 将资源转换为单独的文件，并且保留 import 语句 + type: 'asset/resource', + generator: { + importMode: 'preserve', + }, + }, + ]); + }, + }, +}; +``` + +关于 asset modules 的更多介绍，请参考 [Rspack - Asset modules](https://rspack.dev/guide/features/asset-module)。 diff --git a/website/docs/zh/guide/advanced/svgr-files.mdx b/website/docs/zh/guide/advanced/svgr-files.mdx new file mode 100644 index 000000000..1f2be6671 --- /dev/null +++ b/website/docs/zh/guide/advanced/svgr-files.mdx @@ -0,0 +1,105 @@ +# 引用 SVGR + +默认情况下，Rslib 会将 SVG 图片当作静态资源处理。 + +通过添加 [@rsbuild/plugin-svgr](https://rsbuild.dev/zh/plugins/list/plugin-svgr) 插件，Rslib 支持调用 [SVGR](https://react-svgr.com/)，将 SVG 图片转换为一个 React 组件使用。 + +## 快速开始 + +### 安装插件 + +你可以通过如下的命令安装插件: + +import { PackageManagerTabs } from '@theme'; + + + +### 注册插件 + +你可以在 `rslib.config.ts` 文件中注册插件： + +```ts title="rslib.config.ts" +import { pluginSvgr } from '@rsbuild/plugin-svgr'; + +export default { + plugins: [pluginSvgr()], +}; +``` + +## 示例 + +### Bundle 模式 + +在 Bundle 模式下，支持 [Rsbuild SVGR 插件](https://rsbuild.dev/zh/plugins/list/plugin-svgr) 下的所有用法，唯一的区别是当以 URL 形式使用 SVG 文件时，Rslib 会按照 [引用静态资源](/zh/guide/advanced/static-assets) 在产物中对应保留静态资源的 `import` 语句。 + +下面是一个使用示例： + +```jsx title="App.jsx" +import Logo from './logo.svg?react'; + +export const App = () => ; +``` + +如果导入的路径不包含 `?react` 后缀，那么 SVG 会被当做普通的静态资源来处理，保留对静态资源的 `import` 语句。 + +```js +import logoURL from './static/logo.svg'; + +console.log(logoURL); +``` + +`@rsbuild/plugin-svgr` 也支持默认导入和混合导入等用法： + +- 通过 [svgrOptions.exportType](https://rsbuild.dev/zh/plugins/list/plugin-svgr#svgroptionsexporttype) 设置为 `'default'` 来启用默认导入。 +- 通过 [mixedImport](https://rsbuild.dev/zh/plugins/list/plugin-svgr#mixedimport) 选项来启用混合导入，从而同时使用默认导入和具名导入。 + +### Bundleless 模式 + +在 Bundleless 模式下，由于每个文件都是独立经过代码转换，因此不支持 `?react` 和 `?url` 的引用形式，但支持下面两种使用形式： + +#### 具名导入 + +`@rsbuild/plugin-svgr` 支持具名导入 `ReactComponent` 来使用 SVGR，你需要设置 [svgrOptions.exportType](https://rsbuild.dev/zh/plugins/list/plugin-svgr#svgroptionsexporttype) 为 `'named'`： + +```js +pluginSvgr({ + svgrOptions: { + exportType: 'named', + }, +}); +``` + +```jsx title="App.jsx" +import { ReactComponent as Logo } from './logo.svg'; + +export const App = () => ; +``` + +所有的 `.svg` 文件都会被转换成 React 组件，此时你可以： + +- 通过设置 [exclude](https://rsbuild.dev/zh/plugins/list/plugin-svgr#exclude) 来排除不需要转换的文件。 +- 通过 [svgrOptions.exportType](https://rsbuild.dev/zh/plugins/list/plugin-svgr#svgroptionsexporttype) 设置为 `'default'` 来修改为默认导出。 + +#### 混合导入 + +如果你的库中同时存在 url 和 React 组件两种引入形式，你也可以通过混合导入的方式来使用： + +```ts +pluginSvgr({ + mixedImport: true, + svgrOptions: { + exportType: 'named', + }, +}); +``` + +此时引用的 SVG 文件会同时导出 URL 和 React 组件： + +```js +import logoUrl, { ReactComponent as Logo } from './logo.svg'; + +console.log(logoUrl); // -> string +console.log(Logo); // -> React component +``` + +更多信息可以参考 [mixedImport](https://rsbuild.dev/zh/plugins/list/plugin-svgr#mixedimport) 选项。 diff --git a/website/docs/zh/guide/solution/index.mdx b/website/docs/zh/guide/solution/index.mdx index 23d3c33d4..a3e0e7a9b 100644 --- a/website/docs/zh/guide/solution/index.mdx +++ b/website/docs/zh/guide/solution/index.mdx @@ -4,7 +4,7 @@ ## Browser target -开发在浏览器中运行的库时，可以将其打包为 [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。 +开发在浏览器中运行的库时，可以将其打包为 [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。 发布到 npm 时，你可以选择不压缩代码或[压缩代码](/config/rsbuild/output#outputminify)，同时提供[sourcemap](/config/rsbuild/output#outputsourcema) 以增强库使用者的调试体验。样式上，可以使用 CSS 或 CSS 预处理器，如 Sass、Less 或 Stylus 等，或使用 PostCSS 用于 CSS 后处理。 Tailwind CSS 等工具也可以帮助你构建样式，也可以使用 CSS Modules。 From 4f0fae6c3cabfe4d7ee85f0251ee25affea4833d Mon Sep 17 00:00:00 2001 From: SoonIter Date: Thu, 13 Feb 2025 18:30:10 +0800 Subject: [PATCH 02/13] docs: update the doc --- website/docs/zh/guide/advanced/json-files.mdx | 8 +++++--- website/docs/zh/guide/advanced/static-assets.mdx | 10 +++++++--- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/website/docs/zh/guide/advanced/json-files.mdx b/website/docs/zh/guide/advanced/json-files.mdx index 0c2041187..101bd6459 100644 --- a/website/docs/zh/guide/advanced/json-files.mdx +++ b/website/docs/zh/guide/advanced/json-files.mdx @@ -40,20 +40,22 @@ import { Tabs, Tab } from '@theme'; + ```js import { name } from './example.json'; console.log(name); // 'foo'; +``` -```` -```json title="example.json" + +```json { "name": "foo", "items": [1, 2] } -```` +``` diff --git a/website/docs/zh/guide/advanced/static-assets.mdx b/website/docs/zh/guide/advanced/static-assets.mdx index 21b0ff7a4..222de21aa 100644 --- a/website/docs/zh/guide/advanced/static-assets.mdx +++ b/website/docs/zh/guide/advanced/static-assets.mdx @@ -46,12 +46,13 @@ import { Tabs, Tab } from '@theme'; + ```tsx import logo from './assets/logo.svg'; console.log(logo); +``` -```` @@ -64,11 +65,12 @@ console.log(logo); + ```tsx import logo_rslib_entry_namespaceObject from './static/svg/logo.svg'; -console.log(logo_rslib_entry_namespaceObject) -```` +console.log(logo_rslib_entry_namespaceObject); +``` @@ -129,11 +131,13 @@ export { logo_rslib_entry_namespaceObject as default }; + ```css .logo { background-image: url('./assets/logo.png'); } ``` + Date: Thu, 13 Feb 2025 18:37:33 +0800 Subject: [PATCH 03/13] docs: complete zh --- website/docs/zh/guide/advanced/static-assets.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/website/docs/zh/guide/advanced/static-assets.mdx b/website/docs/zh/guide/advanced/static-assets.mdx index 222de21aa..40905d559 100644 --- a/website/docs/zh/guide/advanced/static-assets.mdx +++ b/website/docs/zh/guide/advanced/static-assets.mdx @@ -2,8 +2,6 @@ Rslib 支持在代码中引用图片、字体、音频、视频等类型的静态资源。 -在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为需要被其他打包工具再次消费的中间产物。 - ## 静态资源格式 以下是 Rslib 默认支持的静态资源格式： @@ -38,7 +36,7 @@ console.log(logo); // "/static/logo.[hash].png" export default = () => ; ``` -Rslib 会将源文件转化为一个 JS 文件和一个根据 [output.distPath](/config/rsbuild/output#outputdistpath) 输出的静态资源文件，用于保留对静态资源的 `import` 语句。 +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物。Rslib 会在代码转换时将源文件转化为一个 JS 文件和一个根据 [output.distPath](/config/rsbuild/output#outputdistpath) 输出的静态资源文件，用于保留对静态资源的 `import` 语句。 下面是一个使用示例，假设源码如下： @@ -125,7 +123,7 @@ export { logo_rslib_entry_namespaceObject as default }; } ``` -在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为需要被其他打包工具再次消费的中间产物，会通过设置 [output.assetPrefix](/config/rsbuild/output#outputassetprefix) 为 `"auto"` 来使 CSS 产物中保留相对引用路径。 +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物。Rslib 会通过设置 [output.assetPrefix](/config/rsbuild/output#outputassetprefix) 为 `"auto"` 来使 CSS 产物中保留相对引用路径。 下面是一个使用示例，假设源码如下： From cc5ff2ef4c224a24603256dda3a8bb19cc4aa5ed Mon Sep 17 00:00:00 2001 From: SoonIter Date: Thu, 13 Feb 2025 19:14:18 +0800 Subject: [PATCH 04/13] docs: complete en --- website/docs/en/guide/advanced/_meta.json | 3 + website/docs/en/guide/advanced/json-files.mdx | 103 ++++++ .../docs/en/guide/advanced/static-assets.mdx | 297 ++++++++++++++++++ website/docs/en/guide/advanced/svgr-files.mdx | 105 +++++++ 4 files changed, 508 insertions(+) create mode 100644 website/docs/en/guide/advanced/json-files.mdx create mode 100644 website/docs/en/guide/advanced/static-assets.mdx create mode 100644 website/docs/en/guide/advanced/svgr-files.mdx diff --git a/website/docs/en/guide/advanced/_meta.json b/website/docs/en/guide/advanced/_meta.json index c9bbf4c49..58d2ca213 100644 --- a/website/docs/en/guide/advanced/_meta.json +++ b/website/docs/en/guide/advanced/_meta.json @@ -2,6 +2,9 @@ "third-party-deps", "output-compatibility", "dts", + "static-assets", + "svgr-files", + "json-files", "module-federation", "storybook" ] diff --git a/website/docs/en/guide/advanced/json-files.mdx b/website/docs/en/guide/advanced/json-files.mdx new file mode 100644 index 000000000..101bd6459 --- /dev/null +++ b/website/docs/en/guide/advanced/json-files.mdx @@ -0,0 +1,103 @@ +# 引用 JSON 文件 + +Rslib 支持在代码中引用 JSON 文件。 + +## JSON 文件 + +你可以直接在 JavaScript 文件中引用 JSON 文件。 + +### 默认引用 + +```json title="example.json" +{ + "name": "foo", + "items": [1, 2] +} +``` + +```js title="index.js" +import example from './example.json'; + +console.log(example.name); // 'foo'; +console.log(example.items); // [1, 2]; +``` + +:::warning + +在 Bundle 模式下，JSON 文件支持默认引用和具名引用。 + +在 Bundleless 模式下，JSON 文件仅支持具名引用。 + +::: + +### 具名引用 + +Rslib 同样支持通过 named import 来引用 JSON 文件： + +下面是一个使用示例，假设源码如下： + +import { Tabs, Tab } from '@theme'; + + + + +```js +import { name } from './example.json'; + +console.log(name); // 'foo'; +``` + + + + +```json +{ + "name": "foo", + "items": [1, 2] +} +``` + + + + +会根据配置文件中的 [产物结构](/guide/basic/output-structure) 配置，打包出如下产物： + + + + + +```tsx +var example_namespaceObject = { + "name": "foo" +}; +console.log(example_namespaceObject.name); +``` + + + + + + + + + + +```tsx +import * as example from './example.js'; + +console.log(example.name); +``` + + + +```tsx +var example_namespaceObject = JSON.parse('{"name":"foo","items":[1,2]}'); +var __webpack_exports__items = example_namespaceObject.items; +var __webpack_exports__name = example_namespaceObject.name; +export { __webpack_exports__items as items, __webpack_exports__name as name }; +``` + + + + + diff --git a/website/docs/en/guide/advanced/static-assets.mdx b/website/docs/en/guide/advanced/static-assets.mdx new file mode 100644 index 000000000..4e0468dac --- /dev/null +++ b/website/docs/en/guide/advanced/static-assets.mdx @@ -0,0 +1,297 @@ +# Import static assets + +Rslib 支持在代码中引用图片、字体、音频、视频等类型的静态资源。 + +## 静态资源格式 + +以下是 Rslib 默认支持的静态资源格式： + +- **图片**：png、jpg、jpeg、gif、svg、bmp、webp、ico、apng、avif、tif、tiff、jfif、pjpeg、pjp、cur。 +- **字体**：woff、woff2、eot、ttf、otf、ttc。 +- **音频**：mp3、wav、flac、aac、m4a、opus。 +- **视频**：mp4、webm、ogg、mov。 + +如果你需要引用其他格式的静态资源，请参考 [扩展静态资源类型](#扩展静态资源类型)。 + +## 在 JS 文件中引用 + +在 JS 文件中，可以直接通过 `import` 的方式引用相对路径下的静态资源： + +```tsx +// 引用 src/assets 目录下的 logo.png 图片 +import logo from './assets/logo.png'; + +console.log(logo); // "/static/logo.[hash].png" + +export default = () => ; +``` + +也可以使用**路径别名**来引用： + +```tsx +import logo from '@/assets/logo.png'; + +console.log(logo); // "/static/logo.[hash].png" + +export default = () => ; +``` + +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物。Rslib 会在代码转换时将源文件转化为一个 JS 文件和一个根据 [output.distPath](/config/rsbuild/output#outputdistpath) 输出的静态资源文件，用于保留对静态资源的 `import` 语句。 + +下面是一个使用示例，假设源码如下： + +import { Tabs, Tab } from '@theme'; + + + + +```tsx +import logo from './assets/logo.svg'; + +console.log(logo); +``` + + + + + + + +会根据配置文件中的 [产物结构](/guide/basic/output-structure) 配置，打包出如下产物： + + + + + + +```tsx +import logo_rslib_entry_namespaceObject from './static/svg/logo.svg'; + +console.log(logo_rslib_entry_namespaceObject); +``` + + + + + + + + + + + + + +```tsx +import logo from './assets/logo.mjs'; + +console.log(logo); +``` + + + + +```tsx +import logo_rslib_entry_namespaceObject from '../static/svg/logo.svg'; +export { logo_rslib_entry_namespaceObject as default }; +``` + + + + + + + + + + +## 在 CSS 文件中引用 + +在 CSS 文件中，可以引用相对路径下的静态资源： + +```css title="src/index.css" +.logo { + background-image: url('./assets/logo.png'); +} +``` + +也支持使用**路径别名**来引用： + +```css title="src/index.css" +.logo { + background-image: url('@/assets/logo.png'); +} +``` + +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物。Rslib 会通过设置 [output.assetPrefix](/config/rsbuild/output#outputassetprefix) 为 `"auto"` 来使 CSS 产物中保留相对引用路径。 + +下面是一个使用示例，假设源码如下： + + + + +```css +.logo { + background-image: url('./assets/logo.png'); +} +``` + + + + + + + +会打包出如下产物： + + + + + +```css +.logo { + background-image: url('./static/image/logo.png'); +} +``` + + + + + + + + + +--- + +### 在 CSS 中忽略某些文件引用 + +如果需要在 CSS 文件中引用绝对路径下的静态资源： + +```css +@font-face { + font-family: DingTalk; + src: url('/image/font/foo.ttf'); +} +``` + +默认情况下，Rslib 内置的 `css-loader` 会解析 `url()` 中的绝对路径并寻找指定的模块。如果你希望跳过绝对路径的解析，可以配置 [`tools.cssLoader`](/config/rsbuild/tools#toolscssloader) 来过滤指定的路径，被过滤的路径将被原样保留在代码中。 + +```ts +export default { + tools: { + cssLoader: { + url: { + filter: (url) => { + if (/\/image\/font/.test(url)) { + return false; + } + return true; + }, + }, + }, + }, +}; +``` + +## 静态资源内联 + +在开发组件库这种会被其他打包工具再次消费的中间产物时，一般不会内联静态资源，交给应用侧的构建工具处理和优化。 + +自动内联的体积阈值可以通过 [output.dataUriLimit](/config/rsbuild/output#outputdataurilimit) 配置项修改，在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 默认会将 `output.dataUriLimit` 设置为 `0`，不内联任何静态资源。 + +## 构建产物目录 + +当静态资源被引用后，会自动被输出到构建产物的目录下，你可以： + +- 通过 [output.filename](/config/rsbuild/output#outputfilename) 来修改产物的文件名。 +- 通过 [output.distPath](/config/rsbuild/output#outputdistpath) 来修改产物的输出路径。 + +## 类型声明 + +当你在 TypeScript 代码中引用静态资源时，TypeScript 可能会提示该模块缺少类型定义： + +``` +TS2307: Cannot find module './logo.png' or its corresponding type declarations. +``` + +此时你需要为静态资源添加类型声明文件，请在项目中创建 `src/env.d.ts` 文件，并添加相应的类型声明。 + +- 方法一：如果项目里安装了 `@rslib/core` 包，你可以直接引用 `@rslib/core` 提供的**预设类型**： + +```ts +/// +``` + +- 方法二：手动添加需要的类型声明： + +```ts title="src/env.d.ts" +// 以 png 图片为例 +declare module '*.png' { + const url: string; + export default url; +} +``` + +添加类型声明后，如果依然存在上述错误提示，请尝试重启当前 IDE，或者调整 `env.d.ts` 所在的目录，使 TypeScript 能够正确识别类型定义。 + +## 扩展静态资源类型 + +如果 Rslib 内置的静态资源类型不能满足你的需求，可以通过以下方式扩展额外的静态资源类型。 + +### 使用 `source.assetsInclude` + +通过 [source.assetsInclude](/config/rsbuild/source#sourceassetsinclude) 配置项，你可以指定需要被视为静态资源的额外文件类型。 + +```ts title="rslib.config.ts" +export default { + source: { + assetsInclude: /\.pdf$/, + }, +}; +``` + +添加以上配置后，你就可以在代码里引用 `*.pdf` 文件了，比如： + +```js +import myFile from './static/myFile.pdf'; + +console.log(myFile); // "/static/assets/myFile.[hash].pdf" +``` + +### 使用 `tools.rspack` + +可以通过 [tools.rspack](/config/rsbuild/tools#toolsrspack) 来修改内置的 Rspack 配置，并添加自定义的静态资源处理规则。 + +比如，把 `*.pdf` 文件当做静态资源输出到产物目录，可以添加以下配置： + +```ts title="rslib.config.ts" +export default { + tools: { + rspack(config, { addRules }) { + addRules([ + { + test: /\.pdf$/, + // 将资源转换为单独的文件，并且保留 import 语句 + type: 'asset/resource', + generator: { + importMode: 'preserve', + }, + }, + ]); + }, + }, +}; +``` + +关于 asset modules 的更多介绍，请参考 [Rspack - Asset modules](https://rspack.dev/guide/features/asset-module)。 diff --git a/website/docs/en/guide/advanced/svgr-files.mdx b/website/docs/en/guide/advanced/svgr-files.mdx new file mode 100644 index 000000000..1f2be6671 --- /dev/null +++ b/website/docs/en/guide/advanced/svgr-files.mdx @@ -0,0 +1,105 @@ +# 引用 SVGR + +默认情况下，Rslib 会将 SVG 图片当作静态资源处理。 + +通过添加 [@rsbuild/plugin-svgr](https://rsbuild.dev/zh/plugins/list/plugin-svgr) 插件，Rslib 支持调用 [SVGR](https://react-svgr.com/)，将 SVG 图片转换为一个 React 组件使用。 + +## 快速开始 + +### 安装插件 + +你可以通过如下的命令安装插件: + +import { PackageManagerTabs } from '@theme'; + + + +### 注册插件 + +你可以在 `rslib.config.ts` 文件中注册插件： + +```ts title="rslib.config.ts" +import { pluginSvgr } from '@rsbuild/plugin-svgr'; + +export default { + plugins: [pluginSvgr()], +}; +``` + +## 示例 + +### Bundle 模式 + +在 Bundle 模式下，支持 [Rsbuild SVGR 插件](https://rsbuild.dev/zh/plugins/list/plugin-svgr) 下的所有用法，唯一的区别是当以 URL 形式使用 SVG 文件时，Rslib 会按照 [引用静态资源](/zh/guide/advanced/static-assets) 在产物中对应保留静态资源的 `import` 语句。 + +下面是一个使用示例： + +```jsx title="App.jsx" +import Logo from './logo.svg?react'; + +export const App = () => ; +``` + +如果导入的路径不包含 `?react` 后缀，那么 SVG 会被当做普通的静态资源来处理，保留对静态资源的 `import` 语句。 + +```js +import logoURL from './static/logo.svg'; + +console.log(logoURL); +``` + +`@rsbuild/plugin-svgr` 也支持默认导入和混合导入等用法： + +- 通过 [svgrOptions.exportType](https://rsbuild.dev/zh/plugins/list/plugin-svgr#svgroptionsexporttype) 设置为 `'default'` 来启用默认导入。 +- 通过 [mixedImport](https://rsbuild.dev/zh/plugins/list/plugin-svgr#mixedimport) 选项来启用混合导入，从而同时使用默认导入和具名导入。 + +### Bundleless 模式 + +在 Bundleless 模式下，由于每个文件都是独立经过代码转换，因此不支持 `?react` 和 `?url` 的引用形式，但支持下面两种使用形式： + +#### 具名导入 + +`@rsbuild/plugin-svgr` 支持具名导入 `ReactComponent` 来使用 SVGR，你需要设置 [svgrOptions.exportType](https://rsbuild.dev/zh/plugins/list/plugin-svgr#svgroptionsexporttype) 为 `'named'`： + +```js +pluginSvgr({ + svgrOptions: { + exportType: 'named', + }, +}); +``` + +```jsx title="App.jsx" +import { ReactComponent as Logo } from './logo.svg'; + +export const App = () => ; +``` + +所有的 `.svg` 文件都会被转换成 React 组件，此时你可以： + +- 通过设置 [exclude](https://rsbuild.dev/zh/plugins/list/plugin-svgr#exclude) 来排除不需要转换的文件。 +- 通过 [svgrOptions.exportType](https://rsbuild.dev/zh/plugins/list/plugin-svgr#svgroptionsexporttype) 设置为 `'default'` 来修改为默认导出。 + +#### 混合导入 + +如果你的库中同时存在 url 和 React 组件两种引入形式，你也可以通过混合导入的方式来使用： + +```ts +pluginSvgr({ + mixedImport: true, + svgrOptions: { + exportType: 'named', + }, +}); +``` + +此时引用的 SVG 文件会同时导出 URL 和 React 组件： + +```js +import logoUrl, { ReactComponent as Logo } from './logo.svg'; + +console.log(logoUrl); // -> string +console.log(Logo); // -> React component +``` + +更多信息可以参考 [mixedImport](https://rsbuild.dev/zh/plugins/list/plugin-svgr#mixedimport) 选项。 From 49f2198e6527fc17fd9291fe239284dbf9d038eb Mon Sep 17 00:00:00 2001 From: SoonIter Date: Thu, 13 Feb 2025 19:25:32 +0800 Subject: [PATCH 05/13] docs: complete en static assets --- .../docs/en/guide/advanced/static-assets.mdx | 100 +++++++++--------- 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/website/docs/en/guide/advanced/static-assets.mdx b/website/docs/en/guide/advanced/static-assets.mdx index 4e0468dac..9268c4a4d 100644 --- a/website/docs/en/guide/advanced/static-assets.mdx +++ b/website/docs/en/guide/advanced/static-assets.mdx @@ -1,24 +1,24 @@ # Import static assets -Rslib 支持在代码中引用图片、字体、音频、视频等类型的静态资源。 +Rslib supports import static assets, including images, fonts, audio and video. -## 静态资源格式 +## Assets format -以下是 Rslib 默认支持的静态资源格式： +The following are the formats supported by Rslib by default: -- **图片**：png、jpg、jpeg、gif、svg、bmp、webp、ico、apng、avif、tif、tiff、jfif、pjpeg、pjp、cur。 -- **字体**：woff、woff2、eot、ttf、otf、ttc。 -- **音频**：mp3、wav、flac、aac、m4a、opus。 -- **视频**：mp4、webm、ogg、mov。 +- **images**: png, jpg, jpeg, gif, svg, bmp, webp, ico, apng, avif, tif, tiff, jfif, pjpeg, pjp, cur. +- **fonts**: woff, woff2, eot, ttf, otf, ttc. +- **audio**: mp3, wav, flac, aac, m4a, opus. +- **video**: mp4, webm, ogg, mov. -如果你需要引用其他格式的静态资源，请参考 [扩展静态资源类型](#扩展静态资源类型)。 +To import assets in other formats, refer to [Extend Asset Types](#extend-asset-types). -## 在 JS 文件中引用 +## Import assets in JS file -在 JS 文件中，可以直接通过 `import` 的方式引用相对路径下的静态资源： +In JS files, you can directly refer to static assets with relative paths through `import`: ```tsx -// 引用 src/assets 目录下的 logo.png 图片 +// Import the logo.png image in the 'src/assets' directory import logo from './assets/logo.png'; console.log(logo); // "/static/logo.[hash].png" @@ -26,7 +26,7 @@ console.log(logo); // "/static/logo.[hash].png" export default = () => ; ``` -也可以使用**路径别名**来引用： +Import with **alias** is also available: ```tsx import logo from '@/assets/logo.png'; @@ -36,9 +36,9 @@ console.log(logo); // "/static/logo.[hash].png" export default = () => ; ``` -在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物。Rslib 会在代码转换时将源文件转化为一个 JS 文件和一个根据 [output.distPath](/config/rsbuild/output#outputdistpath) 输出的静态资源文件，用于保留对静态资源的 `import` 语句。 +When the [format](/config/lib/format) is set to `cjs` or `esm`, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again. During the code transformation, Rslib transforms the source file into a JS file and a static asset file that is output according to [output.distPath](/config/rsbuild/output#outputdistpath), which is used to preserve the `import` statements for static assets. -下面是一个使用示例，假设源码如下： +The following is an example of usage, assuming the source code is as follows: import { Tabs, Tab } from '@theme'; @@ -57,7 +57,7 @@ console.log(logo); -会根据配置文件中的 [产物结构](/guide/basic/output-structure) 配置，打包出如下产物： +Based on the configuration in the [output structure](/guide/basic/output-structure) in the configuration file, the following outputs will be packaged: @@ -105,9 +105,9 @@ export { logo_rslib_entry_namespaceObject as default }; -## 在 CSS 文件中引用 +## Import assets in CSS file -在 CSS 文件中，可以引用相对路径下的静态资源： +In CSS files, you can import static assets with relative paths: ```css title="src/index.css" .logo { @@ -115,7 +115,7 @@ export { logo_rslib_entry_namespaceObject as default }; } ``` -也支持使用**路径别名**来引用： +Import with **alias** are also supported: ```css title="src/index.css" .logo { @@ -123,9 +123,9 @@ export { logo_rslib_entry_namespaceObject as default }; } ``` -在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物。Rslib 会通过设置 [output.assetPrefix](/config/rsbuild/output#outputassetprefix) 为 `"auto"` 来使 CSS 产物中保留相对引用路径。 +When the [format](/config/lib/format) is `cjs` or `esm`, Rslib treats the output as an intermediate product that will be consumed again by other packaging tools. Rslib preserves relative reference paths in CSS outputs by setting [output.assetPrefix](/config/rsbuild/output#outputassetprefix) to `"auto"`. -下面是一个使用示例，假设源码如下： +The following is an example of usage, assuming the source code is as follows: @@ -147,7 +147,7 @@ export { logo_rslib_entry_namespaceObject as default }; -会打包出如下产物： +The following output will be packaged: @@ -174,9 +174,9 @@ export { logo_rslib_entry_namespaceObject as default }; --- -### 在 CSS 中忽略某些文件引用 +### Ignore some assets imported in CSS -如果需要在 CSS 文件中引用绝对路径下的静态资源： +If you need to import a static asset with an absolute path in a CSS file: ```css @font-face { @@ -185,7 +185,7 @@ export { logo_rslib_entry_namespaceObject as default }; } ``` -默认情况下，Rslib 内置的 `css-loader` 会解析 `url()` 中的绝对路径并寻找指定的模块。如果你希望跳过绝对路径的解析，可以配置 [`tools.cssLoader`](/config/rsbuild/tools#toolscssloader) 来过滤指定的路径，被过滤的路径将被原样保留在代码中。 +By default, the built-in `css-loader` in Rslib will resolve absolute paths in `url()` and look for the specified modules. If you want to skip resolving absolute paths, you can configure [`tools.cssLoader`](/config/rsbuild/tools#toolscssloader) to filter out the specified paths. The filtered paths are left as they are in the code. ```ts export default { @@ -204,54 +204,54 @@ export default { }; ``` -## 静态资源内联 +## Inline static assets -在开发组件库这种会被其他打包工具再次消费的中间产物时，一般不会内联静态资源，交给应用侧的构建工具处理和优化。 +When developing libraries that will be consumed again by other build tools as intermediate products, static assets are typically not inlined, leaving the handling and optimization to the build tools on the application side. -自动内联的体积阈值可以通过 [output.dataUriLimit](/config/rsbuild/output#outputdataurilimit) 配置项修改，在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 默认会将 `output.dataUriLimit` 设置为 `0`，不内联任何静态资源。 +The automatic inlining size threshold can be modified via the [output.dataUriLimit](/config/rsbuild/output#outputdataurilimit) configuration option. When the [format](/config/lib/format) is `cjs` or `esm`, Rslib defaults the `output.dataUriLimit` to `0`, not inlining any static assets. -## 构建产物目录 +## Build Output Directory -当静态资源被引用后，会自动被输出到构建产物的目录下，你可以： +Once static assets are referenced, they will automatically be output to the build output directory. You can: -- 通过 [output.filename](/config/rsbuild/output#outputfilename) 来修改产物的文件名。 -- 通过 [output.distPath](/config/rsbuild/output#outputdistpath) 来修改产物的输出路径。 +- Modify the filename of the output through [output.filename](/config/rsbuild/output#outputfilename). +- Change the output path of the product through [output.distPath](/config/rsbuild/output#outputdistpath). -## 类型声明 +## Type declaration -当你在 TypeScript 代码中引用静态资源时，TypeScript 可能会提示该模块缺少类型定义： +When you import static assets in TypeScript code, TypeScript may prompt that the module is missing a type definition: ``` TS2307: Cannot find module './logo.png' or its corresponding type declarations. ``` -此时你需要为静态资源添加类型声明文件，请在项目中创建 `src/env.d.ts` 文件，并添加相应的类型声明。 +To fix this, you need to add a type declaration file for the static assets, please create a `src/env.d.ts` file, and add the corresponding type declaration. -- 方法一：如果项目里安装了 `@rslib/core` 包，你可以直接引用 `@rslib/core` 提供的**预设类型**： +- Method 1: If the `@rslib/core` package is installed, you can reference the **preset types** provided by `@rslib/core`: ```ts /// ``` -- 方法二：手动添加需要的类型声明： +- Method 2: Manually add the required type declarations: ```ts title="src/env.d.ts" -// 以 png 图片为例 +// Taking png images as an example declare module '*.png' { - const url: string; - export default url; + const content: string; + export default content; } ``` -添加类型声明后，如果依然存在上述错误提示，请尝试重启当前 IDE，或者调整 `env.d.ts` 所在的目录，使 TypeScript 能够正确识别类型定义。 +After adding the type declaration, if the type error still exists, you can try to restart the current IDE, or adjust the directory where `env.d.ts` is located, making sure the TypeScript can correctly identify the type definition. -## 扩展静态资源类型 +## Extend asset types -如果 Rslib 内置的静态资源类型不能满足你的需求，可以通过以下方式扩展额外的静态资源类型。 +If the built-in static assets type of Rslib does not meet your needs, you can extend the additional static assets type in the following ways. -### 使用 `source.assetsInclude` +### Use `source.assetsInclude` -通过 [source.assetsInclude](/config/rsbuild/source#sourceassetsinclude) 配置项，你可以指定需要被视为静态资源的额外文件类型。 +By using the [source.assetsInclude](/config/rsbuild/source#sourceassetsinclude) config, you can specify additional file types to be treated as static assets. ```ts title="rslib.config.ts" export default { @@ -261,19 +261,19 @@ export default { }; ``` -添加以上配置后，你就可以在代码里引用 `*.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/assets/myFile.[hash].pdf" +console.log(myFile); ``` -### 使用 `tools.rspack` +### Use `tools.rspack` -可以通过 [tools.rspack](/config/rsbuild/tools#toolsrspack) 来修改内置的 Rspack 配置，并添加自定义的静态资源处理规则。 +You can modify the built-in Rspack configuration and add custom static assets handling rules via [tools.rspack](/config/rsbuild/tools#toolsrspack). -比如，把 `*.pdf` 文件当做静态资源输出到产物目录，可以添加以下配置： +For example, to treat `*.pdf` files as assets and output them to the dist directory, you can add the following configuration: ```ts title="rslib.config.ts" export default { @@ -294,4 +294,4 @@ export default { }; ``` -关于 asset modules 的更多介绍，请参考 [Rspack - Asset modules](https://rspack.dev/guide/features/asset-module)。 +For more information about asset modules, please refer to [Rspack - Asset modules](https://rspack.dev/guide/features/asset-module). From 0bce8c8c4a92b1ab69b7be58d4142bbb5c010482 Mon Sep 17 00:00:00 2001 From: SoonIter Date: Thu, 13 Feb 2025 19:28:21 +0800 Subject: [PATCH 06/13] docs: complete en json files --- website/docs/en/guide/advanced/json-files.mdx | 23 +++++++++---------- 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/website/docs/en/guide/advanced/json-files.mdx b/website/docs/en/guide/advanced/json-files.mdx index 101bd6459..7db0a2c65 100644 --- a/website/docs/en/guide/advanced/json-files.mdx +++ b/website/docs/en/guide/advanced/json-files.mdx @@ -1,12 +1,12 @@ -# 引用 JSON 文件 +# Import JSON files -Rslib 支持在代码中引用 JSON 文件。 +Rslib supports import JSON files in code. -## JSON 文件 +## JSON file -你可以直接在 JavaScript 文件中引用 JSON 文件。 +You can directly reference JSON files in JavaScript files. -### 默认引用 +### Default Import ```json title="example.json" { @@ -24,17 +24,16 @@ console.log(example.items); // [1, 2]; :::warning -在 Bundle 模式下，JSON 文件支持默认引用和具名引用。 - -在 Bundleless 模式下，JSON 文件仅支持具名引用。 +In Bundle mode, JSON files support both default and named imports. +In Bundleless mode, JSON files only support named imports. ::: -### 具名引用 +### Named Import -Rslib 同样支持通过 named import 来引用 JSON 文件： +Rslib also supports referencing JSON files through named imports: -下面是一个使用示例，假设源码如下： +Here is an example, assuming the source code is as follows: import { Tabs, Tab } from '@theme'; @@ -60,7 +59,7 @@ console.log(name); // 'foo'; -会根据配置文件中的 [产物结构](/guide/basic/output-structure) 配置，打包出如下产物： +Based on the configuration in the [output structure](/guide/basic/output-structure) specified in the configuration file, the following outputs will be packaged: From d8f7eabd3138dae61bad99361927677663d2a492 Mon Sep 17 00:00:00 2001 From: SoonIter Date: Thu, 13 Feb 2025 19:29:00 +0800 Subject: [PATCH 07/13] chore: update --- website/docs/en/guide/advanced/json-files.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/website/docs/en/guide/advanced/json-files.mdx b/website/docs/en/guide/advanced/json-files.mdx index 7db0a2c65..4b104d4b6 100644 --- a/website/docs/en/guide/advanced/json-files.mdx +++ b/website/docs/en/guide/advanced/json-files.mdx @@ -65,9 +65,10 @@ Based on the configuration in the [output structure](/guide/basic/output-structu + ```tsx var example_namespaceObject = { - "name": "foo" + name: 'foo', }; console.log(example_namespaceObject.name); ``` @@ -89,12 +90,14 @@ console.log(example.name); + ```tsx var example_namespaceObject = JSON.parse('{"name":"foo","items":[1,2]}'); var __webpack_exports__items = example_namespaceObject.items; var __webpack_exports__name = example_namespaceObject.name; export { __webpack_exports__items as items, __webpack_exports__name as name }; ``` + From 239ad51da50cb63f0b62a96aa80a266c0f7e1e9e Mon Sep 17 00:00:00 2001 From: SoonIter Date: Thu, 13 Feb 2025 19:34:36 +0800 Subject: [PATCH 08/13] chore: update --- website/docs/en/guide/advanced/svgr-files.mdx | 56 ++++++++++--------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/website/docs/en/guide/advanced/svgr-files.mdx b/website/docs/en/guide/advanced/svgr-files.mdx index 1f2be6671..493f28047 100644 --- a/website/docs/en/guide/advanced/svgr-files.mdx +++ b/website/docs/en/guide/advanced/svgr-files.mdx @@ -1,22 +1,22 @@ -# 引用 SVGR +# Referencing SVGR -默认情况下，Rslib 会将 SVG 图片当作静态资源处理。 +By default, Rslib treats SVG images as static assets. -通过添加 [@rsbuild/plugin-svgr](https://rsbuild.dev/zh/plugins/list/plugin-svgr) 插件，Rslib 支持调用 [SVGR](https://react-svgr.com/)，将 SVG 图片转换为一个 React 组件使用。 +By adding the [@rsbuild/plugin-svgr](https://rsbuild.dev/en/plugins/list/plugin-svgr) plugin, Rslib supports invoking [SVGR](https://react-svgr.com/) to convert SVG images into React components for use. -## 快速开始 +## Quick Start -### 安装插件 +### Install the Plugin -你可以通过如下的命令安装插件: +You can install the plugin using the following command: import { PackageManagerTabs } from '@theme'; -### 注册插件 +### Register the Plugin -你可以在 `rslib.config.ts` 文件中注册插件： +You can register the plugin in the `rslib.config.ts` file: ```ts title="rslib.config.ts" import { pluginSvgr } from '@rsbuild/plugin-svgr'; @@ -26,13 +26,13 @@ export default { }; ``` -## 示例 +## Examples -### Bundle 模式 +### Bundle Mode -在 Bundle 模式下，支持 [Rsbuild SVGR 插件](https://rsbuild.dev/zh/plugins/list/plugin-svgr) 下的所有用法，唯一的区别是当以 URL 形式使用 SVG 文件时，Rslib 会按照 [引用静态资源](/zh/guide/advanced/static-assets) 在产物中对应保留静态资源的 `import` 语句。 +In Bundle mode, all usages supported by the [Rsbuild SVGR plugin](https://rsbuild.dev/en/plugins/list/plugin-svgr) are available. The only difference is that when using an SVG file in URL form, Rslib will retain the `import` statement for the static asset in the output according to [Referencing Static Assets](/en/guide/advanced/static-assets). -下面是一个使用示例： +Here is an example of usage: ```jsx title="App.jsx" import Logo from './logo.svg?react'; @@ -40,7 +40,9 @@ import Logo from './logo.svg?react'; export const App = () => ; ``` -如果导入的路径不包含 `?react` 后缀，那么 SVG 会被当做普通的静态资源来处理，保留对静态资源的 `import` 语句。 +If the import path does not include the `?react` suffix, the SVG will be treated as a normal static asset, and the `import` statement for the static asset will be retained. + +`@rsbuild/plugin-svgr` also supports default imports and mixed imports: ```js import logoURL from './static/logo.svg'; @@ -48,18 +50,18 @@ import logoURL from './static/logo.svg'; console.log(logoURL); ``` -`@rsbuild/plugin-svgr` 也支持默认导入和混合导入等用法： +`@rsbuild/plugin-svgr` also supports default imports and mixed imports: -- 通过 [svgrOptions.exportType](https://rsbuild.dev/zh/plugins/list/plugin-svgr#svgroptionsexporttype) 设置为 `'default'` 来启用默认导入。 -- 通过 [mixedImport](https://rsbuild.dev/zh/plugins/list/plugin-svgr#mixedimport) 选项来启用混合导入，从而同时使用默认导入和具名导入。 +- Enable default imports by setting [svgrOptions.exportType](https://rsbuild.dev/en/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`. +- Enable mixed imports through the [mixedImport](https://rsbuild.dev/en/plugins/list/plugin-svgr#mixedimport) option to use both default and named imports. -### Bundleless 模式 +### Bundleless Mode -在 Bundleless 模式下，由于每个文件都是独立经过代码转换，因此不支持 `?react` 和 `?url` 的引用形式，但支持下面两种使用形式： +In Bundleless mode, since each file undergoes code transformation independently, the import ways of `?react` and `?url` are not supported. However, the following two usage forms are supported: -#### 具名导入 +#### Named Import -`@rsbuild/plugin-svgr` 支持具名导入 `ReactComponent` 来使用 SVGR，你需要设置 [svgrOptions.exportType](https://rsbuild.dev/zh/plugins/list/plugin-svgr#svgroptionsexporttype) 为 `'named'`： +`@rsbuild/plugin-svgr` supports named import of `ReactComponent` to use SVGR. You need to set [svgrOptions.exportType](https://rsbuild.dev/en/plugins/list/plugin-svgr#svgroptionsexporttype) to `'named'`. ```js pluginSvgr({ @@ -75,14 +77,14 @@ import { ReactComponent as Logo } from './logo.svg'; export const App = () => ; ``` -所有的 `.svg` 文件都会被转换成 React 组件，此时你可以： +All `.svg` files will be converted into React components. At this time, you can: -- 通过设置 [exclude](https://rsbuild.dev/zh/plugins/list/plugin-svgr#exclude) 来排除不需要转换的文件。 -- 通过 [svgrOptions.exportType](https://rsbuild.dev/zh/plugins/list/plugin-svgr#svgroptionsexporttype) 设置为 `'default'` 来修改为默认导出。 +- Exclude files that do not need to be converted by setting [exclude](https://rsbuild.dev/en/plugins/list/plugin-svgr#exclude). +- Change to default export by setting [svgrOptions.exportType](https://rsbuild.dev/en/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`. -#### 混合导入 +#### Mixed Import -如果你的库中同时存在 url 和 React 组件两种引入形式，你也可以通过混合导入的方式来使用： +If your library has both URL and React component import forms for SVG files, you can also use mixed imports. ```ts pluginSvgr({ @@ -93,7 +95,7 @@ pluginSvgr({ }); ``` -此时引用的 SVG 文件会同时导出 URL 和 React 组件： +At this time, the imported SVG file will export both the URL and the React component. ```js import logoUrl, { ReactComponent as Logo } from './logo.svg'; @@ -102,4 +104,4 @@ console.log(logoUrl); // -> string console.log(Logo); // -> React component ``` -更多信息可以参考 [mixedImport](https://rsbuild.dev/zh/plugins/list/plugin-svgr#mixedimport) 选项。 +For more information, refer to the [mixedImport](https://rsbuild.dev/en/plugins/list/plugin-svgr#mixedimport) option. From d32c30f382ec5ab51810312ec50c274dccbfeb2d Mon Sep 17 00:00:00 2001 From: SoonIter Date: Thu, 13 Feb 2025 19:36:06 +0800 Subject: [PATCH 09/13] chore: update --- website/docs/en/guide/advanced/svgr-files.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/en/guide/advanced/svgr-files.mdx b/website/docs/en/guide/advanced/svgr-files.mdx index 493f28047..43062e79e 100644 --- a/website/docs/en/guide/advanced/svgr-files.mdx +++ b/website/docs/en/guide/advanced/svgr-files.mdx @@ -1,4 +1,4 @@ -# Referencing SVGR +# Import SVGR By default, Rslib treats SVG images as static assets. From e24c9eec0173e70a01869107d8c2c87c97beb46b Mon Sep 17 00:00:00 2001 From: SoonIter Date: Thu, 13 Feb 2025 19:41:55 +0800 Subject: [PATCH 10/13] chore: update --- website/docs/en/guide/advanced/svgr-files.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/website/docs/en/guide/advanced/svgr-files.mdx b/website/docs/en/guide/advanced/svgr-files.mdx index 43062e79e..03027d4e2 100644 --- a/website/docs/en/guide/advanced/svgr-files.mdx +++ b/website/docs/en/guide/advanced/svgr-files.mdx @@ -2,7 +2,7 @@ By default, Rslib treats SVG images as static assets. -By adding the [@rsbuild/plugin-svgr](https://rsbuild.dev/en/plugins/list/plugin-svgr) plugin, Rslib supports invoking [SVGR](https://react-svgr.com/) to convert SVG images into React components for use. +By adding the [@rsbuild/plugin-svgr](https://rsbuild.dev/plugins/list/plugin-svgr) plugin, Rslib supports invoking [SVGR](https://react-svgr.com/) to convert SVG images into React components for use. ## Quick Start @@ -30,7 +30,7 @@ export default { ### Bundle Mode -In Bundle mode, all usages supported by the [Rsbuild SVGR plugin](https://rsbuild.dev/en/plugins/list/plugin-svgr) are available. The only difference is that when using an SVG file in URL form, Rslib will retain the `import` statement for the static asset in the output according to [Referencing Static Assets](/en/guide/advanced/static-assets). +In Bundle mode, all usages supported by the [Rsbuild SVGR plugin](https://rsbuild.dev/plugins/list/plugin-svgr) are available. The only difference is that when using an SVG file in URL form, Rslib will retain the `import` statement for the static asset in the output according to [Referencing Static Assets](/guide/advanced/static-assets). Here is an example of usage: @@ -52,8 +52,8 @@ console.log(logoURL); `@rsbuild/plugin-svgr` also supports default imports and mixed imports: -- Enable default imports by setting [svgrOptions.exportType](https://rsbuild.dev/en/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`. -- Enable mixed imports through the [mixedImport](https://rsbuild.dev/en/plugins/list/plugin-svgr#mixedimport) option to use both default and named imports. +- Enable default imports by setting [svgrOptions.exportType](https://rsbuild.dev/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`. +- Enable mixed imports through the [mixedImport](https://rsbuild.dev/plugins/list/plugin-svgr#mixedimport) option to use both default and named imports. ### Bundleless Mode @@ -61,7 +61,7 @@ In Bundleless mode, since each file undergoes code transformation independently, #### Named Import -`@rsbuild/plugin-svgr` supports named import of `ReactComponent` to use SVGR. You need to set [svgrOptions.exportType](https://rsbuild.dev/en/plugins/list/plugin-svgr#svgroptionsexporttype) to `'named'`. +`@rsbuild/plugin-svgr` supports named import of `ReactComponent` to use SVGR. You need to set [svgrOptions.exportType](https://rsbuild.dev/plugins/list/plugin-svgr#svgroptionsexporttype) to `'named'`. ```js pluginSvgr({ @@ -79,8 +79,8 @@ export const App = () => ; All `.svg` files will be converted into React components. At this time, you can: -- Exclude files that do not need to be converted by setting [exclude](https://rsbuild.dev/en/plugins/list/plugin-svgr#exclude). -- Change to default export by setting [svgrOptions.exportType](https://rsbuild.dev/en/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`. +- Exclude files that do not need to be converted by setting [exclude](https://rsbuild.dev/plugins/list/plugin-svgr#exclude). +- Change to default export by setting [svgrOptions.exportType](https://rsbuild.dev/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`. #### Mixed Import @@ -104,4 +104,4 @@ console.log(logoUrl); // -> string console.log(Logo); // -> React component ``` -For more information, refer to the [mixedImport](https://rsbuild.dev/en/plugins/list/plugin-svgr#mixedimport) option. +For more information, refer to the [mixedImport](https://rsbuild.dev/plugins/list/plugin-svgr#mixedimport) option. From 9a09eaabad83b5712dc58af2bad3e294b145b054 Mon Sep 17 00:00:00 2001 From: SoonIter Date: Thu, 13 Feb 2025 19:46:51 +0800 Subject: [PATCH 11/13] chore: update --- website/docs/en/config/rsbuild/output.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/website/docs/en/config/rsbuild/output.mdx b/website/docs/en/config/rsbuild/output.mdx index d0b0123c8..45c0b1529 100644 --- a/website/docs/en/config/rsbuild/output.mdx +++ b/website/docs/en/config/rsbuild/output.mdx @@ -4,9 +4,11 @@ import { RsbuildDocBadge } from '@components/RsbuildDocBadge'; Options for build outputs. -{/* ## output.assetPrefix */} +## output.assetPrefix -{/* In [production mode](https://rsbuild.dev/config/mode), use this option to set the URL prefix for static assets, such as setting it to a CDN URL. */} +Use this option to set the URL prefix for static assets, such as setting it to a CDN URL. + +In cases where the [format](/config/lib/format) is set to `cjs` or `esm`, Rslib sets `output.assetPrefix` to `"auto"`. ## output.charset From db463a73739ddb2e4365eb0539d43cd669fedb3c Mon Sep 17 00:00:00 2001 From: SoonIter Date: Thu, 13 Feb 2025 19:50:26 +0800 Subject: [PATCH 12/13] chore: update --- website/docs/en/guide/advanced/json-files.mdx | 4 ++-- website/docs/en/guide/advanced/static-assets.mdx | 2 +- website/docs/en/guide/advanced/svgr-files.mdx | 14 +++++++------- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/website/docs/en/guide/advanced/json-files.mdx b/website/docs/en/guide/advanced/json-files.mdx index 4b104d4b6..93bf8c123 100644 --- a/website/docs/en/guide/advanced/json-files.mdx +++ b/website/docs/en/guide/advanced/json-files.mdx @@ -6,7 +6,7 @@ Rslib supports import JSON files in code. You can directly reference JSON files in JavaScript files. -### Default Import +### Default import ```json title="example.json" { @@ -29,7 +29,7 @@ In Bundleless mode, JSON files only support named imports. ::: -### Named Import +### Named import Rslib also supports referencing JSON files through named imports: diff --git a/website/docs/en/guide/advanced/static-assets.mdx b/website/docs/en/guide/advanced/static-assets.mdx index 9268c4a4d..8d7471312 100644 --- a/website/docs/en/guide/advanced/static-assets.mdx +++ b/website/docs/en/guide/advanced/static-assets.mdx @@ -210,7 +210,7 @@ When developing libraries that will be consumed again by other build tools as in The automatic inlining size threshold can be modified via the [output.dataUriLimit](/config/rsbuild/output#outputdataurilimit) configuration option. When the [format](/config/lib/format) is `cjs` or `esm`, Rslib defaults the `output.dataUriLimit` to `0`, not inlining any static assets. -## Build Output Directory +## Build output directory Once static assets are referenced, they will automatically be output to the build output directory. You can: diff --git a/website/docs/en/guide/advanced/svgr-files.mdx b/website/docs/en/guide/advanced/svgr-files.mdx index 03027d4e2..4644dbe7b 100644 --- a/website/docs/en/guide/advanced/svgr-files.mdx +++ b/website/docs/en/guide/advanced/svgr-files.mdx @@ -4,9 +4,9 @@ By default, Rslib treats SVG images as static assets. By adding the [@rsbuild/plugin-svgr](https://rsbuild.dev/plugins/list/plugin-svgr) plugin, Rslib supports invoking [SVGR](https://react-svgr.com/) to convert SVG images into React components for use. -## Quick Start +## Quick start -### Install the Plugin +### Install the plugin You can install the plugin using the following command: @@ -14,7 +14,7 @@ import { PackageManagerTabs } from '@theme'; -### Register the Plugin +### Register the plugin You can register the plugin in the `rslib.config.ts` file: @@ -28,7 +28,7 @@ export default { ## Examples -### Bundle Mode +### Bundle mode In Bundle mode, all usages supported by the [Rsbuild SVGR plugin](https://rsbuild.dev/plugins/list/plugin-svgr) are available. The only difference is that when using an SVG file in URL form, Rslib will retain the `import` statement for the static asset in the output according to [Referencing Static Assets](/guide/advanced/static-assets). @@ -55,11 +55,11 @@ console.log(logoURL); - Enable default imports by setting [svgrOptions.exportType](https://rsbuild.dev/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`. - Enable mixed imports through the [mixedImport](https://rsbuild.dev/plugins/list/plugin-svgr#mixedimport) option to use both default and named imports. -### Bundleless Mode +### Bundleless mode In Bundleless mode, since each file undergoes code transformation independently, the import ways of `?react` and `?url` are not supported. However, the following two usage forms are supported: -#### Named Import +#### Named import `@rsbuild/plugin-svgr` supports named import of `ReactComponent` to use SVGR. You need to set [svgrOptions.exportType](https://rsbuild.dev/plugins/list/plugin-svgr#svgroptionsexporttype) to `'named'`. @@ -82,7 +82,7 @@ All `.svg` files will be converted into React components. At this time, you can: - Exclude files that do not need to be converted by setting [exclude](https://rsbuild.dev/plugins/list/plugin-svgr#exclude). - Change to default export by setting [svgrOptions.exportType](https://rsbuild.dev/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`. -#### Mixed Import +#### Mixed import If your library has both URL and React component import forms for SVG files, you can also use mixed imports. From 0b89e80a54e45b8a3df84a7d91e4bc2fdbfefd72 Mon Sep 17 00:00:00 2001 From: Timeless0911 <1604889533@qq.com> Date: Mon, 17 Feb 2025 19:55:45 +0800 Subject: [PATCH 13/13] chore: update --- website/docs/en/config/rsbuild/output.mdx | 4 ++- website/docs/en/guide/advanced/json-files.mdx | 29 ++++++++++--------- .../docs/en/guide/advanced/static-assets.mdx | 28 +++++++++--------- website/docs/en/guide/advanced/svgr-files.mdx | 18 ++++++------ website/docs/zh/guide/advanced/json-files.mdx | 28 +++++++++--------- .../docs/zh/guide/advanced/static-assets.mdx | 18 +++++------- website/docs/zh/guide/advanced/svgr-files.mdx | 6 ++-- 7 files changed, 65 insertions(+), 66 deletions(-) diff --git a/website/docs/en/config/rsbuild/output.mdx b/website/docs/en/config/rsbuild/output.mdx index 45c0b1529..6f140e0a2 100644 --- a/website/docs/en/config/rsbuild/output.mdx +++ b/website/docs/en/config/rsbuild/output.mdx @@ -8,7 +8,7 @@ Options for build outputs. Use this option to set the URL prefix for static assets, such as setting it to a CDN URL. -In cases where the [format](/config/lib/format) is set to `cjs` or `esm`, Rslib sets `output.assetPrefix` to `"auto"`. +When [format](/config/lib/format) is set to `cjs` or `esm`, Rslib defaults to setting `output.assetPrefix` to `"auto"`. ## output.charset @@ -30,6 +30,8 @@ For custom CSS Modules configuration. Set the size threshold to inline static assets such as images and fonts. +When [format](/config/lib/format) is set to `cjs` or `esm`, Rslib defaults to setting `output.dataUriLimit` to `0`, without inlining any static assets, so that build tools on the application side can handle and optimize them. + ## output.distPath Set the directory of the dist files. Rsbuild will output files to the corresponding subdirectory according to the file type. diff --git a/website/docs/en/guide/advanced/json-files.mdx b/website/docs/en/guide/advanced/json-files.mdx index 93bf8c123..5b89694c7 100644 --- a/website/docs/en/guide/advanced/json-files.mdx +++ b/website/docs/en/guide/advanced/json-files.mdx @@ -4,7 +4,15 @@ Rslib supports import JSON files in code. ## JSON file -You can directly reference JSON files in JavaScript files. +You can directly import JSON files in JavaScript files. + +:::warning + +In bundle mode, JSON files support both default and named import. + +In bundleless mode, JSON files only support named import. + +::: ### Default import @@ -22,16 +30,9 @@ console.log(example.name); // 'foo'; console.log(example.items); // [1, 2]; ``` -:::warning - -In Bundle mode, JSON files support both default and named imports. -In Bundleless mode, JSON files only support named imports. - -::: - ### Named import -Rslib also supports referencing JSON files through named imports: +Rslib also supports importing JSON files through named import. Here is an example, assuming the source code is as follows: @@ -59,25 +60,25 @@ console.log(name); // 'foo'; -Based on the configuration in the [output structure](/guide/basic/output-structure) specified in the configuration file, the following outputs will be packaged: +Based on the configuration in the [output structure](/guide/basic/output-structure) specified in the configuration file, the following outputs will be emitted: - + ```tsx var example_namespaceObject = { - name: 'foo', + u: 'foo', }; -console.log(example_namespaceObject.name); +console.log(example_namespaceObject.u); ``` - + diff --git a/website/docs/en/guide/advanced/static-assets.mdx b/website/docs/en/guide/advanced/static-assets.mdx index 8d7471312..69df68e2a 100644 --- a/website/docs/en/guide/advanced/static-assets.mdx +++ b/website/docs/en/guide/advanced/static-assets.mdx @@ -15,7 +15,7 @@ To import assets in other formats, refer to [Extend Asset Types](#extend-asset-t ## Import assets in JS file -In JS files, you can directly refer to static assets with relative paths through `import`: +In JS files, you can directly import static assets with relative paths through `import`: ```tsx // Import the logo.png image in the 'src/assets' directory @@ -36,7 +36,7 @@ console.log(logo); // "/static/logo.[hash].png" export default = () => ; ``` -When the [format](/config/lib/format) is set to `cjs` or `esm`, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again. During the code transformation, Rslib transforms the source file into a JS file and a static asset file that is output according to [output.distPath](/config/rsbuild/output#outputdistpath), which is used to preserve the `import` statements for static assets. +When the [format](/config/lib/format) is set to `cjs` or `esm`, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again and transforms the source file into a JS file and a static asset file that is emitted according to [output.distPath](/config/rsbuild/output#outputdistpath) by default, which is used to preserve the `import` statements for static assets. The following is an example of usage, assuming the source code is as follows: @@ -57,10 +57,10 @@ console.log(logo); -Based on the configuration in the [output structure](/guide/basic/output-structure) in the configuration file, the following outputs will be packaged: +Based on the configuration in the [output structure](/guide/basic/output-structure) in the configuration file, the following outputs will be emitted: - + @@ -77,7 +77,7 @@ console.log(logo_rslib_entry_namespaceObject); - + @@ -123,7 +123,7 @@ Import with **alias** are also supported: } ``` -When the [format](/config/lib/format) is `cjs` or `esm`, Rslib treats the output as an intermediate product that will be consumed again by other packaging tools. Rslib preserves relative reference paths in CSS outputs by setting [output.assetPrefix](/config/rsbuild/output#outputassetprefix) to `"auto"`. +When the [format](/config/lib/format) is set to `cjs` or `esm`, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again and preserves relative reference paths in CSS outputs by default via setting [output.assetPrefix](/config/rsbuild/output#outputassetprefix) to `"auto"`. The following is an example of usage, assuming the source code is as follows: @@ -147,7 +147,7 @@ The following is an example of usage, assuming the source code is as follows: -The following output will be packaged: +The following output will be emitted: @@ -185,7 +185,7 @@ If you need to import a static asset with an absolute path in a CSS file: } ``` -By default, the built-in `css-loader` in Rslib will resolve absolute paths in `url()` and look for the specified modules. If you want to skip resolving absolute paths, you can configure [`tools.cssLoader`](/config/rsbuild/tools#toolscssloader) to filter out the specified paths. The filtered paths are left as they are in the code. +By default, the built-in `css-loader` in Rslib will resolve absolute paths in `url()` and look for the specified modules. If you want to skip resolving absolute paths, you can configure [`tools.cssLoader`](/config/rsbuild/tools#toolscssloader) to filter out the specified paths. The filtered paths are preserved as they are in the code. ```ts export default { @@ -206,16 +206,14 @@ export default { ## Inline static assets -When developing libraries that will be consumed again by other build tools as intermediate products, static assets are typically not inlined, leaving the handling and optimization to the build tools on the application side. - -The automatic inlining size threshold can be modified via the [output.dataUriLimit](/config/rsbuild/output#outputdataurilimit) configuration option. When the [format](/config/lib/format) is `cjs` or `esm`, Rslib defaults the `output.dataUriLimit` to `0`, not inlining any static assets. +When the [format](/config/lib/format) is set to `cjs` or `esm`, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again and sets [output.dataUriLimit](/config/rsbuild/output#outputdataurilimit) to `0` by default to not inline any static assets. ## Build output directory -Once static assets are referenced, they will automatically be output to the build output directory. You can: +Once static assets are imported, they will automatically be output to the build output directory. You can: -- Modify the filename of the output through [output.filename](/config/rsbuild/output#outputfilename). -- Change the output path of the product through [output.distPath](/config/rsbuild/output#outputdistpath). +- Modify the filename of the outputs through [output.filename](/config/rsbuild/output#outputfilename). +- Change the output path of the outputs through [output.distPath](/config/rsbuild/output#outputdistpath). ## Type declaration @@ -282,7 +280,7 @@ export default { addRules([ { test: /\.pdf$/, - // 将资源转换为单独的文件，并且保留 import 语句 + // Convert assets to separate files and keep import statements type: 'asset/resource', generator: { importMode: 'preserve', diff --git a/website/docs/en/guide/advanced/svgr-files.mdx b/website/docs/en/guide/advanced/svgr-files.mdx index 4644dbe7b..b52cc365d 100644 --- a/website/docs/en/guide/advanced/svgr-files.mdx +++ b/website/docs/en/guide/advanced/svgr-files.mdx @@ -2,7 +2,7 @@ By default, Rslib treats SVG images as static assets. -By adding the [@rsbuild/plugin-svgr](https://rsbuild.dev/plugins/list/plugin-svgr) plugin, Rslib supports invoking [SVGR](https://react-svgr.com/) to convert SVG images into React components for use. +By adding the [@rsbuild/plugin-svgr](https://rsbuild.dev/plugins/list/plugin-svgr) plugin, Rslib supports transforming SVG to React components via [SVGR](https://react-svgr.com/). ## Quick start @@ -30,7 +30,7 @@ export default { ### Bundle mode -In Bundle mode, all usages supported by the [Rsbuild SVGR plugin](https://rsbuild.dev/plugins/list/plugin-svgr) are available. The only difference is that when using an SVG file in URL form, Rslib will retain the `import` statement for the static asset in the output according to [Referencing Static Assets](/guide/advanced/static-assets). +In bundle mode, all usages supported by [@rsbuild/plugin-svgr](https://rsbuild.dev/plugins/list/plugin-svgr) are available in Rslib. The only difference is that when using an SVG file in URL form, Rslib will retain the `import` statement for the static asset in the output according to [Import static assets](/guide/advanced/static-assets). Here is an example of usage: @@ -50,14 +50,14 @@ import logoURL from './static/logo.svg'; console.log(logoURL); ``` -`@rsbuild/plugin-svgr` also supports default imports and mixed imports: +`@rsbuild/plugin-svgr` also supports default import and mixed import: -- Enable default imports by setting [svgrOptions.exportType](https://rsbuild.dev/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`. -- Enable mixed imports through the [mixedImport](https://rsbuild.dev/plugins/list/plugin-svgr#mixedimport) option to use both default and named imports. +- Enable default import by setting [svgrOptions.exportType](https://rsbuild.dev/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`. +- Enable mixed import through the [mixedImport](https://rsbuild.dev/plugins/list/plugin-svgr#mixedimport) option to use both default and named import. ### Bundleless mode -In Bundleless mode, since each file undergoes code transformation independently, the import ways of `?react` and `?url` are not supported. However, the following two usage forms are supported: +In bundleless mode, since each file undergoes code transformation independently, the import ways of `?react` and `?url` are not supported. However, the following two usage forms are supported: #### Named import @@ -77,14 +77,14 @@ import { ReactComponent as Logo } from './logo.svg'; export const App = () => ; ``` -All `.svg` files will be converted into React components. At this time, you can: +All `.svg` files will be transformed into React components. At this time, you can: -- Exclude files that do not need to be converted by setting [exclude](https://rsbuild.dev/plugins/list/plugin-svgr#exclude). +- Exclude files that do not need to be transformed by setting [exclude](https://rsbuild.dev/plugins/list/plugin-svgr#exclude). - Change to default export by setting [svgrOptions.exportType](https://rsbuild.dev/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`. #### Mixed import -If your library has both URL and React component import forms for SVG files, you can also use mixed imports. +If your library has both URL and React component import forms for SVG files, you can also use mixed import. ```ts pluginSvgr({ diff --git a/website/docs/zh/guide/advanced/json-files.mdx b/website/docs/zh/guide/advanced/json-files.mdx index 101bd6459..478a93295 100644 --- a/website/docs/zh/guide/advanced/json-files.mdx +++ b/website/docs/zh/guide/advanced/json-files.mdx @@ -6,6 +6,14 @@ Rslib 支持在代码中引用 JSON 文件。 你可以直接在 JavaScript 文件中引用 JSON 文件。 +:::warning + +在 bundle 模式下，JSON 文件支持默认引用和具名引用。 + +在 bundleless 模式下，JSON 文件仅支持具名引用。 + +::: + ### 默认引用 ```json title="example.json" @@ -22,17 +30,9 @@ console.log(example.name); // 'foo'; console.log(example.items); // [1, 2]; ``` -:::warning - -在 Bundle 模式下，JSON 文件支持默认引用和具名引用。 - -在 Bundleless 模式下，JSON 文件仅支持具名引用。 - -::: - ### 具名引用 -Rslib 同样支持通过 named import 来引用 JSON 文件： +Rslib 同样支持通过 named import 来引用 JSON 文件。 下面是一个使用示例，假设源码如下： @@ -60,24 +60,24 @@ console.log(name); // 'foo'; -会根据配置文件中的 [产物结构](/guide/basic/output-structure) 配置，打包出如下产物： +会根据配置文件中的 [产物结构](/guide/basic/output-structure) 配置，输出如下产物： - + ```tsx var example_namespaceObject = { - "name": "foo" + u: 'foo', }; -console.log(example_namespaceObject.name); +console.log(example_namespaceObject.u); ``` - + diff --git a/website/docs/zh/guide/advanced/static-assets.mdx b/website/docs/zh/guide/advanced/static-assets.mdx index 40905d559..9b5483938 100644 --- a/website/docs/zh/guide/advanced/static-assets.mdx +++ b/website/docs/zh/guide/advanced/static-assets.mdx @@ -36,7 +36,7 @@ console.log(logo); // "/static/logo.[hash].png" export default = () => ; ``` -在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物。Rslib 会在代码转换时将源文件转化为一个 JS 文件和一个根据 [output.distPath](/config/rsbuild/output#outputdistpath) 输出的静态资源文件，用于保留对静态资源的 `import` 语句。 +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物，默认会在代码转换时将源文件转化为一个 JS 文件和一个根据 [output.distPath](/config/rsbuild/output#outputdistpath) 输出的静态资源文件，从而保留引用静态资源的 `import` 语句。 下面是一个使用示例，假设源码如下： @@ -57,10 +57,10 @@ console.log(logo); -会根据配置文件中的 [产物结构](/guide/basic/output-structure) 配置，打包出如下产物： +会根据配置文件中的 [产物结构](/guide/basic/output-structure) 配置，输出如下产物： - + @@ -77,7 +77,7 @@ console.log(logo_rslib_entry_namespaceObject); - + @@ -123,7 +123,7 @@ export { logo_rslib_entry_namespaceObject as default }; } ``` -在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物。Rslib 会通过设置 [output.assetPrefix](/config/rsbuild/output#outputassetprefix) 为 `"auto"` 来使 CSS 产物中保留相对引用路径。 +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物，默认会将 [output.assetPrefix](/config/rsbuild/output#outputassetprefix) 设置为 `"auto"` 来使 CSS 产物中保留相对引用路径。 下面是一个使用示例，假设源码如下： @@ -147,7 +147,7 @@ export { logo_rslib_entry_namespaceObject as default }; -会打包出如下产物： +会输出如下产物： @@ -206,9 +206,7 @@ export default { ## 静态资源内联 -在开发组件库这种会被其他打包工具再次消费的中间产物时，一般不会内联静态资源，交给应用侧的构建工具处理和优化。 - -自动内联的体积阈值可以通过 [output.dataUriLimit](/config/rsbuild/output#outputdataurilimit) 配置项修改，在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 默认会将 `output.dataUriLimit` 设置为 `0`，不内联任何静态资源。 +在 [format](/config/lib/format) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物，默认会将 [output.dataUriLimit](/config/rsbuild/output#outputdataurilimit) 设置为 `0` 以不内联任何静态资源。 ## 构建产物目录 @@ -294,4 +292,4 @@ export default { }; ``` -关于 asset modules 的更多介绍，请参考 [Rspack - Asset modules](https://rspack.dev/guide/features/asset-module)。 +关于资源模块的更多介绍，请参考 [Rspack - 资源模块](https://rspack.dev/zh/guide/features/asset-module)。 diff --git a/website/docs/zh/guide/advanced/svgr-files.mdx b/website/docs/zh/guide/advanced/svgr-files.mdx index 1f2be6671..50dac8591 100644 --- a/website/docs/zh/guide/advanced/svgr-files.mdx +++ b/website/docs/zh/guide/advanced/svgr-files.mdx @@ -30,7 +30,7 @@ export default { ### Bundle 模式 -在 Bundle 模式下，支持 [Rsbuild SVGR 插件](https://rsbuild.dev/zh/plugins/list/plugin-svgr) 下的所有用法，唯一的区别是当以 URL 形式使用 SVG 文件时，Rslib 会按照 [引用静态资源](/zh/guide/advanced/static-assets) 在产物中对应保留静态资源的 `import` 语句。 +在 bundle 模式下，Rslib 支持 [@rsbuild/plugin-svgr](https://rsbuild.dev/zh/plugins/list/plugin-svgr) 下的所有用法，唯一的区别是当以 URL 形式使用 SVG 文件时，Rslib 会按照 [引用静态资源](/guide/advanced/static-assets) 在产物中对应保留静态资源的 `import` 语句。 下面是一个使用示例： @@ -40,7 +40,7 @@ import Logo from './logo.svg?react'; export const App = () => ; ``` -如果导入的路径不包含 `?react` 后缀，那么 SVG 会被当做普通的静态资源来处理，保留对静态资源的 `import` 语句。 +如果导入的路径不包含 `?react` 后缀，那么 SVG 会被当做普通的静态资源来处理，即保留对静态资源的 `import` 语句。 ```js import logoURL from './static/logo.svg'; @@ -55,7 +55,7 @@ console.log(logoURL); ### Bundleless 模式 -在 Bundleless 模式下，由于每个文件都是独立经过代码转换，因此不支持 `?react` 和 `?url` 的引用形式，但支持下面两种使用形式： +在 bundleless 模式下，由于每个文件都是独立经过代码转换，因此不支持 `?react` 和 `?url` 的引用形式，但支持下面两种使用形式： #### 具名导入