#html.favicon

• Type: string | Function
• Default: Automatically detects favicon files in the public directory

Sets the favicon for all pages. Rsbuild handles the value as follows:

• URL: Uses the URL directly without downloading the file.
• Local file path: Copies the file to the output directory during compilation. The path can be absolute or relative to the project root.

In both cases, Rsbuild adds a <link> tag for the favicon to the HTML.

#Default value

When html.favicon is not explicitly configured, Rsbuild will automatically look for favicon files in the public directory.

It searches for the following files in order, and uses the first one it finds as the default favicon:

• public/favicon.ico
• public/favicon.png
• public/favicon.svg

#Example

Set as a relative path:

export default {
  html: {
    favicon: './src/assets/icon.png',
  },
};

Set to an absolute path:

import path from 'node:path';

export default {
  html: {
    favicon: path.resolve(__dirname, './src/assets/icon.png'),
  },
};

Set to a URL:

export default {
  html: {
    favicon: 'https://foo.com/favicon.ico',
  },
};

After recompiling, the following tags are automatically generated in the HTML:

<link rel="icon" href="https://foo.com/favicon.ico" />

#Output path

By default, favicons are output to the root path of the output directory, for example:

• ./src/assets/icon.png will be output to ./dist/icon.png.
• ./src/assets/favicon.ico will be output to ./dist/favicon.ico.

You can customize the output path for favicons using the output.distPath.favicon option:

export default {
  output: {
    distPath: {
      // Output favicon to "./dist/static/favicon/" directory
      favicon: 'static/favicon',
    },
  },
};

#Function usage

• Type:

type FaviconFunction = (context: {
  value: string;
  entryName: string;
}) => string | void | Promise<string | void>;

When html.favicon is of type Function, the function receives an object as input, with the following properties:

• value: the default favicon configuration for Rsbuild.
• entryName: the name of the current entry.

In the context of MPA (Multi-Page Application), you can return different favicon based on the entry name, thus generating different tags for each page:

export default {
  html: {
    favicon({ entryName }) {
      const icons = {
        foo: 'https://example.com/foo.ico',
        bar: 'https://example.com/bar.ico',
      };
      return icons[entryName] || 'https://example.com/default.ico';
    },
  },
};

#Version history