@knighted/duel
Tool for building a Node.js dual package with TypeScript. Supports CommonJS and ES module projects.
type
..mts
and .cts
file extensions.package.json
and tsconfig.json
files.First, install this package to create the duel
executable inside your node_modules/.bin
directory.
user@comp ~ $ npm i @knighted/duel --save-dev
Then, given a package.json
that defines "type": "module"
and a tsconfig.json
file that looks something like the following:
{
"compilerOptions": {
"declaration": true,
"module": "NodeNext",
"outDir": "dist"
},
"include": ["src"]
}
You can create an ES module build for the project defined by the above configuration, and also a dual CJS build by defining the following npm run script in your package.json
:
"scripts": {
"build": "duel"
}
And then running it:
user@comp ~ $ npm run build
If everything worked, you should have an ESM build inside of dist
and a CJS build inside of dist/cjs
. Now you can update your exports
to match the build output.
It should work similarly for a CJS-first project. Except, your package.json file would use "type": "commonjs"
and the dual build directory is in dist/esm
.
If you prefer to have both builds in directories inside of your defined outDir
, you can use the --dirs
option.
"scripts": {
"build": "duel --dirs"
}
Assuming an outDir
of dist
, running the above will create dist/esm
and dist/cjs
directories.
TypeScript will throw compiler errors when using import.meta
globals while targeting a CommonJS dual build, but will not throw compiler errors when the inverse is true, i.e. using CommonJS globals (__filename
, __dirname
, etc.) while targeting an ES module dual build. There is an open issue regarding this unexpected behavior. You can use the --modules
option to have the differences between ES modules and CommonJS transformed by duel
prior to running compilation with tsc
so that there are no compilation or runtime errors.
Note, there is a slight performance penalty since your project needs to be copied first to run the transforms before compiling with tsc
.
"scripts": {
"build": "duel --modules"
}
This feature is still a work in progress regarding transforming exports
when targeting an ES module build (relies on @knighted/module
).
The available options are limited, because you should define most of them inside your project's tsconfig.json
file.
--project, -p
The path to the project's configuration file. Defaults to tsconfig.json
.--pkg-dir, -k
The directory to start looking for a package.json file. Defaults to the cwd.--modules, -m
Transform module globals for dual build target. Defaults to false.--dirs, -d
Outputs both builds to directories inside of outDir
. Defaults to false
.You can run duel --help
to get the same info. Below is the output of that:
Usage: duel [options]
Options:
--project, -p [path] Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.
--pkg-dir, -k [path] The directory to start looking for a package.json file. Defaults to cwd.
--modules, -m Transform module globals for dual build target. Defaults to false.
--dirs, -d Output both builds to directories inside of outDir. [esm, cjs].
--help, -h Print this message.
These are definitely edge cases, and would only really come up if your project mixes file extensions. For example, if you have .ts
files combined with .mts
, and/or .cts
. For most projects, things should just work as expected.
This is going to work best if your CJS-first project uses file extensions in relative specifiers. This is completely acceptable in CJS projects, and required in ESM projects. This package makes no attempt to rewrite bare specifiers, or remap any relative specifiers to a directory index.
Unfortunately, TypeScript doesn't really build dual packages very well. One instance of unexpected behavior is when the compiler throws errors for ES module globals when running a dual CJS build, but not for the inverse case, despite both causing runtime errors in Node.js. See the open issue. You can circumvent this with duel
by using the --modules
option if your project uses module globals such as import.meta
properties or __dirname
, __filename
, etc. in a CommonJS project.
If doing an import type
across module systems, i.e. from .mts
into .cts
, or vice versa, you might encounter the compilation error error TS1452: 'resolution-mode' assertions are only supported when `moduleResolution` is `node16` or `nodenext`.
. This is a known issue and TypeScript currently suggests installing the nightly build, i.e. npm i typescript@next
.
If running duel
with your project's package.json file open in your editor, you may temporarily see the content replaced. This is because duel
dynamically creates a new package.json using the type
necessary for the dual build. Your original package.json will be restored after the build completes.
As far as I can tell, duel
is one (if not the only) way to get a correct dual package build using tsc
without requiring multiple tsconfig.json
files or extra configuration. The Microsoft backed TypeScript team keep talking about dual build support, but they continue to refuse to rewrite specifiers.
Fortunately, Node.js has added --experimental-require-module
so that you can require()
ES modules if they don't use top level await, which sets the stage for possibly no longer requiring dual builds.