RFC-008: The Interfaces for Users

[bvanjoi]

The Interfaces for Users

Expected

We need to provide a set of interfaces which is easy for users to understand and use. Among module bundler for JavaScript, Webpack is the most widely used and mature tool that provides a set of well known concepts, so we tried to align the configuration files of the implemented features on JavaScript side with it as much as possible.

Detailed design

Let's take the design of the resolve as an example.

Webpack implements a complex set of features with enhanced-resolve, In addition to the most basic features such as extensions, mainFiles, It also provides some less commonly used fields such as byDependency, let's discuss the different scenarios based on the above cases one by one.

order	name
1	alias
2	aliasFields
3	cacheWithContext
4	conditionNames
5	descriptionFiles
6	enforceExtension
7	extensionAlias
8	extensions
9	fallback
10	mainFields
11	mainFiles
12	exportsFields
13	modules
14	unsafeCache
15	useSyncFileSystemCalls
16	plugins
17	preferRelative
18	preferAbsolute
19	symlinks
20	cachePredicate
21	restrictions
22	roots
23	importsFields
24	byDependency

• For the most foundation and important features, such as order 1, 2, 4, 8, 11, 17, 19, there is no ambiguity about theses basic functions, either in terms of interface meaning or in terms of function usage, and as the most basic functions of the bundler, we should ensure that the usage is consistent with that in Webpack.

  // webpack
  module.exports = {
    resolve: {
      extensions: ['.ts', '.js']
    }
  }
  
  // rspack
  module.exports = {
    resolve: {
      extensions: ['.ts', '.js']
    }
  }

• For those interfaces that are essential, but the effect is not completely consistent, such as 5, 10, 13, 12, 23, we had to redesign the API. For example, enhanced-resolve provide a field called modules, its default value is ['node_modules'], and it means to when trying to resolve a file imported from a library, the value in the modules array will be used as the directory of the library. However, it is known that libraries downloaded from npm are generally stored in the node_modules directory of the current project, of course, bower is special cases, but I don't think we should pay for changing special circumstances. The rest fields have similar problems.

  // webpack
  module.exports = {
    resolve: {
      aliasField: ['browser']
    }
  }
  
  // rspack
  module.exports = {
    resolve: {
      browserField: true
    }
  }

• For features that are not implemented, such as 7, 9, 16, 18, 20, 22, 24, they can be grouped into two categories, those that are not supported at the moment because their functionality is less used, such as the new field extensionsAlias added in version 5.10.0. The other is a feature that cannot be implemented due to its own technical selection, such as plugins.

• For these features which are not implemented by enhanced-resolve but had implemented by rspack, such as the shared cache among different resolver, we should design the API according to the corresponded features.

Also, here are some explications on why the API is aligned in JavaScript side: due to the Rust is a strongly typed language, so we had to use the explicit type in Rust side, for example for the field of resolve.alias, we need to use an enum type such as AliasMap::Ignored or AliasMap::To('./a.js'), it's very inconvenient.

Test for API

For testing of interfaces, the solution of Webpack is worthy of reference, as it puts all API-related test cases into a folder called tests/configCases, which is worth we can learn from.

Three Sections

The project is used to build JavaScript projects, so the configuration interfaces are divided into three:

• the interface on JavaScript;
• the interface on Rust;
• and the binding that bridges the two.

The flow of data is:

node interface -----------------> binding options    ---------------->   rust interface
                    normalized                          normalized

[hyf0]

I suggest that we support both rspack.config.json and rspack.config.{js,ts}. I intend that we could write tests in pure rust(just like now) if we support `rspack.config.json.

[hyf0]

I think the key is that whether we consider RSpack + node binding as a whole or only RSpack itself.

[hardfist]

maybe .rspackrc for rust，rspack.config.ts for js binding

[liuliudada-w]

The case where the parameter type is regular or function may need to be discussed separately, in some cases this ability is very useful. Especially when we are going to support json

[hyf0]

The config in JSON format is only a subset in JS format.

[h-a-n-a]

It looks good to me for the content you provided. On top of that, another goal of this RFC is to maintain a unified experience for both rust and node users.

1. Could you shed more light on the detail of the implementation of interop between rust native and node binding? For example, how can we pass enums between these two sides efficiently(how do we serialize and deserialize for enums)?

2. Currently, a workaround(the rust's orphan rule) has to be provided to get rust types to implement traits of Napi, the example are as follows:

// crates/node_binding

// This is the JavaScript function we want to expose to the Node side.
// Developers have to convert `rspack_core::Stats` to a trait `Napi` implemented custom `Stats` type

#[napi(object)]
struct Stats {
  // fields omitted, but It's the same with `rspack_core` under this situation ;
}

#[napi]
pub async fn build() -> Stats {
   let rspack_core_stats: rspack_core::Stats = compiler.compile().await?;
   // convert `rspack_core_stats` to the custom one and return it.
}

This is a real pain in the ass for us to handle the conversion. Is there any possibility we can simplify this?