#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

Set server.historyApiFallback to true to serve index.html for unmatched requests that meet the conditions below.

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 Accept header contains text/html or */* (the default accepted values) and does not start with application/json
• The last path segment does not contain a . (dot), unless disableDotRule is enabled
• 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'

Specifies the default HTML file to return when the History API fallback is enabled.

For example, if you set historyApiFallback.index to /main.html, the server will automatically serve main.html as the fallback page when users access any unmatched routes.

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

#rewrites

• Type:

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

• Default: []

rewrites lets you customize how request paths are mapped to HTML files when a History API fallback occurs.

When no static asset matches the request, Rsbuild checks these rules in order and applies the first match. Rewrites run before the dot rule. They change the URL within the server without sending an HTTP redirect.

export default {
  server: {
    historyApiFallback: {
      rewrites: [
        // Serve the landing page for the root path
        { from: /^\/$/, to: '/views/landing.html' },
        // Return subpage.html for any path starting with /subpage
        { from: /^\/subpage/, to: '/views/subpage.html' },
        // Return a custom 404 page for all other paths
        { from: /./, to: '/views/404.html' },
      ],
    },
  },
};

#htmlAcceptHeaders

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

Specify the values to match in the request’s Accept header. Requests whose Accept header starts with application/json are skipped even if they also match this list.

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

#disableDotRule

• Type: boolean
• Default: false

By default, unmatched requests containing a dot (.) in the last path segment are treated as file requests and are not rewritten to index.

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

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