How to do CommonJS Output

[dhouck]

Rsbuild version: v2.1.13.

Iʼm trying to set up Rsbuild for the first time, and I do not have Rslib (maybe I should use it, but I havenʼt installed it yet and Iʼm not sure I should). The target is neither Node nor web, but a java program which embeds the Rhino engine, which only supports CJS and not ESM.

First, since CJS/ESM options seem to partially depend on target: It looks like even though the target is not Node, I should be setting output.target to "node" anyway, and that this will propagate to Rspackʼs target field? (And then to get the right output I can set SWC or Babel to target Rhino specifically)

But with that it looks like the only documented option in Rsbuild is to use CJS output instead of ESM output is setting output.module to false, which changes to a CJS module, but also for some reason wraps the entire output in an IIFE. Itʼs also possible to go through Rspack and set tools.rspack.output.library.type to "commonjs2", which does not do the IIFE thing; is there a downside to jumping to the lower-level option?

Finally, something which is completely not documented as far as I can tell, and which doesnʼt seem like it should work: even though I do not have Rslib installed at all, setting lib.format to "cjs" also seems to work. Why does this happen, is it a stable feature, and should it be documented?

Are any of these the right way to force CJS?

[dhouck]

(As a side note, I find everything about CJS vs ESM more confusing than I should and always need to look up details, so itʼs not impossible Iʼm confused somewhere, but saying that the CJS output is not a module seems wrong and I think it adds extra confusion. Itʼs not an ESM module, but it has module.exports, and in general acts like a module in most respects)

[chenjiahan]

I’m not very familiar with Rhino, but you could try treating it as a Node-like CommonJS target:

export default {
  output: {
    target: 'node',
    module: false,
  },
  splitChunks: false,
  tools: {
    rspack: {
      output: {
        asyncChunks: false,
      },
    },
  },
};

This produces a CommonJS bundle using module.exports and avoids extra chunks. If the IIFE wrapper is incompatible with your runtime, you can also try tools.rspack.output.iife: false.

Rslib is built on top of Rsbuild and focuses on library development. lib.format is an Rslib-specific option, so it should not be used in an Rsbuild config.

[dhouck]

See, I thought it was Rslib-specific, but itʼs still doing stuff without Rslib installed. So it clearly has some meaning in just Rsbuild; something is reading it and saying the output is commonjs.

[barry166]

From Rsbuild core, I would not treat lib.format as stable Rsbuild config. The CommonJS switch in Rsbuild is output.module: false; for a node target, the output plugin maps that to Rspack output.library.type: 'commonjs2' here: https://github.com/web-infra-dev/rsbuild/blob/main/packages/core/src/plugins/output.ts#L131-L137. The default is also set from output.target === 'node' in init config: https://github.com/web-infra-dev/rsbuild/blob/main/packages/core/src/initConfigs.ts#L142-L145.

So for this case I would stay on the documented path:

export default {
  output: {
    target: 'node',
    module: false,
  },
  splitChunks: false,
  tools: {
    rspack: {
      output: {
        asyncChunks: false,
        iife: false,
      },
    },
  },
}

If lib.format: 'cjs' appears to change the output, I’d confirm with rsbuild inspect; something outside Rsbuild core is likely reading it, but Rsbuild itself documents output.module as the supported CJS/ESM knob: https://rsbuild.rs/config/output/module

[dhouck]

Iʼm still a bit confused about the lib thing, but I canʼt reproduce it now so maybe Iʼd just changed multiple options at once yesterday when I thought it was doing anything. On the off chance I run into it again before just removing that line from my config and forgetting about it, Iʼll file a bug report, because it really shouldnʼt be having an effect without Rslib.

And thanks for the code links; I looked but couldnʼt find them. That explains the IIFE difference; the Rsbuild default of setting output.module to true also sets the Rspack output.module, which disables IIFE (even though this isnʼt mentioned in the Rspack output.iife section). I can turn it off manually as you suggest, but I was confused about the different behavior and wondering if there was anything else I missed.