Breaking change: moving builtins options to builtin plugins

[ahabhgk]

In webpack, lots of common used features can be added by plugins, HTMLWebpackPlugin, webpack.DefinePlugin, webpack.ProvidePlugin, webpack.ExternalsPlugin, etc. In early stage of Rspack, we want to implement these common used features without slow down the performance by JS plugins, so we introduced the builtins options, and implement these common used features under the builtins options, with good performance of course, but as time goes on, we found that the builtins options causes some problems.

• Hard to migrate from existing webpack config, builtins options only exists in Rspack, when you migrate a existing webpack project to Rspack, not all config is compatible, and most of them are under builtins options.
• Incompatible with existing webpack plugin in community, some of the existing webpack plugin depend on webpack's internal plugins, for example, node-polyfill-webpack-plugin depend on webpack.ProvidePlugin, webpack-dev-server depend on webpack.HotModuleReplacementPlugin, for these plugins, we have to (re)write our own version plugins.
• Can't fine-granular control some of the Rspack's behavior, for example, disable JS minify but enable CSS minify, use lightingcss to minify CSS, add entry dynamically by EntryPlugin. Rspack can't do these for now with builtins options, but webpack can do these with plugins.

So, to resolve these problems in Rspack, we propose another kind of plugin in addition to the JS plugin: builtin plugin.

Builtin plugins are a set of internal Rspack plugin, written by Rust, and can be used by rspack.XxxPlugin.

And we use rspack.XxxRspackPlugin naming convention for those plugins that commonly used in webpack community, and ported into Rspack rust side for performance reason.

// before builtin plugins:
module.exports = {
  builtins: {
    html: [{ template: 'index.html' }],
    define: {
      'process.env.NODE_ENV': JSON.stringify('production'),
      'process.env.XXX': JSON.stringify('xxx'),
    },
    minifyOptions: {},
  }
}

// after builtin plugins:
const { rspack } = require("@rspack/core")
module.exports = {
  plugins: [
    new rspack.HtmlRspackPlugin({ template: 'index.html' }),
    new rspack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production'),
      'process.env.XXX': JSON.stringify('xxx'),
    }),
    new rspack.SwcJsMinimizerRspackPlugin({}),
    new rspack.LightingCssMinimizerRspackPlugin({}),
  ]
}

Builtin plugins will replace some of the builtins options, and others builtins options will be replaced by builtin:swc-loader:

• builtins.define => rspack.DefinePlugin
• builtins.provide => rspack.ProvidePlugin
• builtins.banner => rspack.BannerPlugin
• builtins.minifyOptions => rspack.SwcJsMinimizerRspackPlugin and rspack.SwcCssMinimizerRspackPlugin
• builtins.html => rspack.HtmlRspackPlugin
• builtins.progress => rspack.ProgressPlugin
• builtins.copy => rspack.CopyRspackPlugin
• builtins.css => experiments.css (builtins css is the peer implementation of experiments css, so this probably will be moved to experiments.css)
• builtins.devFriendlySplitChunks => rspack.DevFriendlySplitChunksRspackPlugin (this is used to speed up bundle-splitting in development mode, but after we refactor the implementation of SplitChunksPlugin in v0.2, the performance problem is solved, so you don't need this anymore and this probably will be removed)
• builtins.treeShaking => rspack.TreeShakingRspackPlugin (we are refactoring our implementation of tree shaking, and the config will align with webpack: optimization.sideEffects, optimization.provideExports, optimization.innerGraph, and optimization.usedExports, so this probably will be removed or be a plugin which alias for these config under the hood, we will decide after we finish the refactor)
• builtins.noEmitAssets => rspack.NoEmitAssetsRspackPlugin (this is an alternative implement for memory output file system, since we already implement memory output file system, so you don't need this anymore and this probably will be removed)
• builtins.react => builtin:swc-loader
• builtins.decorator => builtin:swc-loader
• builtins.emotion => builtin:swc-loader
• builtins.pluginImport => builtin:swc-loader
• builtins.relay => builtin:swc-loader

we will deprecate builtins options in 0.3.x and builtin plugins and builtin:swc-loader will be the recommended way, we will provide a guide for users to migrate smoothly. And deprecate doesn't mean drop support, we will still support builtins options for at least 2 minor versions (0.4.x, 0.5.x) and drop support in 0.6.0.

[ruanjonker]

Do it!

[9aoy]

@ahabhgk I see that SwcJsMinimizerPlugin is added in plugins, not in optimization.minimizer, are you sure?

const { rspack } = require("@rspack/core")
module.exports = {
  plugins: [
    new rspack.SwcJsMinimizerPlugin({}),
    new rspack.LightingCssMinimizerPlugin({}),
  ]
}

[ahabhgk]

Oh, indeed I forgot optimization.minimizer when I wrote it, but actually they are the same under the hood, optimization.minimizer is the best place but plugins also works

[ScriptedAlchemy]

To be honest I'm quite a fan of builtins. First experience with rspack, builtins let me remove massive amounts of configs and it just worked. If I needed extra customization I could implement as plugin but it was great to have a non webpacky set of quick options.

We need to support these as plugins. Just because many destructure these and use them to compose other plugins, and for advanced customization- it may offer more controls.
But, if I have a simple build requirement - builtins offer a very easy way to get started.

If I need more control I can turn off builtins and use plugin, or loader. But the majority of my quick POC or testing apps or initial interactions of a codebase would likely work fine using builtins. As more refinement is needed, we offer it but there's not an upfront cost to using rspack. Could be easy, but powerful.

If not in rspack core. We should provide a similar abstraction with smaller api surface or something with lots of builtins. This could appeal to users who like rollup or esbuild just because it's not as heavy to configure as webpack. Rspack-lite api could provide fast powerful builds but with rollup simplicity.

[hardfist]

since we all agree that builtin plugin is necessary, so the problem is how we keep the simplicity of builtins

support some utils function like defineLiteConfig, it will convert builtins options to plugin under the hood

import { defineLiteConfig } from '@rspack/core';
export default defineLiteConfig({
  builtins: {
     define: {
      'process.env.NODE_ENV': JSON.stringify('production'),
      'process.env.XXX': JSON.stringify('xxx'),
     }
  }
});

it will be converted to the following under the hood

export default defineConfig({
  plugins: [
       new rspack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production'),
      'process.env.XXX': JSON.stringify('xxx'),
    }),
  ]
});

