> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# JSON

Rslib 支持在代码中引用 JSON 文件，也支持引用 [YAML](https://yaml.org/) 和 [TOML](https://toml.io/cn/) 文件并将其转换为 JSON 格式。

## JSON 文件

你可以直接在 JavaScript 文件中引用 JSON 文件。

:::warning

在 bundle 模式下，JSON 文件支持默认引用和具名引用。

在 bundleless 模式下，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];
```

### 具名引用

Rslib 同样支持通过 named import 来引用 JSON 文件。

下面是一个使用示例，假设源码如下：


**src/index.ts**

```js
import { name } from './example.json';

console.log(name); // 'foo';
```


**src/example.json**

```json
{
  "name": "foo",
  "items": [1, 2]
}
```


会根据配置文件中的 [产物结构](/zh/guide/basic/output-structure.md) 配置，输出如下产物：


**bundle**


**dist/index.js**

```tsx
var example_namespaceObject = {
  u: 'foo',
};
console.log(example_namespaceObject.u);
```



**bundleless**


**dist/index.js**

```tsx
import * as example from './example.js';

console.log(example.name);
```


**dist/example.js**

```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 };
```



### 使用 import attributes

在 bundle 模式下，Rslib 支持 [import attributes](https://github.com/tc39/proposal-import-attributes)，你可以通过 import attributes 来引入 JSON 文件：

```js title="index.js"
import json from './example.json' with { type: 'json' };
```

在 bundleless 模式下，通过 import attributes 引入 JSON 文件时，需要确保产物中保留对 JSON 文件的引用，参考 [文档](#bundleless) 进行配置。

## YAML 文件

[YAML](https://yaml.org/) 是一种数据序列化语言，通常用于编写配置文件。

通过添加 [@rsbuild/plugin-yaml](https://github.com/rstackjs/rsbuild-plugin-yaml) 插件，你可以在 JavaScript 中引用 `.yaml` 或 `.yml` 文件，它们会被自动转换为 JavaScript 对象。


```sh [npm]
npm add @rsbuild/plugin-yaml -D
```

```sh [yarn]
yarn add @rsbuild/plugin-yaml -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-yaml -D
```

```sh [bun]
bun add @rsbuild/plugin-yaml -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-yaml -D
```

### 注册插件

你可以在 `rslib.config.ts` 文件中注册插件：

```ts title="rslib.config.ts"
import { pluginYaml } from '@rsbuild/plugin-yaml';

export default {
  plugins: [pluginYaml()],
};
```

### 示例


**src/index.ts**

```ts
import example from './example.yaml';

console.log(example.hello); // 'world';
console.log(example.foo); // { bar: 'baz' };
```


**src/example.yaml**

```yaml
hello: world
foo:
  bar: baz
```


## TOML 文件

[TOML](https://toml.io/cn/) 是一种语义明显、易于阅读的配置文件格式。

通过添加 [@rsbuild/plugin-toml](https://github.com/rstackjs/rsbuild-plugin-toml) 插件，你可以在 JavaScript 中引用 `.toml` 文件，它们会被自动转换为 JavaScript 对象。


```sh [npm]
npm add @rsbuild/plugin-toml -D
```

```sh [yarn]
yarn add @rsbuild/plugin-toml -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-toml -D
```

```sh [bun]
bun add @rsbuild/plugin-toml -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-toml -D
```

### 注册插件

你可以在 `rslib.config.ts` 文件中注册插件：

```ts title="rslib.config.ts"
import { pluginToml } from '@rsbuild/plugin-toml';

export default {
  plugins: [pluginToml()],
};
```

### 示例


**src/index.ts**

```ts
import example from './example.toml';

console.log(example.hello); // 'world';
console.log(example.foo); // { bar: 'baz' };
```


**src/example.toml**

```toml
hello = "world"

[foo]
bar = "baz"
```


## 类型声明

当你在 TypeScript 代码中引用 YAML 或 TOML 文件时，可以使用以下任一方法添加类型声明：

- 方法一：如果项目里安装了 `@rslib/core` 包，你可以在 `tsconfig.json` 中添加 `@rslib/core` 提供的 [预设类型](/zh/guide/basic/typescript.md#预设类型)：

```json title="tsconfig.json"
{
  "compilerOptions": {
    "types": ["@rslib/core/types"]
  }
}
```

- 方法二：手动添加需要的类型声明：

```ts title="src/env.d.ts"
declare module '*.yaml' {
  const content: Record<string, any>;
  export default content;
}
declare module '*.yml' {
  const content: Record<string, any>;
  export default content;
}
declare module '*.toml' {
  const content: Record<string, any>;
  export default content;
}
```

## 打包模式与输出

Rslib 支持在不同的打包模式下，JSON / YAML / TOML 文件以不同的形式输出。

### bundle

在 bundle 模式下（即 [`bundle: true`](/zh/config/lib/bundle.md)），JSON 文件会被直接打包到 JavaScript 产物中，且 JSON 文件中没有被使用到的 key 会被 tree-shake 掉，TOML 和 YAML 文件同理。

### bundleless

在 bundleless 模式下（即 [`bundle: false`](/zh/config/lib/bundle.md)），每个 JSON / YAML / TOML 文件会被转换为对应的 JavaScript 模块输出，JSON 文件会被转换为 `JSON.parse` 的形式并导出，YAML 和 TOML 文件会被转换为 JavaScript 对象并导出。

如果希望 JSON / YAML / TOML 文件按原样输出到产物目录，并且产物 JavaScript 文件中保留对这些文件的引用路径，可以通过以下方式完成：

1. 在 [source.entry](/zh/config/rsbuild/source.md#sourceentry) 入口文件的 glob 匹配中忽略 JSON / YAML / TOML 文件
2. 在 [output.externals](/zh/config/rsbuild/output.md#outputexternals) 中保留 JSON / YAML / TOML 文件的请求路径
3. 在产物输出中添加 [output.copy](/zh/config/rsbuild/output.md#outputcopy) 选项，指定 JSON / YAML / TOML 文件的输出路径

例如下面的配置将会将 `src` 目录下的所有 JSON 文件按原样输出：

```ts title="rslib.config.ts"
export default defineConfig({
  lib: [
    {
      bundle: false,
      source: {
        entry: {
          index: ['./src/**', '!./src/**/*.json'], // [!code highlight]
        },
      },
      output: {
        // [!code highlight:2]
        copy: [{ from: './**/*.json', context: './src' }],
        externals: [/.*\.json$/],
      },
    },
  ],
});
```