#server.publicDir

• Type:

type PublicDirOptions = {
  name?: string;
  copyOnBuild?: boolean | 'auto';
  ignore?: string[];
  watch?: boolean;
};
type PublicDir = false | PublicDirOptions | PublicDirOptions[];

• Default:

const defaultValue = {
  name: 'public',
  copyOnBuild: 'auto',
  ignore: [],
  watch: false,
};

By default, Rsbuild uses the public directory for serving public assets. Files in this directory are served at server.base path (default /).

Related document: Public Folder.

#Options

#name

• Type: string
• Default: 'public'

The name of the public directory. The value of name can be set to a relative path or an absolute path. Relative path will be resolved relative to the project root directory.

• Relative path example:

export default {
  server: {
    publicDir: {
      name: '../some-public',
    },
  },
};

• Absolute path example:

import path from 'node:path';

export default {
  server: {
    publicDir: {
      name: path.join(__dirname, '../some-public'),
    },
  },
};

#copyOnBuild

• Type: boolean | 'auto'
• Default: 'auto'

Whether to copy files from the public directory to the dist directory on production build.

• true: copy files.
• false: do not copy files.
• 'auto': if output.target is not 'node', copy files, otherwise do not copy.

#Disable

For example, disable copyOnBuild:

export default {
  server: {
    publicDir: {
      copyOnBuild: false,
    },
  },
};

Note that setting the value of copyOnBuild to false means that when you run rsbuild preview for a production preview, you will not be able to access the corresponding static resources.

#Node target

By default, when output.target is 'node', Rsbuild will not copy files from the public directory.

You can set copyOnBuild to true to copy files for the node target:

export default {
  output: {
    target: 'node',
  },
  server: {
    publicDir: {
      copyOnBuild: true,
    },
  },
};

#ignore

• Type: string[]
• Default: []

Glob patterns for files or directories to ignore when copying the public directory during production builds.

This option only affects the copy behavior during build. It does not affect static file serving in the dev server.

For example, ignore foo.js when copying the public directory:

export default {
  server: {
    publicDir: {
      ignore: ['**/foo.js'],
    },
  },
};

#watch

• Type: boolean
• Default: false

Whether to watch the public directory and reload the page when the files change.

Setting watch to true allows the dev server to watch changes to files in the specified public directory and reload the page when the files are changed:

export default {
  server: {
    publicDir: {
      watch: true,
    },
  },
};

Note that the watch option is only valid in development mode. If dev.hmr and dev.liveReload are both set to false, watch will be ignored.

#Multiple directories

The server.publicDir can be configured as an array, allowing you to serve multiple directories as static assets folders:

export default {
  server: {
    publicDir: [
      {
        name: 'public',
      },
      {
        name: 'assets',
        watch: false,
      },
    ],
  },
};

#Disabled

You can set publicDir to false to disable the static assets serving:

export default {
  server: {
    publicDir: false,
  },
};

#Multiple environments

#Directory configuration

• Version: >= 2.3.0

Set server.publicDir for each environment under environments. If an environment omits publicDir, it inherits the global server.publicDir. Set publicDir: false to disable public directories for that environment.

export default {
  environments: {
    client: {},
    admin: {
      server: {
        publicDir: {
          name: 'public-admin',
        },
      },
    },
    worker: {
      server: {
        publicDir: false,
      },
    },
  },
};

In this example, client uses public, admin uses public-admin, and worker has no public directory.

During development, all environments share one dev server, which serves the public files configured by each environment. Setting publicDir: false in one environment does not affect access to public files from other environments.

#Configuration inheritance

An environment's own publicDir replaces the global publicDir. Omitted options use their default values.

export default {
  server: {
    publicDir: {
      name: 'assets',
    },
  },
  environments: {
    client: {
      server: {
        publicDir: {
          copyOnBuild: false,
        },
      },
    },
  },
};

Here, client does not set name, so it uses the default directory public. To use assets, also set name: 'assets' in client.server.publicDir.

Even when the global publicDir is false, an environment can enable its own public directories by setting publicDir to an object or array.

#Build behavior

During production builds, each environment copies files from its public directories to its output directory. copyOnBuild controls whether files are copied, and ignore specifies which files to exclude.

For example, two web environments using the default publicDir settings copy public/logo.png as follows:

If the directory lists, directory order, or copyOnBuild and ignore settings differ, each environment copies files to its own output directory, even when the output directories are nested.

#Version history