so the core itself doesn't need to be aware of builtins itself and keep alignment with webpack, all the maintain work is on defineLiteConfig itself, users who don't want the magic can still use plugins, it can also ease the migration work, you can just print the output of defineLiteConfig and set it to defineConfig, no more magic

support things called preset

we toggle the functionality by config called preset, but it seems too magic to me and make the core alignment with webpack harder

export default defineConfig({
  preset: 'builtin',
  builtins: {
     define: {
      'process.env.NODE_ENV': JSON.stringify('production'),
      'process.env.XXX': JSON.stringify('xxx'),
     }
  }
});

it will be converted to the following under the hood

export default defineConfig({
  preset: 'basic',
  plugins: [
       new rspack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production'),
      'process.env.XXX': JSON.stringify('xxx'),
    }),
  ]
});

provide light abstraction by community

we still only support plugin, but can provide defineLiteConfig by third party library like rspack-utils.

import { defineLiteConfig } from 'rspack-utils';
export default defineLiteConfig({
  builtins: {
     define: {
      'process.env.NODE_ENV': JSON.stringify('production'),
      'process.env.XXX': JSON.stringify('xxx'),
     }
  }
});

[ahabhgk]

I prefer preset since webpack also have plan for that webpack/webpack#17171

and we can also provide a plugin for this:

import BuiltinsOptionsPlugin from "@rspack/builtins-options-plugin"
export default {
  plugins: [
    new BuiltinsOptionsPlugin({ // defineLiteConfig or other "lite" cli can also use this under the hood
      define: {},
      react: {},
      // ...
    })
  ]
}

[hardfist]

cc @ScriptedAlchemy what's your suggestion here?

[ScriptedAlchemy]

Excellent observation regarding the webpack preset.

I appreciate the simplicity of builtins, where it's just: preset: {react:true}

However, I believe BuiltinsOptionsPlugin could provide more composability and flexibility. Given that webpack follows a similar pattern, aligning with this method could simplify potential future integrations when webpack decides to merge. As a plugin, it also allows for extensions and so on. Therefore, this could be a viable approach:

new BuiltinsOptionsPlugin({ // defineLiteConfig or other "lite" CLI could also utilize this internally
  define: {},
  react: {},
  // ...
})

If we aim to abstract further, we could follow the approach used by webpackOptionsApply with externals or target: 'node'.

[h-a-n-a]

Detailed design for swc-loader related features:

{
   builtins: {
      emotion: {},
      relay: {}
   } 
}

Will be converted to the internal builtin:swc-loader visitor, using a rspackExperiments
namespace(with a rspack namespace) for that:

{
  module: {
    rules: [{
      loader: "builtin:swc-loader",
      options: {
         rspackExperiments: { emotion: {}, relay: {} }
      }
    }]
  }
}

This feature is not stable and subject to change.

wasm-plugin will be supported in the future.

[ScriptedAlchemy]

I do like how the built-in loaders are expressed, very useful for customization.