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

# Browser Compatibility

## Browserslist Configuration

Modern.js supports three ways to set the range of browsers that a web application needs to support.

### Method 1: Configure via `.browserslistrc` File

Modern.js supports setting the range of browsers that a web application needs to support. You can set the [Browserslist](https://browsersl.ist/) values in the `.browserslistrc` file.

When you create a new Modern.js project, a default `.browserslistrc` configuration is included, which indicates that JavaScript code will be compiled to ES6 format.

```yaml title=".browserslistrc"
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14
```

When the `overrideBrowserslist` configuration is not specified in the project, this `.browserslistrc` file will take effect.

### Method 2: Configure via package.json

You can also configure browserslist by setting the `browserslist` field in the `package.json` file:

```json title="package.json"
{
  "browserslist": [
    "chrome >= 87"
    // Other browser configurations...
  ]
}
```

### Method 3: Configure via `output.overrideBrowserslist`

You can also configure browserslist by setting the [`output.overrideBrowserslist`](/configure/app/output/override-browserslist.md) field in the `modern.config.js` file:

```js title="modern.config.js"
export default {
  output: {
    overrideBrowserslist: [
      'chrome >= 87',
      // Other browser configurations...
    ],
  },
};
```

### Configuration Priority

The `overrideBrowserslist` configuration has a higher priority than the `.browserslistrc` file and the `browserslist` field in package.json.

In most scenarios, it is recommended to prioritize using the `.browserslistrc` file rather than the `overrideBrowserslist` configuration because the `.browserslistrc` file is the officially defined configuration file, has better general applicability, and can be recognized by other libraries in the community.

:::tip
Please refer to [Rsbuild - Setting Browser Range](https://v2.rsbuild.rs/zh/guide/advanced/browserslist) for more information.
:::


## Polyfill

### Compile-time Polyfill

Modern.js by default injects corresponding polyfill code at compile time through [core-js](https://github.com/zloirock/core-js).

By default, it will include the necessary polyfill code based on the project's Browserslist settings, so you generally do not need to worry about polyfill issues for your project source code and third-party dependencies. However, since some unused polyfill code is included, the final bundle size may increase.

:::info
For scenarios where certain third-party dependencies clearly do not require polyfills, you can set [`output.polyfill`](/configure/app/output/polyfill.md) to `usage`. This way, Babel will only inject polyfill code based on the syntax used in the code during compilation.

:::

### 运行时按需 Polyfill

Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) 信息的运行时按需 Polyfill 方案，相比于 Babel 优势如下：

- 不会插入到代码中，只根据访问页面的设备，按需下发 Polyfill 代码 ，减少整体代码体积。
- 相同浏览器会公用一份 Polyfill 代码。因此，随着项目越来越多，基于 UA 的 Polyfill 代码下发速度会越来越快，综合速度超过常规方案。

Modern.js 提供了 `@modern-js/plugin-polyfill` 插件来实现该功能，可以通过安装该插件来开启该功能：


```sh [npm]
npm install @modern-js/plugin-polyfill
```

```sh [yarn]
yarn add @modern-js/plugin-polyfill
```

```sh [pnpm]
pnpm add @modern-js/plugin-polyfill
```

然后在 `modern.config.ts` 中注册 Polyfill 插件:

```ts title="modern.config.ts"
import { polyfillPlugin } from '@modern-js/plugin-polyfill';

export default defineConfig({
  plugins: [..., polyfillPlugin()],
});
```

配置 `output.polyfill` 为 `ua` 并且执行 `pnpm run build && pnpm run serve` 启动服务器后，访问页面可以看到 HTML 产物中包含如下脚本:

```js
<script src="/__polyfill__" crossorigin></script>
```

在 Chrome 51 下访问页面可以看到 `http://localhost:8080/__polyfill__` 返回内容如下:

![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)

:::caution 注意
该功能只有在使用 Modern.js 内置的 Web Server 时才会生效。

如果有自定义模版的需求，请参考 [HTML 模板](/zh/guides/basic-features/html.md)。通过 `html.template` 或 `tools.html` 手动修改模版时，可能会导致该功能无法正确生效。
:::