Output Files#

This chapter will introduces the directory structure of output files and how to control the output directory of different types of files.

If you want to know how to deploy the build outputs of Rsbuild as a static site, please refer to Deploy Static Site.

Default Directory Structure#

The following is a basic directory for output files. By default, the compiled files will be output in the dist directory of current project.

dist
├── static
│   ├── css
│   │   ├── [name].[hash].css
│   │   └── [name].[hash].css.map
│   │
│   └── js
│       ├── [name].[hash].js
│       ├── [name].[hash].js.LICENSE.txt
│       └── [name].[hash].js.map
│
└── [name].html

The most common output files are HTML files, JS files, and CSS files:

• HTML files: default output to the root of dist directory.
• JS files: default output to static/js directory,
• CSS files: default output to the static/css directory.

In addition, JS files and CSS files sometimes generate some related files:

• License files: contains open source license, which is output to the same level directory of the JS file, and adds .LICENSE.txt suffix.
• Source Map files: contains the source code mappings, which is output to the same level directory of JS files and CSS files, and adds a .map suffix.

In the filename, [name] represents the entry name corresponding to this file, such as index, main. [hash] is the hash value generated based on the content of the file.

Modify the Directory#

Rsbuild provides some configs to modify the directory or filename, you can:

• Modify the filename through output.filename.
• Modify the output path of through output.distPath.
• Modify the license file through output.legalComments.
• Modify Source Map file through output.sourceMap.
• Modify the output structure of the HTML files through html.outputStructure.

Static Assets#

When you import static assets such as images, SVG, fonts, media, etc. in the code, they will also be output to the dist/static directory, and automatically assigned to the corresponding subdirectories according to the file type:

dist
└── static
    ├── image
    │   └── foo.[hash].png
    │
    ├── svg
    │   └── bar.[hash].svg
    │
    ├── font
    │   └── baz.[hash].woff2
    │
    └── media
        └── qux.[hash].mp4

You can use the output.distPath config to uniformly input these static assets into a directory, for example, output to the assets directory:

export default {
  output: {
    distPath: {
      image: 'assets',
      svg: 'assets',
      font: 'assets',
      media: 'assets',
    },
  },
};

The above config produces the following directory structure:

dist
└── assets
    ├── foo.[hash].png
    ├── bar.[hash].svg
    ├── baz.[hash].woff2
    └── qux.[hash].mp4

Node.js Output Directory#

When the output.targets of Rsbuild contains 'node', or you have enabled server-side features such as SSR in the higher level solutions, Rsbuild will generate some output files for Node.js and output them to the server directory:

dist
├── server
│   └── [name].js
├── static
└── [name].html

Node.js files usually only contain JS files, no HTML or CSS. Also, JS file names will not contain hash.

You can modify the output path of Node.js files through the output.distPath.server config.

For example, output Node.js files to the server directory:

export default {
  output: {
    distPath: {
      server: 'server',
    },
  },
};

Flatten the Directory#

Sometimes you don't want the dist directory to have too many levels, you can set the directory to an empty string to flatten the generated directory.

See the example below:

export default {
  output: {
    distPath: {
      js: '',
      css: '',
    },
  },
};

The above config produces the following directory structure:

dist
├── [name].[hash].css
├── [name].[hash].css.map
├── [name].[hash].js
├── [name].[hash].js.map
└── [name].html

Writing Outputs to Disk#

By default, Rsbuild does not write the output files to disk during development. Instead, the files are stored in the memory of the dev server to reduce the overhead of file operations.

You can write the output files to disk, which is typically used for inspecting the contents of the build artifacts or configuring proxy rules for static assets.

Set the dev.writeToDisk configuration option to true as follows:

export default {
  dev: {
    writeToDisk: true,
  },
};