Building and Publishing TypeScript NPM Packages: A Step-by-Step Guide

📆 · ⏳ 4 min read · · 👀

Introduction

Creating and publishing your own Npm packages can be a rewarding experience, allowing you to share your code and contribute to the open-source community. TypeScript, with its static typing and modern language features, is an excellent choice for building high-quality libraries and utilities.

In this tutorial, we will walk through the process of building and publishing an Npm package using TypeScript. We’ll cover the essential steps from project setup to testing, building, and finally releasing the package on NPM.

Prerequisites

Before we dive into the tutorial, make sure you have Node.js and NPM installed on your machine. Additionally, a basic understanding of TypeScript and package management with NPM will be helpful.

Setting Up the Project

To begin, let’s set up a new TypeScript project by using a template which will have all the initial boilerplate required like ts-npm-template ↗️ as a starting point.

Clone the template repository or use it as a template directly from Github to initialize your own project.

Note: This template is created by me and follows an opiniated structure for creating NPM packages. I am constantly learning and improving it to adhere to best practices.

What the template includes

  • TypeScript configuration with strict type checking and ES module output.
  • Biome.js for linting and formatting.
  • Vitest for testing your package.
  • Tsup for bundling your code.
  • Semantic Release for versioning and publishing your package.
  • Typedoc for automatically generating documentation of your package.
  • Github Actions workflow for automating the testing and release process.
  • PNPM package manager for faster and more efficient dependency management.

So in all the template is feature rich and will help you get started with creating NPM packages with TypeScript. All you need to focus on is writing your library code. Ofcourse, you can always customize the template to suit your needs.

Let’s understand the steps to set up the project using the template.

Steps to set up the project

After you have created a new repository using the template, follow these steps to set up the project

Creating the Package

Start by defining the package details in the package.json file, including the package name, version, author, and other relevant information.

This will be the metadata for your package and will be used when publishing it to NPM.

Writing your library code

Write your library code in TypeScript, taking advantage of its static typing and other language features. Organize your code into modules and export the necessary functions, classes, or objects to be consumed by other developers.

The place to start with is the src/index.ts file. You can follow the example structure which is provided in the template or follow your own structure.

Testing with vitest

Ensuring the quality of your code is crucial the template uses a testing framework like vitest ↗️ to write unit tests for your package.

Write test cases to cover different scenarios and validate the behavior of your library functions. This will help you catch bugs early and ensure that your code works as expected.

Building with tsup

To make your code ready for distribution, you need to bundle it into a single file. The template uses tsup ↗️, a zero-config bundler specifically designed for TypeScript projects.

It will handle the transpilation and bundling process for you, producing a browser-ready JavaScript file. The template is already configured to use tsup with the necessary settings, however you can customize it as per your needs.

The settings enabled are as follows:

  • Output ES module, Common JS and IIFE format.
  • Minify the output.
  • Generate source maps for debugging.
  • Tree shaking

Versioning and Publishing with Semantic Release

Semantic Release automates the release and versioning process based on the commit history of your project. The template automatically configures semantic release to automatically determine the next version number and publish the package to NPM. This ensures a consistent and reliable release workflow.

This is possible by using Github Actions workflow to automate the testing and releasing the package whenever code is pushed to the main branch. Semantic release will automatically determine what should be the next version bump based on the code commits.

Ensure you follow the syntax of conventional commits ↗️ when writing commit messages. This will help semantic release to determine the next version bump.

If you are a vscode user, the template also add recommendation extensions which will help you write conventional commits as per the presets defined in the package.json file.

Conclusion

We learned how to create packages using TypeScript and automatically publish them NPM using the template (ts-npm-template ↗️). This will help you get started with creating your own NPM packages with TypeScript.

We went through what the template provides out of the box and how you can customize it to suit your needs. The template is feature rich and will help you focus on writing your library code rather than setting up the project.

If you are someone who is looking to create NPM packages, I would recommend you to use the template as a starting point and if you want to contribute to the template, feel free to raise a PR to improve it.

You may also like

  • # projects# engineering

    I built my own in-house Newsletter system

    Discover how I transformed the need for a newsletter system, sparked by Revue's shutdown, into a fulfilling side project. Dive into the my journey of conceptualizing, breaking down, and building a custom newsletter system that seamlessly integrates with my website's content workflows.

  • # engineering# nodejs

    Running SSL on Localhost

    In today's digital landscape, security is paramount. Secure Sockets Layer (SSL) is a crucial technology that encrypts data transmitted between a user's browser and a website, ensuring confidentiality and integrity. But did you know you can also enable SSL for your localhost development environment? This guide will walk you through the process step by step.

  • # nodejs# raspberrypi

    Get Up and Running with the Latest Version of Node.js on Raspberry Pi

    Do you want to run the latest version of Node.js on your Raspberry Pi? This guide will take you through the process of installing the latest version of Node.js on armhf architecture using binary packages.