Options for Publishing TypeScript Libraries

This is a bit of a brain dump for myself around the different options out there and some considerations for each. I am publishing as it may be useful for others.

It is far from an exhaustive list of options and I haven’t fully evaluated each, I just put together a list with initial pros / cons then picked one.

I will try to update each as I learn more about them and try them out more.

The problem

Building libraries you want to have at least a commonJS and ESM build available so your library works in the node ecosystem without a bundler and also when using a bundler like WebPack or esbuild.

The way we reference the different builds is in our package.json

"main": "dist/index.js" // node looks at 'main'
"module": "dist/index.esm.js" // bundlers look at module

There are other issues like bundle sizes, enabling tree shaking etc. The tl;dr is make this the problem of a library rather than doing it yourself.

Other issues

When using TypeScript project references you need the main entry in your package.json for when tsc builds your package.

This means that during development you will have tsc building your library, then you package it and it needs to be built differently. Getting the package.json compatible with both local dev and the published can be difficult.

@pika/pack

Pros

• Builds into a pkg/ folder (not in place)
• Allows different package.json in the repo vs published
• Can still use changesets to update the version number before release
• Works similar to how NX packages, into another folder

Cons

• Unable to use pnpm publish as it expects the package to be built in place
• May cause other issues with the package not being built in place

microbundle

Pros

• Small bundle sizes using rollup

Cons

• package.json is source of truth, this may make it hard to get it working with TS project references

tsdx

Pros

• Well thought out
• TypeScript first

Cons

• Does way more than just package
• Some of the problems it solves I want to solve in different ways, prefer not to have multiple tools which can do the same thing as it’s confusing

tsup

Pros

• Simple
• Uses esbuild

Cons

• Doesn’t seem to work easily with ts project references when generating type definitions

Setup

To work around the generation of the TS project references issue you can just run tsc with --emitDeclarationOnly

vite

Pros

• This is probably the web bundling tool I will be using going forward
• Uses esbuild
• Supports local dev of a browser library by just adding a index.htm in the root of the package

Cons

• Similar issue to tdsx, it does a lot. Difference is I will likely be using vite for some of those features too.

Chosen setup

I ended up using tsup and tsc together. This may change to vite soon though.