Output Compatibility#

This chapter introduces how to specify which target environment should be supported.

Syntax Downgrade#

By setting lib.syntax, you can choose the syntax to which JavaScript and CSS will be downgraded. You can use the query syntax from Browserslist. Rslib also supports common ECMAScript version numbers, such as ES2015.

Rslib also supports using a .browserslistrc file to specify settings. Note that lib.syntax takes precedence over .browserslistrc. If both are present, lib.syntax will be used.

By default, the syntax is set to ESNext, which will only supports only the latest version of mainstream browsers (Chrome / Firefox / Edge / macOS Safari / iOS Safari) or Node.js according to output.target.

Polyfill#

Before dealing with compatibility issues, it is recommended that you understand the following background knowledge to better handle related issues. Check out the background knowledge on syntax transpilation and API polyfill.

Browser#

Normally, we don't need to inject polyfill for npm packages, this step should be done on the web application framework side, but in some scenarios we need to inject polyfill in order to make our library run directly in low version browsers.

Note that this plugin does not transform your code syntax, it only injects polyfill for unsupported functions used in your code, importing them as normal functions instead of polluting the global. You need to install the core-js-pure dependency.

Set up#

The polyfill relies on Babel to inject the polyfill code, so you need to install the Rsbuild Babel plugin and babel-plugin-polyfill-corejs3 to inject the polyfill code.

npm add @rsbuild/plugin-babel babel-plugin-polyfill-corejs3 -D

And install core-js-pure as the runtime relied code.

npm add core-js-pure

Configure the Babel plugin with polyfill options, set the target field to specify the target browser version.

1import { pluginBabel } from '@rsbuild/plugin-babel';
2import { defineConfig } from '@rslib/core';
3
4export default defineConfig({
5  lib: [
6    {
7      format: 'esm',
8    },
9  ],
10  plugins: [
11    pluginBabel({
12      babelLoaderOptions: {
13        plugins: [
14          [
15            require('babel-plugin-polyfill-corejs3'),
16            {
17              method: 'usage-pure',
18              targets: { ie: '10' },
19              version: '3.29',
20            },
21          ],
22        ],
23      },
24    }),
25  ],
26});

Configurations#

Check out babel-plugin-polyfill-corejs3 documentation for more details.

Node.js#

By using @rsbuild/plugin-node-polyfill, Node core libs polyfills are automatically injected into the browser-side, allowing you to use these modules on the browser side with confidence.

Set up#

Rslib uses @rsbuild/plugin-node-polyfill to provide the Node Polyfill feature.

npm add @rsbuild/plugin-node-polyfill -D

Then add the plugin into the plugins field.

import { defineConfig } from '@rslib/core';
import { pluginNodePolyfill } from '@rsbuild/plugin-node-polyfill';

export default defineConfig({
  lib: [{ format: 'esm' }],
  plugins: [pluginNodePolyfill()],
});

Configurations#

• For projects with bundle enabled, the Node Polyfill will be injected and included in the output.

• For projects with bundle disabled, polyfills are not injected into the output by default. To avoid inlining the polyfill in every module. The modules are externalized and need to be added to dependencies manually, follow these steps:

  1. Configure output.external with resolvedPolyfillToModules, which you can import from @rsbuild/plugin-node-polyfill. This will externalize the polyfill modules to the installed polyfill dependencies.
  2. Install used polyfill modules as dependencies.

  With the following steps, every usage of the polyfill module will be replaced by the corresponding module in the externals field. Checkout the

  Source
  of the example for more details.

Check out the documentation of @rsbuild/plugin-node-polyfill, all the configurations are applicable for Rslib.