Tsup: A Guide to the TypeScript Bundler

Tsup is a zero-configuration bundler that allows users to bundle their TypeScript libraries. This allows you to put all your imported code along with code written in your library into a single file. It’s currently being used in the following open-source projects: 

1. shadcn/ui CLI library
2. novel.sh package

Let’s take a look at how to implement tsup to bundle your TypeScript library.

What Is Tsup?

Tsup bundles your library. Now, you might be wondering what does “bundle” mean here? When you write your TypeScript library, you would import packages from npm in your code. Bundling means putting all these imported code, along with the code written in your library in a single file. 

Tsup configuration is really simple and straightforward. It supports code-splitting and source map generation.

More on Software EngineeringPascal Case vs. Camel Case Explained

How to Implement Tsup

To implement tsup, follow the steps below:

1. Installation

Run the below command at the root of your project
 

```
npm i tsup -D
# Or Yarn
yarn add tsup --dev
# Or pnpm
pnpm add tsup -D
```

2. Usage

To use Tsup in your project, you would need to update package.json and create tsup.config.ts.

3. Update package.json

To bundle your library, you would need to update your build command in package.json as shown belo

```
{
  "name": "your-library",
  "version": "1.0.0",
  "description": "Your library description.",
  …
  "scripts": {
    "build": "tsup",   
   …
}
```

4. Create tsup.config.js

Once you have updated package.json, you need to create a file named tsup.config.ts at the root of your project and update that file with the below code.

```
import { defineConfig } from 'tsup'

export default defineConfig({
  entry: ['src/index.ts'],
  splitting: false,
  sourcemap: true,
  clean: true,
})
```

• entry tells tsup where to start bundling. 
• Splitting is set to false here so there is no code splitting. 
• Sourcemap is set to true, this creates a .map file for the bundled files. These sourcemap files can be used to debug and fix minified JavaScript code without the need to determine where the error occurred in the original code. 
• clean flag in Tsup is used to clean the output directory before each build. This can be useful to ensure that the output is only the latest. 

Now when you run npm run build, your library gets bundled. 

If you’re still having trouble, I suggest reviewing how tsup is being used in shadcn-ui/ui. It can help you in many ways, including:

1. You get to learn how Tsup “can” be implemented. Implementation you find in OSS helps you navigate the docs. Reading the entirety of the docs is good, but it can be overwhelming.
2. You get to see it in action. Tsup is found in two places when you search for it in the shadcn-ui/ui CLI source code:

Tsup package.json

"scripts": {  
 "dev": "tsup - watch",  
 "build": "tsup",

tsup.config.ts

import { defineConfig } from "tsup"  

export default defineConfig({  
 clean: true,  
 dts: true,  
 entry: \["src/index.ts"\],  
 format: \["esm"\],  
 sourcemap: true,  
 minify: true,  
 target: "esnext",  
 outDir: "dist",  
})

At this point, I would just go read the docs to learn what these options are and how the scripts are configured. This is my way of setting a direction to read and learn the most from the docs. This is how I did it too in my open source CLI related package to bundle my TypeScript library, to begin with.

Tsup TypeScript and JavaScript JSON Schema Store

Tsup also provides a schema.json via the CDN. You can use this schema to provide auto-completions, validations and descriptions in JSON file configurations, such as tsup.config.json and package.json. To see these capabilities in action, you need to update your .vscode/settings.json with the below code.

```
{
  "json.schemas": [
    {
      "url": "https://cdn.jsdelivr.net/npm/tsup/schema.json",
      "fileMatch": ["package.json", "tsup.config.json"]
    }
  ]
}
```

More on Software EngineeringHow to Revert a File in Git

Advantages of Tsup

1. It has over 1 million downloads per week on NPM registry
2. tsup repository is well reviewed on GitHub with active maintenance.
3. It’s well documented.
4. It’s used in shadcn-ui/ui CLI package making it accessible to learn.
5. Tsup is powered by esbuild.

Frequently Asked Questions