#Import JSON files

Rslib supports importing JSON files in code, and also supports importing YAML and TOML files and converting them to JSON format.

#JSON file

You can directly import JSON files in JavaScript files.

#Default import

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

import example from './example.json';

console.log(example.name); // 'foo';
console.log(example.items); // [1, 2];

#Named import

Rslib also supports importing JSON files through named import.

Here is an example, assuming the source code is as follows:

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

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

Based on the configuration in the output structure specified in the configuration file, the following outputs will be emitted:

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

#Use import attributes

In bundle mode, Rslib supports import attributes, and you can import JSON files through import attributes:

import json from './example.json' with { type: 'json' };

In bundleless mode, when importing JSON files through import attributes, you need to ensure that references to the JSON files are preserved in the output, refer to document for configuration.

#YAML file

YAML is a data serialization language commonly used for writing configuration files.

By adding the @rsbuild/plugin-yaml plugin, you can import .yaml or .yml files in JavaScript and they will be automatically converted to JavaScript objects.

npm add @rsbuild/plugin-yaml -D

#Register plugin

You can register the plugin in the rslib.config.ts file:

import { pluginYaml } from '@rsbuild/plugin-yaml';

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

#Example

import example from './example.yaml';

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

#TOML file

TOML is a semantically explicit, easy-to-read configuration file format.

By adding the @rsbuild/plugin-toml plugin, you can import .toml files in JavaScript and it will be automatically converted to JavaScript objects.

npm add @rsbuild/plugin-toml -D

#Register plugin

You can register the plugin in the rslib.config.ts file:

import { pluginToml } from '@rsbuild/plugin-toml';

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

#Example

import example from './example.toml';

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

#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:

/// <reference types="@rslib/core/types" />

• Method 2: Manually add the required type declarations:

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

#Bundle mode and output

Rslib supports outputting JSON / YAML / TOML files in different forms under different bundle modes.

#bundle

In bundle mode (bundle: true), JSON files will be directly bundled into JavaScript output, and unused keys in JSON files will be tree-shaken. The same applies to TOML and YAML files.

#bundleless

In bundleless mode (bundle: false), each JSON / YAML / TOML file will be converted into a corresponding JavaScript output file. JSON files will be converted to JSON.parse form and exported, while YAML and TOML files will be converted to JavaScript objects and exported.

If you want JSON / YAML / TOML files to be output to the distribution directory as-is, and keep the reference paths to these files in the output JavaScript files, you can achieve this through the following steps:

1. Exclude JSON / YAML / TOML files from the bundleless entry file glob pattern.
2. Reserve request paths for JSON / YAML / TOML files in output.externals.
3. Add output.copy option to the output configuration, specifying the output path for JSON / YAML / TOML files.

For example, the following configuration will output all JSON files in the src directory as-is:

export default defineConfig({
  lib: [
    {
      bundle: false,
      source: {
        entry: {
          index: ['./src/**', '!./src/**/*.json'],
        },
      },
      output: {
        copy: [{ from: './**/*.json', context: './src' }],
        externals: [/.*\.json$/],
      },
    },
  ],
});