d-fischer / tsukuru Goto Github PK

Build a TypeScript package that's compatible with both CommonJS and ES Modules

License: MIT License

JavaScript 4.17% Shell 0.72% TypeScript 95.11%

tsukuru's Introduction

🔨 tsukuru

This package enables you to build a TypeScript package that's compatible with both CommonJS and ES Modules - without writing any duplicate code!

Consumer environment	compiled by `tsc`	compiled by `tsukuru`
node, CommonJS	❌ `const foo = require('foo').default`	✔ `const foo = require('foo');`
node, native ES Modules (.mjs)	❌ `import foo from 'foo'; foo.default();` (incompatible with its own generated definitions)	✔ `import foo from 'foo'; foo();`
typescript	✔ `import foo from 'foo'; foo();`	✔ `import foo from 'foo'; foo();`

This is a heavy work in progress, use at your own risk!

Installing

yarn add --dev tsukuru
# or
npm install --save-dev tsukuru

Configuration of package.json

Put this (or something similar) in your package.json:

{
    "main": "lib",
    "types": "lib",
    "exports": {
        ".": {
            "require": "./lib/index.js",
            "import": "./es/index.mjs"
        }
    },
    "scripts": {
        "build": "tsukuru",
        "rebuild": "tsukuru --clean"
    }
}

Assuming that your outDir is lib. The output directory of the ES Modules is currently hardcoded to be es.

CLI options

-c, --config-file

Specifies the path to your TypeScript configuration file (tsconfig.json). If none is given, tsukuru will traverse your project directory and its ancestors until it finds a file named tsconfig.json.

-R, --no-cjs-root-export

Disables the use pf require('pkg') as a shortcut to the default export. Consumers must use require('pkg').default instead. This may considerably decrease your package's total size.

--clean

Removes the output directories before building.

How does this work?

This package runs the TypeScript compiler twice internally.

The first build will create a CommonJS version. It utilizes custom TypeScript transformers to augment and rearrange the module.exports statements so that you can use require('pkg') instead of require('pkg').default to access the default export of your package.

The second build will create an ES Module version. It will overwrite some of your tsconfig.json configuration to ensure compatibility with ESM modules. It also utilizes another custom transformer to resolve the import paths because node doesn't do that by default. Lastly, it renames the .js output files to .mjs in order to enable module importing without weird package.json hacks.

FAQ

There's a problem using an import from `<other package>` in the ESM build when using node!

Sadly, the world of npm packages isn't quite ready yet for ESM. Please make sure that the package supports importing ESM before filing an issue here.

If it doesn't, maybe make a change by sending pull requests to your favorite libraries? ✨

What does the name mean?

It's Japanese for the verb "build" or "construct". It's usually written like this: 作る

tsukuru's People

Contributors

Stargazers

Watchers

Forkers

mekwall stimulcross

tsukuru's Issues

index.mjs file was generated with mixed slashes

hi @d-fischer,

the index.mjs file was generated with mixed slashes.
lines in the index.ts file which looks like
export { ZArray } from './utils/zarray';
were generated in index.mjs file as
export { ZArray } from "./utils\zarray.mjs";
I didn't dig into your source code but I guess it's because the path construction was made on a windows machine caused it. This can cause problems on linux systems, so I wrote a script to fix
and now it's running as a stage after the build.
If you want I can contribute to fix this.

rimraf is missing when building the package

hi @d-fischer,

rimraf was missing when I tried to build my package, so I had to npm install it.
the rimraf package is listed under devDependencies section, I think it's better to place it under dependencies or peerDependencies.

some points I encountered

Hi @d-fischer,

I used the library to publish a typescript package I'm writing, and it works great.
in fact, it would have saved me a couple of days if I knew about it earlier.

I understand that the library is new, and while working with it I encountered a few points
that I want to share here.

rimraf was missing when I tried to build my package, so I had to npm install it.
the rimraf package is listed under devDependencies section, I think it's better to place it under dependencies or peerDependencies.
the index.mjs file was generated with mixed slashes.
lines in the index.ts file which looks like
export { ZArray } from './utils/zarray';
were generated in index.mjs file as
export { ZArray } from "./utils\\zarray.mjs";
I didn't dig into your source code but I guess it's because the path construction was made on a windows machine caused it. This can cause problems on linux systems, so I wrote a script to fix
and now it's running as a stage after the build.
If you want I can contribute to fix this.
The readme file shows how to set the package.json file, however I wasn't sure about the
settings in the tsconfig.json file. I played with the definitions there and now it's seems to work, but
I'm not sure for certain that all settings are correct.
I attached below my tsconfig.json file, can you kindly verify the settings are correct?

Other then that I want to thank you about this library, the idea behind it is just fine and it's
better then the rest of the solutions I found so far.

{
"compilerOptions": {
"target": "es2015",
"module": "CommonJS",
"declaration": true,
"outDir": "./lib",
"strict": true,
"noImplicitAny": false
},
"lib": [
"es2015",
"dom",
"es5"
],
"include": ["src"],
"exclude": ["node_modules", "**/tests/*"]
}

ES Modules Building Failed

I'm trying to use tsukuru in my library which uses the same structure as twurple. The process fails on ES modules building stage. The situation is the same with twurple itself. After yarn build / yarn rebuild I get the following output:

PS C:\Dev\twurple> yarn rebuild
yarn run v1.22.19
$ tsukuru --clean
√ Cleaning CJS outputs (81ms)
√ Checking & building changed projects for CJS (91694ms)
√ Bootstrapping ESM tsconfig files (24ms)
√ Cleaning ES module outputs (20ms)
\ Building ES modules... error TS18003: No inputs were found in config file 'C:/Dev/twurple/node_modules/.cache/tsukuru/esm-bootstrap/common/tsconfig.json'. Specified 'include' paths were '["C:\\Dev\\twurple\\packages\\common\\**\\*"]' and 'exclude' paths were '["../../../../../packages/common/node_modules","../../../../../packages/common/lib","../../../../../packages/common/es"]'.
√ Building ES modules (1ms)
Done in 92.34s.

After building I have lib folders, but es folders are missing.

tsukuru: 0.8.0-pre.5 (0.7.4 does not build at all with complete success console output)
Node: 16.16.0
OS: Windows 10

Am I doing something wrong? 🤔

Support for TypeScript 5

Any plans on adding support for TypeScript 5?