Building and Publishing an NPM Package with TypeScript

This guide works with a provided template that you can fork and customize to your needs.

Use existing template

When building a package, you often face repetitive tasks: setting up TypeScript, configuring the build pipeline, and managing the publishing workflow.

This template provides a pre-configured environment optimized for ES Modules, including:

TypeScript support out of the box.
Testing setup with a dedicated directory.
Build scripts to generate a clean /dist folder.
Local testing workflow using npm link.

Getting Started

Follow these steps to transform the template into your own custom library.

Note

If not done yet, create an account on npmjs.com and 2FA enabled. This is neccessary to publish packages.

Setup the Repository

First, clone or fork the template repository to your local machine and install the necessary dependencies.


npm install

Add Custom Functionality

The heart of your package lives in the /src directory. Open /src/index.ts and replace the placeholder code with your custom logic. This is the entry point that users will eventually import.

Customize Package Metadata

Open your package.json file. This file contains the “ID card” of your package. You must update these fields so your package is unique on the NPM registry:

name: Use @<your-username>/<package-name> for scoped packages.
version: Start with 1.0.0 (remember to increment this for every update).
author & description: Provide your details and a brief summary.
repository: Update the URLs for git, bugs, and your homepage.

Note

The Files Whitelist** > By default, the files field is set to ["dist"]. This ensures only your compiled code is published. If you add folders like /assets, you must add them to this array in package.json.

Test your Code

Before building, ensure your logic is working as expected. Add test cases to /tests/index.test.ts and run the test script:


npm test

Build and Local Testing

To compile your TypeScript into production-ready JavaScript, run the build command. The output will be stored in the /dist folder.


npm run build

Testing locally ensures that your library functions correctly as a standalone package before you publish it to npm.

1. Soft Local Test

To test the package locally without publishing it to the web, use npm link. This is ideal for rapid development.

In your package folder: Run npm link
In your test project: Run npm link <your-package-name>

Now you can import your package in your test project and test it as if it were published. Changes you make in your library source code are reflected immediately in the test project.

2. Hard Local Test

If the soft test worked without problems, it is highly recommended to perform a “hard” local test. This simulates the actual installation process.

In your package folder: Create a packed archive with npm pack
In your test project: Install the created archive:


# You can install it directly from the path without moving the file
npm install ../path/to/numislib-api/numislib-1.0.0.tgz

Pro-Tip: Installing the .tgz directly keeps your test project cleaner by avoiding manual file moves.

Comparison of Testing Methods

Method	Best For…	Why it’s important
Soft Test (`npm link`)	Rapid development and debugging.	Changes are reflected immediately without rebuilding or reinstalling.
Hard Test (`npm pack`)	Verifying the published structure.	Ensures the `files` array in `package.json` includes the `data` folder and internal paths resolve correctly inside `node_modules`.

Publishing to NPM

Once you have an account on npmjs.com and 2FA enabled, you are ready to go live.

It is highly recommended to perform a dry run first to see exactly which files will be uploaded:


npm publish --dry-run

If everything looks correct, login and publish:


npm login
npm publish --access public

Usage

After publishing, your package can be installed like any other:


npm i @your-username/your-package-name

Created: 03.01.2026

Last Updated: 04.01.2026