Migrating from Rsbuild 0.x#

The document lists all breaking changes from Rsbuild 0.7 to 1.0. You can refer to this document for migration.

See Breaking changes in Rsbuild v1.0.0 for details.

[Important] Lightning CSS loader#

Rsbuild now enables lightningcss-loader by default to transform CSS files, it replaces autoprefixer to add vendor prefixes and provides better performance.

• @rsbuild/plugin-lightningcss has been deprecated and no longer needed.
• tools.autoprefixer config has been removed.

Considering that Lightning CSS has some uncovered edge cases, you can still enable autoprefixer via the postcss config file:

module.exports = {
  plugins: {
    autoprefixer: {},
  },
};

[Important] output.polyfill#

Rsbuild v1 set output.polyfill to 'off' by default, this can reduce the polyfill code and generate smaller bundles by default.

If your application need polyfill, please set output.polyfill to 'usage' or 'entry':

export default {
  output: {
    polyfill: 'usage',
  },
};

[Important] source.decorators#

Rsbuild now uses 2022-11 decorators version by default. This allows Rsbuild to align the default behavior with TypeScript >= 5.0 and esbuild >= 0.21.0.

If you are using the legacy decorators, you can add the following config:

import { defineConfig } from '@rsbuild/core';

export default defineConfig({
  source: {
    decorators: {
      version: 'legacy',
    },
  },
});

[Important] output.targets#

Removed output.targets config, use output.target and environments config instead.

• before:

export default {
  output: {
    targets: ['web', 'node'],
  },
};

• after:

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
      },
    },
  },
};

[Important] Rspack Config Validation#

Rsbuild now enables Rspack's scheme validation by default to ensure the Rspack configuration is correct.

• If there is a type error in the Rspack config object, an error will be thrown and the build will be aborted.
• If there are extra fields in the Rspack config object, an error will be thrown, but the build will not fail.

For more details, see Rspack - RSPACK_CONFIG_VALIDATE.

source.alias#

Removed target param for source.alias function, use environments config instead.

• before:

export default {
  source: {
    alias: (alias, { target }) => {
      if (target === 'node') {
        alias['@common'] = './src/node/common';
      } else if (target === 'web') {
        alias['@common'] = './src/web/common';
      }
    },
  },
  output: {
    targets: ['web', 'node'],
  },
};

• after:

export default {
  environments: {
    web: {
      source: {
        alias: {
          '@common': './src/web/common',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        alias: {
          '@common': './src/node/common',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};

source.entry#

Removed function usage of source.entry, use environments config instead.

• before:

export default {
  source: {
    entry({ target }) {
      if (target === 'web') {
        return {
          index: './src/index.client.js',
        };
      }
      if (target === 'node') {
        return {
          index: './src/index.server.js',
        };
      }
    },
  },
  output: {
    targets: ['web', 'node'],
  },
};

• after:

export default {
  environments: {
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};

output.overrideBrowserslist#

output.overrideBrowserslist no longer supports Record<RsbuildTarget, string[] type, use environments config instead.

• before:

export default {
  output: {
    overrideBrowserslist: {
      web: ['iOS >= 9', 'Android >= 4.4'],
      node: ['node >= 20'],
    },
  },
};

• after:

export default defineConfig({
  environments: {
    web: {
      output: {
        overrideBrowserslist: ['iOS >= 9', 'Android >= 4.4'],
      },
    },
    node: {
      output: {
        overrideBrowserslist: ['node >= 20'],
      },
    },
  },
});

output.emitAssets#

output.emitAssets changed to boolean type, use environments config instead.

• before:

export default {
  output: {
    targets: ['web', 'node'],
    emitAssets: ({ target }) => target !== 'node',
  },
};

• after:

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        emitAssets: false,
      },
    },
  },
};

output.distPath.server#

Removed output.distPath.server, use the environments config instead.

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        distPath: {
          root: 'dist/server',
        },
      },
    },
  },
};

output.minify.html#

Rsbuild v1 removed the output.minify.html and output.minify.htmlOptions options, and no longer minify the HTML files.

Previously Rsbuild uses html-minifier-terser to minify the HTML files. But the performance of html-minifier-terser can not meet the needs of Rsbuild applications, and In most cases, there is little benefit in compressing HTML.

At this stage, Rsbuild will not built-in html-minifier-terser, so we provide a standalone rsbuild-plugin-html-minifier-terser to support HTML minification.

import { pluginHtmlMinifierTerser } from 'rsbuild-plugin-html-minifier-terser';

export default {
  plugins: [pluginHtmlMinifierTerser()],
};

And we plan to use some faster Rust-based HTML minimizer in the future.

output.charset#

The default value of output.charset has been changed from ascii to utf8.

If you need to use ascii, you can add the following config:

export default {
  output: {
    charset: 'ascii',
  },
};

dev.startUrl#

dev.startUrl has been renamed to server.open:

export default {
-  dev: {
+  server: {
-   startUrl: true,
+   open: true,
  }
}

dev.client.port#

The default value of dev.client.port changed from <port> to '' (use location.port).

Use the previous value if you want to keep the behavior:

export default {
  dev: {
    client: {
      port: '<port>',
    },
  },
};

html.appIcon#

Previously, html.appIcon did not support for web app manifests, meaning it was only available on iOS.

Now html.appIcon supports generating web app manifests, and the type of html.appIcon has been changed.

• before:

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

• after:

export default {
  html: {
    appIcon: {
      icons: [{ src: './src/icon.png', size: 180 }],
    },
  },
};

Others#

Rsbuild 1.0 has made some adjustments and optimizations to plugins API and dev server API.

Includes:

• The onBeforeBuild hook supports triggering multiple times in watch mode.
• Added onBeforeEnvironmentCompile and onAfterEnvironmentCompile hooks, which are triggered before/after executing the build of a single environment respectively.
• Removed api.getHtmlPaths and replaced it with environment.htmlPaths.
• Removed api.context.entry and replaced it with environment.entry.
• Removed api.context.targets and replaced it with environment.target.
• Removed rsbuildServer.onHTTPUpgrade and replaced it with rsbuildServer.connectWebSocket.