JimmyVanVeen.com

Introduction

TSDX is a popular development tool that provides many useful features, including hot reloading, testing, and bundling. However, as of September 2021, the TSDX project is no longer being actively maintained, which means that users will not receive updates or bug fixes. As a result, it may be necessary to find alternatives for developing and building TypeScript libraries. In this blog post, we will cover how to replace TSDX with tsc for type definitions and tsup for code transpilation in TypeScript libraries.

Why replace TSDX?

As mentioned, TSDX is no longer being maintained. As a result, users may run into issues that will not be resolved, and new features and improvements will not be added. Additionally, some developers may prefer a simpler setup and want to use more basic tools to build their TypeScript libraries. In such cases, tsc and tsup can be a great combination to use for type definitions and code transpilation, respectively.

Getting started

This blog assumes you have a standard TSDX configuration setup, specifically as it relates to the package.json scripts, and tsconfig.json files. To get started, you need to install the necessary dependencies. In your project directory, run the following command:

npm install tsup --save-dev

This will install tsup as a development dependency in your project.

Using tsc for type definitions

TSC is the TypeScript compiler, and it can be used to generate type definitions for your library without transpiling the source code. While tsc certainly can transpile the code as well, it's still slower than tsup. If you already have a tsconfig.json file in the root directory of your project, you're all set. Just make sure that the "declaration" option is set to true and that the "outDir" option is set to your desired output directory.

For example, your tsconfig.json file could look like this:

1{
2  "compilerOptions": {
3    "declaration": true,
4    "outDir": "./dist",
5    "target": "es6",
6    "module": "commonjs",
7    "strict": true
8  },
9  "include": ["src/**/*"]
10}

This configuration will enable type definition generation, set the output directory to ./lib, and specify that the target output should be ES6 modules.

To generate the type definitions, run the following command:

npx tsc --emitDeclarationOnly --declaration

This will generate the type definitions in the ./dist directory.

Using tsup for code transpilation

tsup is a simple and fast TypeScript bundler that can be used to transpile your TypeScript code; it has the benefit of being significantly faster than tsc, hence the choice to use it. To use tsup and tsc together, update the build script in your package.json file, as well as a "tsup" configuration

1{
2  "scripts": {
3    // ...
4    "build": "tsup src && tsc --emitDeclarationOnly --declaration"
5    // ...
6  }
7  //...
8  "tsup": {
9		"clean": true,
10		"target": "es2019",
11		"format": [
12			"cjs",
13			"esm"
14	  ]
15  },
16}

Then, run the following command to build your project:

npm run build

This will transpile your TypeScript code and output in the dist directory with the correspopnding type definitions.

Finish the Job

To finish the job of replacing TSDX you will need to install Jest individually as well as eslint. I'll leave the majority of the tasks of configuring each tool left to additional blog posts, but for now let's cover the required minimum steps to remove TSDX entirely from your library.

Begin by installing eslint and jest:

npm i -D eslint@latest jest@latest

Follow the documentation for getting started with Jest, which generally can be done programmatically with this command:

npx jest --init

Likewise configure eslint with a manual setup by creating a .eslintrc.js file in the root of your project:

touch .eslintrc.js

And refer to this basic example of a configuration file:

// .eslintrc.js example
module.exports = {
  "env": {
      "browser": true,
      "es2021": true
  },
  "extends": "eslint:recommended",
  "parserOptions": {
      "ecmaVersion": "latest",
      "sourceType": "module"
  },
}

With these changes in place, you can now uninstall tsdx:

npm uninstall tsdx

...and update your scripts to the new versions:

{
  // ...
  "scripts": {
    "build": "tsup src && tsc --emitDeclarationOnly --declaration",
    "test": "jest",
    "lint": "eslint --ext js,jsx,ts,tsx src"
  },
  // ...
}

Conclusion

Replacing TSDX with tsc and tsup for type definitions and code transpilation, respectively, can be a great alternative for developing and building TypeScript libraries. It provides a simpler setup and avoids potential issues caused by a tool that is no longer maintained. With this approach, you can continue to develop your TypeScript projects with confidence.