Creating a Modern TypeScript/JavaScript Library With tsup | by jsmanifest | Nov, 2022

tsup is powered by esbuild

photo by rodrigo santos From Pexels

It’s a great time to be a developer, especially for JavaScript. The JavaScript ecosystem is both vast and exciting, and open source projects are constantly evolving with new tools one after another. we have libraries like feedback To develop complex user interfaces, frameworks such as next To build server-side rendered applications, Gatsby For static web apps, lerna With all turborepo For monorepose.t.c.

Submitting pull requests for bug fixes or proposing new ideas is usually a developer’s first intuition for contributing to exciting open source projects. We also have the option of starting our own open source project. If you are planning to start your own open source JavaScript library, then this article is for you.

For those who are curious but haven’t heard tsupWe’re moving to this modern, robust JavaScript tool (a newer bundling tool that is an alternative to the popular solidify) to build a JavaScript library yourself, and then submit it to the npm registry for others npm install in their own projects. Our code examples will focus on typescriptWhich is a superset of JavaScript.

powered by tsup esbuild, an extremely fast modern JavaScript bundler with extreme speed without the need for a cache. It is a tool that bundles your TypeScript library with no configuration required. It can bundle any file that is supported internally by the node.js platform, including .js, .json, .mjs, .ts, .tsxwith experimental support for .css At the time of this writing.

To begin, start a terminal and create a new directory (you can name it whatever you want). then enter the directory in terminal cd in the terminal. For this article, we’ll call it my-typescript-library,

we will need one package.json so go ahead and enter npm init -y in terminal:

it will immediately make a package.json file with default settings.

call directly srcand then create a new file inside that directory called index.ts, This file is the entry point to our library.

since we will use tsupWe need to install it as a dev dependency:

since the file we created src/index.ts will be the entry point of our library, we need to instruct tsup To consume these files and output them somewhere (we will set the output directory to ./dist,

go ahead and revise package.json add more build simultaneously start lines under scripts Property:

now when we run npm run buildtsup compiler will consume src/index.ts and automatically compile the files ./dist Directory:

tsup -build -terminal -output

by default, tsup sends the output file to ./distBut we can configure it with a config file which we will see shortly.

If we look at the generated file ./dist/index.js, we will see empty content. This is because we haven’t written any code for our library yet.

Let’s go ahead and enter some basic code so we can analyze the output in more detail:


run npm run build again and note how tsup Have migrated our code to ES5:


Let’s test our library by creating a file called client.js with the following code:

enter file and run node client.js in the terminal. You should see:


Great! Our library is working flawlessly.

we can do much more tsup and it all starts with a config file tsup Will automatically consume while running. make tsup.config.ts file with the following content:

With this configuration file, we can instruct tsup Compiler to do different things.

For example, we can instruct it to generate a TypeScript declaration file by setting dts To true,

For this setting, we need to install typescript In our project, otherwise we would receive an error:

when we run npm run build Again this will generate an additional file which is a declaration type file:


We can also generate source maps to help generate a more accurate stack trace in debugging:


Client code will now be able to get the most out of our library by receiving TypeScript hints in their IDE (such as VS Code):


One problem that library authors face is being able to support different formats for clients to consume. Some common formats are:

, format | Details | , , , , IIFE | Quick Function Expressions (for browsers) | , CJS | CommonJS | , ESM | ECMAScript Module |

we can easily configure tsup To generate all three of these formats with a simple one-line update to the configuration:


In our client.js file, we can consume our library without any problems so far. However, in order for users to import the file that conforms to the format being used by their project, we need to package.json To point to the correct file(s) for some formats:


how to read more about exports works, you can click here To go to the official nodejs documentation as it is beyond the scope of this article.

We’ve now covered the recommended requirements for building a minimal modern JavaScript/TypeScript library! The only thing we need to do next is to publish our package to the npm registry so that users can npm install our package.

To do this, add a publishConfig key to package.json and set it inside access To "public" as shown below:

log in npm publish in terminal, and you should see something similar to this (options my-typescript-library with your package name):


this much only!

To access the source code from this post, click here

I hope you found this useful, and look out for more in the future!

Leave a Reply