Before you start reading, please get familiar with the between CommonJS (CJS) and ECMAScript Modules (ESM). This article will describe how we can build a TypeScript project for both CJS and ESM targets using a pure TypeScript compiler and native npm features. difference . You can find an example project in my GitHub repo Motivation This post is inspired by my beloved rxjs library — just take a look at how many tsconfig.json files they have ! Let’s try to build some minimal examples that will showcase how you can build your TypeScript (TS) project to both EcmaScript Modules and CommonJS targets. Of course, you can do the same nowadays using some fancy bundlers like Rollup, Webpack, Vite, etc — but I do it only for educational purposes (…and fun). there — I bet there would be some new ones released by the time I finish writing my article Imagine a situation when you want to have your library used by multiple projects in your organization — one is an old Node.js project built for CJS target, and another one is a modern and fancy browser application. Most likely, if you try to import the ESM bundle into the Node.js project, it won’t compile. From words to business Let’s create our package first. Run in your terminal: npm init -y 
npm i -D typescript @types/node npm-run-all 
npx tsc --init In generated file (this would be our base file for different build targets) change to point to directory: tsconfig.json outDir build "outDir": "./build" Now we can create our configuration for TS based on the build output format: for ESM builds will generate output to folder tsconfig.esm.json esm {
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./build/esm",
    "module": "esnext"
  }
} for CJS builds will generate output to folder tsconfig.cjs.json cjs {
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./build/cjs",
    "module": "commonjs"
  }
} for typings will generate output to folder tsconfig.types.json types {
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./build/types",
    "declaration": true,
    "emitDeclarationOnly": true
  }
} Let’s define our scripts to generate the build output. Go to file and add these commands: package.json "compile": "tsc -b ./tsconfig.cjs.json ./tsconfig.esm.json ./tsconfig.types.json",
"build:clean": "rm -rf ./build", 
"build": "npm-run-all build:clean compile && && node ./scripts/prepare-package-json" will simply clean up the target build directory before every new build. compile will use TypeScript compiler ( ) to build our source ( stands for build) based on the configuration we pass down it. build:clean tsc -b Theoretically, we can have more build formats to share (e.g., ESM5 to support older browsers). And finally, we will generate a special file for our ESM build using our custom script (more about this below). Now we can publish our package using . package.json prepare-package-json npm publish But what if the point of publishing a library if there is no library? Let’s build something. What will our library do? Let’s create file under folder: lib.ts src export async function run() {
  let type = "";
  const workerPath = "./worker.js";
  // require and __dirname are not supported in ESM
  // see: https://nodejs.org/api/esm.html#differences-between-es-modules-and-commonjs
  if (typeof require !== "undefined" && typeof __dirname !== "undefined") {
    type = "CJS";
    const { Worker, isMainThread } = require("worker_threads");
    if (isMainThread) {
      const worker = new Worker(__dirname + "/" + workerPath);
      worker.on("exit", (code: number) => {
        console.log(`Nodejs worker finished with code ${code}`);
      });
    }
  } else {
    type = "ESM";
    if (typeof Worker !== "undefined") {
      new Worker(workerPath);
    } else {
      console.log("Sorry, your runtime does not support Web Workers");
      await import(workerPath);
    }
  }
  console.log(`Completed ${type} build run.`);
} The idea of this library would be to offload some expensive computational work to the worker instance. For Node.js, we will use worker thread implementation, while for browsers, we will use WebWorker API. As a fallback, we can lazy load the script into the main thread and execute it there. For our worker code, we will use Fibonacci number calculation: const maxLimit = 1_000_000;
let n1 = BigInt(0),
  n2 = BigInt(1),
  iteration = 0;
console.log("Starting fibonacci worker");
console.time("fibonacci");
while (++iteration <= maxLimit) {
  [n2, n1] = [n1 + n2, n2];
}

