From 2733867fae5afa767b6e5cac36a11cfe3df37535 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E6=B1=9F=E8=BE=B0?= Date: Tue, 25 Mar 2025 10:49:51 +0800 Subject: [PATCH 1/4] docs(json): add documents for YAML and TOML file support --- website/docs/en/guide/advanced/json-files.mdx | 117 +++++++++++++++++- website/docs/zh/guide/advanced/json-files.mdx | 117 +++++++++++++++++- 2 files changed, 232 insertions(+), 2 deletions(-) diff --git a/website/docs/en/guide/advanced/json-files.mdx b/website/docs/en/guide/advanced/json-files.mdx index 5b89694c7..96e93a461 100644 --- a/website/docs/en/guide/advanced/json-files.mdx +++ b/website/docs/en/guide/advanced/json-files.mdx @@ -1,6 +1,6 @@ # Import JSON files -Rslib supports import JSON files in code. +Rslib supports import JSON files in code. and also supports import [YAML](https://yaml.org/) and [Toml](https://toml.io/en/) files and converting them to JSON format. ## JSON file @@ -104,3 +104,118 @@ export { __webpack_exports__items as items, __webpack_exports__name as name }; + +## YAML file + +[YAML](https://yaml.org/) is a data serialization language commonly used for writing configuration files. + +By adding the [@rsbuild/plugin-yaml](https://github.com/rspack-contrib/rsbuild-plugin-yaml) plugin, you can import `.yaml` or `.yml` files in JavaScript and they will be automatically converted to JavaScript objects. + +import { PackageManagerTabs } from '@theme'; + + + +### Register plugin + +You can register the plugin in the `rslib.config.ts` file: + +```ts title="rslib.config.ts" +import { pluginYaml } from '@rsbuild/plugin-yaml'; + +export default { + plugins: [pluginYaml()], +}; +``` + +### Example + + + + +```js +import { name } from './example.yaml'; + +console.log(name); // 'foo'; +``` + + + + +```yaml +name: foo +items: + - 1 + - 2 +``` + + + + +## TOML file + +[TOML](https://toml.io/) is a semantically explicit, easy-to-read configuration file format. + +By adding the [@rsbuild/plugin-toml](https://github.com/rspack-contrib/rsbuild-plugin-toml) plugin, you can import `.toml` files in JavaScript and it will be automatically converted to JavaScript objects. + + + +### Register plugin + +You can register the plugin in the `rslib.config.ts` file: + +```ts title="rslib.config.ts" +import { pluginToml } from '@rsbuild/plugin-toml'; + +export default { + plugins: [pluginToml()], +}; +``` + +### Example + + + + +```js +import { name } from './example.toml'; + +console.log(name); // 'foo'; +``` + + + + +```toml +name = "foo" +items = [1, 2] +``` + + + + +## Type declaration + +When you import YAML or Toml files in TypeScript code, please create a `src/env.d.ts` file in your project and add the corresponding type declarations. + +- Method 1: If the `@rslib/core` package is installed, you can reference the **preset types** provided by `@rslib/core`: + +```ts title="src/env.d.ts" +/// +``` + +- Method 2: Manually add the required type declarations: + +```ts title="src/env.d.ts" +declare module '*.yaml' { + const content: Record; + export default content; +} +declare module '*.yml' { + const content: Record; + export default content; +} +declare module '*.toml' { + const content: Record; + export default content; +} +``` diff --git a/website/docs/zh/guide/advanced/json-files.mdx b/website/docs/zh/guide/advanced/json-files.mdx index 478a93295..0ce31bbe3 100644 --- a/website/docs/zh/guide/advanced/json-files.mdx +++ b/website/docs/zh/guide/advanced/json-files.mdx @@ -1,6 +1,6 @@ # 引用 JSON 文件 -Rslib 支持在代码中引用 JSON 文件。 +Rslib 支持在代码中引用 JSON 文件，同时也支持引用 [YAML](https://yaml.org/) 和 [TOML](https://toml.io/en/) 文件并将其转换为 JSON 格式。 ## JSON 文件 @@ -101,3 +101,118 @@ export { __webpack_exports__items as items, __webpack_exports__name as name }; + +## YAML 文件 + +[YAML](https://yaml.org/) 是一种数据序列化语言，通常用于编写配置文件。 + +通过添加 [@rsbuild/plugin-yaml](https://github.com/rspack-contrib/rsbuild-plugin-yaml) 插件，你可以在 JavaScript 中引用 `.yaml` 或 `.yml` 文件，它们会被自动转换为 JavaScript 对象。 + +import { PackageManagerTabs } from '@theme'; + + + +### 注册插件 + +你可以在 `rslib.config.ts` 文件中注册插件： + +```ts title="rslib.config.ts" +import { pluginYaml } from '@rsbuild/plugin-yaml'; + +export default { + plugins: [pluginYaml()], +}; +``` + +### 示例 + + + + +```js +import { name } from './example.yaml'; + +console.log(name); // 'foo'; +``` + + + + +```yaml +name: foo +items: + - 1 + - 2 +``` + + + + +## TOML 文件 + +[TOML](https://toml.io/en/) 是一种数据序列化语言，通常用于编写配置文件。 + +通过添加 [@rsbuild/plugin-toml](https://github.com/rspack-contrib/rsbuild-plugin-toml) 插件，你可以在 JavaScript 中引用 `.toml` 文件，它们会被自动转换为 JavaScript 对象。 + + + +### 注册插件 + +你可以在 `rslib.config.ts` 文件中注册插件： + +```ts title="rslib.config.ts" +import { pluginToml } from '@rsbuild/plugin-toml'; + +export default { + plugins: [pluginToml()], +}; +``` + +### 示例 + + + + +```js +import { name } from './example.toml'; + +console.log(name); // 'foo'; +``` + + + + +```toml +name = "foo" +items = [1, 2] +``` + + + + +## 类型声明 + +当你在 TypeScript 代码中引用 YAML 或 TOML 文件时，请在项目中创建 src/env.d.ts 文件，并添加相应的类型声明。 + +- 方法一：如果项目里安装了 `@rslib/core` 包，你可以直接引用 `@rslib/core` 提供的**预设类型**： + +```ts title="src/env.d.ts" +/// +``` + +- 方法二：手动添加需要的类型声明： + +```ts title="src/env.d.ts" +declare module '*.yaml' { + const content: Record; + export default content; +} +declare module '*.yml' { + const content: Record; + export default content; +} +declare module '*.toml' { + const content: Record; + export default content; +} +``` From 7886c042c922bca08505cb2d51c8204b3e46d0ed Mon Sep 17 00:00:00 2001 From: Timeless0911 <50201324+Timeless0911@users.noreply.github.com> Date: Tue, 25 Mar 2025 11:27:49 +0800 Subject: [PATCH 2/4] Update website/docs/en/guide/advanced/json-files.mdx --- website/docs/en/guide/advanced/json-files.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/en/guide/advanced/json-files.mdx b/website/docs/en/guide/advanced/json-files.mdx index 96e93a461..497861a66 100644 --- a/website/docs/en/guide/advanced/json-files.mdx +++ b/website/docs/en/guide/advanced/json-files.mdx @@ -1,6 +1,6 @@ # Import JSON files -Rslib supports import JSON files in code. and also supports import [YAML](https://yaml.org/) and [Toml](https://toml.io/en/) files and converting them to JSON format. +Rslib supports importing JSON files in code, and also supports importing [YAML](https://yaml.org/) and [TOML](https://toml.io/en/) files and converting them to JSON format. ## JSON file From 5ebdac913589725e01ba83c8653ac332dc82142f Mon Sep 17 00:00:00 2001 From: Timeless0911 <50201324+Timeless0911@users.noreply.github.com> Date: Tue, 25 Mar 2025 11:27:57 +0800 Subject: [PATCH 3/4] Update website/docs/zh/guide/advanced/json-files.mdx --- website/docs/zh/guide/advanced/json-files.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/zh/guide/advanced/json-files.mdx b/website/docs/zh/guide/advanced/json-files.mdx index 0ce31bbe3..8f16d2961 100644 --- a/website/docs/zh/guide/advanced/json-files.mdx +++ b/website/docs/zh/guide/advanced/json-files.mdx @@ -1,6 +1,6 @@ # 引用 JSON 文件 -Rslib 支持在代码中引用 JSON 文件，同时也支持引用 [YAML](https://yaml.org/) 和 [TOML](https://toml.io/en/) 文件并将其转换为 JSON 格式。 +Rslib 支持在代码中引用 JSON 文件，同时也支持引用 [YAML](https://yaml.org/) 和 [TOML](https://toml.io/cn/) 文件并将其转换为 JSON 格式。 ## JSON 文件 From 18ddd8cbeb7501bd6d069b698209b082df30894f Mon Sep 17 00:00:00 2001 From: ljc Date: Tue, 25 Mar 2025 11:34:54 +0800 Subject: [PATCH 4/4] chore: Update website/docs/zh/guide/advanced/json-files.mdx Co-authored-by: Timeless0911 <50201324+Timeless0911@users.noreply.github.com> --- website/docs/zh/guide/advanced/json-files.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/zh/guide/advanced/json-files.mdx b/website/docs/zh/guide/advanced/json-files.mdx index 8f16d2961..6a85790fa 100644 --- a/website/docs/zh/guide/advanced/json-files.mdx +++ b/website/docs/zh/guide/advanced/json-files.mdx @@ -150,7 +150,7 @@ items: ## TOML 文件 -[TOML](https://toml.io/en/) 是一种数据序列化语言，通常用于编写配置文件。 +[TOML](https://toml.io/cn/) 是一种数据序列化语言，通常用于编写配置文件。 通过添加 [@rsbuild/plugin-toml](https://github.com/rspack-contrib/rsbuild-plugin-toml) 插件，你可以在 JavaScript 中引用 `.toml` 文件，它们会被自动转换为 JavaScript 对象。