Home

Awesome

rollup-plugin-cjs-es

.github/workflows/build.yml codecov install size

Convert CommonJS module into ES module. Powered by cjs-es.

Installation

npm install -D rollup-plugin-cjs-es

Features

Usage

import cjs from "rollup-plugin-cjs-es";

export default {
  input: ["entry.js"],
  output: {
    dir: "dist",
    format: "cjs"
  },
  plugins: [
    cjs({
      nested: true
    })
  ]
};

require is reassigned

If require, exports, or module are dynamically assigned, the transformer can't find them and it will emit a warning e.g.

(function(r) {
  r("foo");
})(require);

const r = require;
r("foo");

These patterns are common in module loaders like UMD. I suggest using other plugins to unwrap the module back to the normal CJS pattern.

Lazy load and code splitting

To lazy load an ES module, we can use the import() function:

foo.js

export const foo = () => {
  return import("./bar");
};

bar.js

export const bar = "bar";

After rolluped into CommonJS format, the dist folder would contain two entries:

foo.js

'use strict';

const foo = () => {
  return Promise.resolve(require("./bar.js"));
};

exports.foo = foo;

bar.js

'use strict';

const bar = "bar";

exports.bar = bar;

So that bar.js is not loaded until require("foo").foo() is called.

With this plugin, you can use the same feature using CommonJS syntax, by writing the require statement inside a promise:

module.exports = {
  foo: () => {
    return Promise.resolve(require("./bar.js"));
  }
};

The plugin would transform it into a dynamic import().

Named import/export v.s. default import/export

Missing exports: foo is not exported by foo.js

In the following example, you would get a warning:

entry.js

const foo = require("./foo");
foo.foo();

foo.js

const myObject = {
  foo: () => console.log("foo");
};
// assign the entire object so that cjs-es won't convert the object pattern into named exports.
module.exports = myObject;

(!) Missing exports
https://github.com/rollup/rollup/wiki/Troubleshooting#name-is-not-exported-by-mo
dule
entry.js
foo is not exported by foo.js
1: import * as foo from "./foo";
2: foo.foo();
       ^

That is because cjs-es tends to import named exports by default.

To solve this problem, the plugin generates a .cjsescache file when a build is finished (whether it succeeded or not), which record the export type of each imported module. In the next build, it will read the cache file and determine the export type according to the cache.

You can also use exportType option to tell the plugin that foo.js exports default member manually:

{
  plugins: [
    cjsEs({
      exportType: {
        // the path would be resolved with the current directory.
        "foo.js": "default"
      }
    })
  ]
}

Dynamic import() problem with default export

In the following example, you would get an error under ES enviroment:

entry.js

Promise.resolve(require("./foo"))
  .then(foo => foo());

foo.js

module.exports = function() {
  console.log("foo");
};

After rolluped into ES format and renamed them into .mjs:

entry.mjs

import("./foo.mjs")
  .then(foo => foo());

foo.mjs

function foo() {
  console.log("foo");
}

export default foo;

(node:9996) ExperimentalWarning: The ESM module loader is experimental.
(node:9996) UnhandledPromiseRejectionWarning: TypeError: foo is not a function
    at then.foo (file:///D:/Dev/node-test/dist/entry.mjs:2:16)
    at <anonymous>

To correctly call the default member, entry.js has to be modified:

Promise.resolve(require("./foo"))
  .then(foo => foo.default());

However, this would break other enviroments like CommonJS:

(node:9432) UnhandledPromiseRejectionWarning: TypeError: foo.default is not a fu
nction
    at Promise.resolve.then.foo (D:\Dev\node-test\dist\entry.js:4:27)
    at <anonymous>
    at process._tickCallback (internal/process/next_tick.js:118:7)
    at Function.Module.runMain (module.js:705:11)
    at startup (bootstrap_node.js:193:16)
    at bootstrap_node.js:660:3

Avoid default export if you want to use dynamic import() + CommonJS in the same time.

Comparing to rollup-plugin-commonjs

rollup-plugin-commonjs uses a smart method to determine whether to use named or default import. It creates a proxy loader when a module is imported:

source

const foo = require("foo");
foo.bar();

transformed

import "foo";
import foo from "commonjs-proxy:foo";
foo.bar();

With this technic, it can first look into the "foo" module to check its export type, then generate the proxy module which maps named exports into a default export. However, if the required module "foo" uses named exports, it has to be converted into a single object:

commonjs-proxy:foo

import * as _ from "foo";
export default _;

As a result, all named exports are included in the bundle even that only bar is used.

The same problem applies to cjs-es as well if you force a module to use default export:

entry.js

const foo = require("./foo");
foo.foo();

foo.js

module.exports = {
  foo: () => console.log("foo"),
  bar: () => console.log("bar")
};

bundled

const _export_foo_ = () => console.log("foo");

_export_foo_();

bundled with exportType: "default"

var foo = {
  foo: () => console.log("foo"),
  bar: () => console.log("bar")
};

foo.foo();

Note that this won't be true after rollup supports tree-shaking for object literal. See https://github.com/rollup/rollup/issues/2201

API

This module exports a single function.

cjsEsFactory

cjsEsFactory(options?:Object) => rollupPlugin

options has following optional properties:

Changelog