Browser support

Docusaurus allows sites to define the list of supported browsers through a browserslist configuration.

Purpose

Websites need to balance between backward compatibility and bundle size. As old browsers do not support modern APIs or syntax, more code is needed to implement the same functionality.

For example, you may use the optional chaining syntax:

const value = obj?.prop?.val;

...which unfortunately is only recognized by browser versions released after 2020. To be compatible with earlier browser versions, when building your site for production, our JS loader will transpile your code to a more verbose syntax:

var _obj, _obj$prop;

const value =
  (_obj = obj) === null || _obj === void 0
    ? void 0
    : (_obj$prop = _obj.prop) === null || _obj$prop === void 0
      ? void 0
      : _obj$prop.val;

However, this penalizes all other users with increased site load time because the 29-character line now becomes 168 characters—a 6-fold increase! (In practice, it will be better because the names used will be shorter.) As a tradeoff, the JS loader only transpiles the syntax to the degree that's supported by all browser versions defined in the browser list.

The browser list by default is provided through the package.json file as a root browserslist field.

warning

On old browsers, the compiled output will use unsupported (too recent) JS syntax, causing React to fail to initialize and end up with a static website with only HTML/CSS and no JS.

Default values

Websites initialized with the default classic template has the following in package.json:

package.json

{
  "name": "docusaurus",
  // ...
  "browserslist": ["baseline widely available"]
  // ...
}

Explained in natural language, the browsers supported are the versions of the core browsers (Chrome, Edge, Firefox and Safari, on desktop and mobile) that support all the Baseline Widely available web platform features, i.e. features that have been available in all core browsers for at least 30 months.

The same browser list is used in development and production, so that your site behaves the same with docusaurus start and docusaurus build.

tip

It remains possible to use a different browser list for each environment with an object keyed by environment (production, development). Refer to the browserslist configuration documentation.

You can "evaluate" any config with the browserslist CLI to obtain the actual list:

npx browserslist

The output is all browsers supported. Below is the output in September 2026:

and_chr 151
and_ff 153
chrome 151
chrome 150
...
chrome 123
edge 151
edge 150
...
edge 123
firefox 154
firefox 153
...
firefox 124
ios_saf 26.6
ios_saf 26.5
...
ios_saf 17.4
safari 26.6
safari 26.5
...
safari 17.4

Read more

You may wish to visit the browserslist documentation for more specifications, especially the accepted query values and best practices.