#server.historyApiFallback

• Type: boolean | HistoryApiFallbackOptions
• Default: false

historyApiFallback is used to support routing based on the history API. When a user visits a path that does not exist, it will automatically return a specified HTML file to avoid a 404 error.

When Rsbuild's default page routing behavior cannot meet your needs, for example, if you want to be able to access main.html when accessing /, you can achieve this through the server.historyApiFallback configuration.

#Example

When server.historyApiFallback is set to true, all HTML GET requests that do not match an actual resource will return index.html. This ensures that routing in single-page applications works correctly.

export default {
  server: {
    historyApiFallback: true,
  },
};

Rsbuild will change the requested location to the index you specify whenever there is a request which fulfills the following criteria:

• The request is a GET or HEAD request
• The request accepts text/html
• The requested path does not contain a . (dot), meaning it is not a direct file request
• The requested path does not match any pattern defined in rewrites

#Options

server.historyApiFallback also supports passing an object to customize its behavior.

#index

• Type: string
• Default: 'index.html'

By setting historyApiFallback.index to main.html, when accessing the root path / or other routes that may result in a 404, the page will automatically redirect to main.html.

export default {
  source: {
    entry: {
      main: './src/index.ts',
    },
  },
  server: {
    htmlFallback: false,
    historyApiFallback: {
      index: '/main.html',
    },
  },
};

#rewrites

• Type:

type Rewrites = Array<{
  from: RegExp;
  to: string | ((context: HistoryApiFallbackContext) => string);
}>;

• Default: []

When your application contains multiple entries, you may need to redirect different paths to different pages. In this case, you can configure more flexible redirection rules through the rewrites option:

export default {
  server: {
    historyApiFallback: {
      rewrites: [
        { from: /^\/$/, to: '/views/landing.html' },
        { from: /^\/subpage/, to: '/views/subpage.html' },
        { from: /./, to: '/views/404.html' },
      ],
    },
  },
};

#htmlAcceptHeaders

• Type: string[]
• Default: ['text/html', '*/*']

Override the default Accepts: headers that are queried when matching HTML content requests.

export default {
  server: {
    historyApiFallback: {
      htmlAcceptHeaders: ['text/html', 'application/xhtml+xml'],
    },
  },
};

#disableDotRule

• Type: boolean
• Default: false

By default, requests containing a dot (.) in the path are treated as direct file requests and are not redirected.

Setting disableDotRule to true will disable this behavior and allow such requests to be redirected as well.

export default {
  server: {
    historyApiFallback: {
      disableDotRule: true,
    },
  },
};