Breaking changes in Rsbuild v1.0.0

[chenjiahan]

Rsbuild v1.0.0 is scheduled to be released in July 2024.

This thread is used to collect planned breaking changes for Rsbuild v1.0.0.

[chenjiahan]

Upgrade Rspack v1.0.0

Rsbuild v1.0.0 will upgrade the dependent @rspack/core to v1.0.0.

Rspack v1.0.0 contains some breaking changes, see web-infra-dev/rspack#6626 for more details.

[chenjiahan]

Rename dev.startUrl

Changes:

• Rename dev.startUrl to server.open.
• Rename dev.beforeStartUrl to server.open.before.

Motivation:

• Align with Rspack dev server's open config.
• Allow to use in the preview server.

[chenjiahan]

#2642

[9aoy]

Replace output.targets with output.target

Replace output.targets with output.target, and rsbuild will generate rspack / webpack configs based on environments instead of output.targets.

Details: #2636

[chenjiahan]

output.overrideBrowserslist

output.overrideBrowserslist no longer supports Record<RsbuildTarget, string[] type for environment configuration.

• 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'],
      },
    },
  },
});

[chenjiahan]

#2646

[chenjiahan]

#2648

[chenjiahan]

output.emitAssets

output.emitAssets changed to boolean type for environment configuration.

• 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,
      },
    },
  },
};

[chenjiahan]

#2649

[chenjiahan]

source.alias

Remove target param for source.alias function, use environment configuration 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',
      },
    },
  },
};

[chenjiahan]

#2650

[chenjiahan]

Decorators Version

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:

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';

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

SWC currently does not support 2023-11, when this PR (swc-project/swc#8970) is merged, we can consider use 2023-11 by default.

[Verthon]

SWC closed linked PR swc-project/swc#8970 in favor of swc-project/swc#9488

[chenjiahan]

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',
        },
      },
    },
  },
};

[chenjiahan]

#2696

[chenjiahan]

source.entry

Remove 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',
      },
    },
  },
};

[chenjiahan]

#2697

[9aoy]

api.getHTMLPaths

Remove api.getHtmlPath, use environment htmlPaths instead.

• before:

const pluginFoo = () => ({
  setup(api) {
    api.modifyRspackConfig(() => {
      const htmlPaths = api.getHTMLPaths();
      console.log(htmlPaths); // { index: 'index.html' };
    });
  },
});

• after:

const pluginFoo = () => ({
  setup(api) {
    api.modifyRspackConfig((config, { environment }) => {
      const { htmlPaths } = environment;
      console.log(htmlPaths); // { index: 'index.html' };
    });
  },
});

[9aoy]

#2771

[9aoy]

api.context

Remove api.context.entry and api.context.targets, and the distPath and tsconfigPath may be different in different environments, should use environment / environments param instead.

const pluginFoo = () => ({
  setup(api) {
      api.modifyBundlerChain((chain, { environment }) => {
-        const { entry,  targets, tsconfigPath, distPath } = api.context;
+        const { entry, tsconfigPath, distPath, config: { output: { target } } } = environment;
    });
    api.onDevCompileDone(async ({ isFirstCompile, stats, environments }) => {
-      const entries = Object.keys(api.context.entry);
+      const entries = Object.values(environments).map(e => e.entry);
    })
  },
});

[9aoy]

#2680
#2721
#2768

[chenjiahan]

output.polyfill

Rsbuild 1.0.0-alpha.4 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':

// rsbuild.config.ts
export default {
  output: {
    polyfill: 'usage'
  }
};

See the vote on Twitter: https://x.com/rspack_dev/status/1808439138439274780

[chenjiahan]

#2804

[chenjiahan]

Remove output.minify.html

Rsbuild 1.0.0-alpha.6 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, we do not want to builtin html-minifier-terser , so we provide a standalone rsbuild-plugin-html-minifier-terser to support HTML minification.

// rsbuild.config.ts
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.

[chenjiahan]

#2833

[chenjiahan]

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',
  },
};

[chenjiahan]

See #3244 for more details