RFC-016 Native and javascript plugin configuration

[hyf0]

• Feature Name: Plugin configuration
• Start Date: 2022/08/15
• Rspack Issue: Nope

Summary

How to config native plugins in node.js

Motivation

We want that users could set up the native plugins in Node.js

Guide-level explanation

How to use native plugins

Let's see that if you want to write a exmaple that how to use native plugins in RSpack, you would write something like

{
  builtins: {
    html: [
      {
        publicPath: '/public',
      }
    ],
    css: {
      modules: true,
    }
  }
}

• We use builtins option to use the native plugin.

How to use js plugins

{
  plugins: [
    new DefinePlugin({
      'process.env.NODE_ENV': 'production',
    })
  ]
}

• A js plugin is a class that extends Plugin class
• To use js plugin in RSpack, you need create a instant of the plugin and pass it into plugins property.

Reference-level explanation

Let's start from the configuration user passed.

{
  plugins: [
    new DefinePlugin({
      'process.env.NODE_ENV': 'production',
    })
  ]
}

Then, we will pass the normalized plugins to rust.

pub type RawPluginOptions = Vec<JsPlugin>

impl RawPluginOptions {
  pub fn normalize(self) -> Vec<Box<dyn Plugin>> {
    let js_plugins = self
      .js_plugins
      .into_iter()
      .map(|p| (p.index, Box::new(p.plugin) as Box<dyn Plugin>))
      .collect::<Vec<_>>();

    js_plugins
  }
}

#[derive(Deserialize, Debug)]
#[napi(object)]
pub struct JsPlugin {}

impl Plugin for JsPlugin {
  // ...
}

After we normalize the plugins options to Vec<Box<dyn Plugin>>, we could just pass it to the RSpack compiler and everthing is OK.

Drawbacks

• Supports the js plugin will slow down the compiler. But for the compatility and extendability it's necessary.

Rationale and alternatives

Nope

Prior art

Nope

Unresolved questions

One to many or one to one for the javascript plugin?

• @H-a-H-a suggest that mapping javascript plugins into one native plugin and re-implement the plugin system in javascript. Because of
  • Less cominucations from rust to javascript
  • Limitation for ordering plugins

Future possibilities

extendability

Nope

[hyf0]

Choosing the one-to-many solution.