console.log("Fibonacci result: ", n1);
console.timeEnd("fibonacci"); This operation should take a while, so it’s worth extracting it into a separate thread (yes, JavaScript is not really a single-threaded) instead of blocking the main thread. Let’s add some glue Now we need to tell our consumers how to import our library without telling them exactly what path they need to import from. Here comes handy npm’s feature: conditional exports "exports": {
    "./*": {
      "types": "./build/types/*.d.ts",
      "require": "./build/cjs/*.js",
      "import": "./build/esm/*.js",
      "default": "./build/esm/*.js"
    }
  } Or, for our use case, we can have them more specific (considering we output only single entry file to start working with our library): "exports": {
    ".": {
      "types": "./build/types/lib.d.ts",
      "require": "./build/cjs/lib.js",
      "import": "./build/esm/lib.js",
      "default": "./build/esm/lib.js"
    }
  } How to read this? tells npm to resolve any path going after the package name (for example, will match path), and simply tells us to resolve the root import ( ). ./\* import lib from 'my-fancy-lib/lib' /lib . import lib from 'my-fancy-lib' The key ( , , , ) defined in the hash object for this export will trigger based on the way the end package consumes this library: types requre import default (or ) will resolve to import lib from 'my-fancy-lib/lib' import lib from 'my-fancy-lib' <node\_modules>/my-fancy-lib/build/esm/lib.js (or ) will resolve to const lib = require('my-fancy-lib/lib') const lib = require('my-fancy-lib') <node\_modules>/my-fancy-lib/build/cjs/lib.js key is basically a fallback key if nothing matched the search. By the way, there are also a few other keys you can define - you can find all of them in the . default documentation Now the funny part. key be defined prior to all others, and the default key needs to go last. While I understand why order is important (a common practice for fallback mechanisms), but I am not sure why it's important to have first. types MUST default types At the end of the day, it is simply a JSON file - runtime can read it first and then decide what priority to set. You can also define conditional exports for TS typings using typesVersions: "typesVersions": {
    ">=3.1": { "*": ["ts3.1/*"] },
    ">=4.2": { "*": ["ts4.2/*"] }
  } Hacky part As I mentioned earlier, we need to execute some custom scripts at the end of the build. So why do we need it? First of all, let’s look at the script: const fs = require("fs");
const path = require("path");

const buildDir = "./build";
function createEsmModulePackageJson() {
  fs.readdir(buildDir, function (err, dirs) {
    if (err) {
      throw err;
    }
    dirs.forEach(function (dir) {
      if (dir === "esm") {
        var packageJsonFile = path.join(buildDir, dir, "/package.json");
        if (!fs.existsSync(packageJsonFile)) {
          fs.writeFile(
            packageJsonFile,
            new Uint8Array(Buffer.from('{"type": "module"}')),
            function (err) {
              if (err) {
                throw err;
              }
            }
          );
        }
      }
    });
  });
}

createEsmModulePackageJson(); So entire idea of this script is to generate separate for ESM build (under directory) with the following content: package.json build/esm {"type": "module"} This will tell the consumer build system that the underlying directory has modern EcmaScript modules. Otherwise, it will complain with: SyntaxError: Unexpected token 'export' Can we do better? Yes! npm has an implicit file extension convention to distinguish between ESM and CJS. All files with extension will be interpreted as ESM while - as CommonJS module. So instead of creating this hacky script, we can define in our root package.json and have CommonJS to require files using extension. .mjs .cjs "type": "module" .cjs But I find an existing way is more user-friendly because consumers don’t need to worry about extensions; they can simply use this library as-is: // for CommonJS 
const { run } = require("my-fancy-lib"); 
// for ESM 
import { run } from "my-fancy-lib"; Security considerations There is a risk called : dual package hazard When an application is using a package that provides both CommonJS and ES module sources, there is a risk of certain bugs if both versions of the package get loaded. This potential comes from the fact that the pkgInstance created by const pkgInstance = require('pkg') is not the same as the pkgInstance created by import pkgInstance from 'pkg' (or an alternative main path like 'pkg/module'). This is the "dual package hazard," where two versions of the same package can be loaded within the same runtime environment. While it is unlikely that an application or package would intentionally load both versions directly, it is common for an application to load one version while a dependency of the application loads the other version. This hazard can happen because Node.js supports intermixing CommonJS and ES modules, and can lead to unexpected behavior. Final words Having multiple variants of the same build which end users can consume without worrying about whether it’s compiled for their build target is always a nice user experience. In real projects, you are more likely to use UMD (Universal Module Definition) format that generates a single bundle for both worlds. However, sometimes it is useful to have fine granular builds — for example, when using for loading scripts in the browser. module/nomodule pattern Also published here

Check out my blog

Read My Stories

Too Long; Didn't Read

In your car, at home, or at work — Bosch technology shapes many areas of life.

How to Build a TypeScript Project for Both CJS and ESM Targets

Too Long; Didn't Read

Ildar Sharafeev

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

How to Build a TypeScript Project for Both CJS and ESM Targets

Too Long; Didn't Read

Ildar Sharafeev

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES