Build and publish a TypeScript package to npm

Publishing a TypeScript package is easy until the package is imported by another project.

Then details matter:

• does it work with ESM?
• does it work with CommonJS?
• can TypeScript find the types?
• are internal source files accidentally public?
• does the npm tarball contain what we expect?

In this tutorial we’ll build and publish a small package called tiny-duration.

It will convert milliseconds into a readable duration:

formatDuration(90500) // "1m 30s"

Create the package

mkdir tiny-duration
cd tiny-duration
npm init -y
npm install --save-dev typescript tsup vitest

Create src/index.ts:

export type FormatDurationOptions = {
  compact?: boolean
}

export function formatDuration(
  milliseconds: number,
  options: FormatDurationOptions = {}
): string {
  if (!Number.isFinite(milliseconds) || milliseconds < 0) {
    throw new TypeError('milliseconds must be a non-negative number')
  }

  const totalSeconds = Math.floor(milliseconds / 1000)
  const minutes = Math.floor(totalSeconds / 60)
  const seconds = totalSeconds % 60

  if (options.compact) {
    return `${minutes}:${String(seconds).padStart(2, '0')}`
  }

  const parts = []

  if (minutes > 0) {
    parts.push(`${minutes}m`)
  }

  if (seconds > 0 || parts.length === 0) {
    parts.push(`${seconds}s`)
  }

  return parts.join(' ')
}

The public API is everything exported from src/index.ts. Keep that surface small and intentional.

Configure TypeScript

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "declaration": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

strict is especially important for a library. A weak type hidden inside the package becomes a weak type in every project that installs it.

Build ESM, CommonJS, and declarations

Create tsup.config.ts:

import { defineConfig } from 'tsup'

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
  sourcemap: true,
})

Add scripts to package.json:

{
  "scripts": {
    "build": "tsup",
    "test": "vitest run",
    "prepack": "npm run test && npm run build"
  }
}

Run:

npm run build

The dist directory contains:

dist/
  index.cjs
  index.d.cts
  index.d.ts
  index.js
  index.js.map

The exact declaration filenames can vary slightly with the build tool version.

Define package exports

Edit package.json:

{
  "name": "tiny-duration",
  "version": "1.0.0",
  "description": "Format a duration in milliseconds",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  },
  "files": [
    "dist"
  ],
  "sideEffects": false
}

Choose a real package name that is available on npm. Scoped packages such as @yourname/tiny-duration avoid many naming collisions.

The exports map is the public entry point.

ESM consumers receive index.js. CommonJS consumers receive index.cjs. TypeScript receives the declarations.

The files array is an allowlist for the published tarball. It prevents tests, source configuration, and local notes from being published accidentally.

Only set sideEffects: false when importing the package does not perform global work. Bundlers use this hint for tree shaking.

Add tests

Create src/index.test.ts:

import { describe, expect, test } from 'vitest'
import { formatDuration } from './index'

describe('formatDuration', () => {
  test('formats minutes and seconds', () => {
    expect(formatDuration(90_500)).toBe('1m 30s')
  })

  test('supports compact output', () => {
    expect(formatDuration(90_500, { compact: true })).toBe('1:30')
  })

  test('rejects negative values', () => {
    expect(() => formatDuration(-1)).toThrow(TypeError)
  })
})

Run:

npm test

These tests exercise source code. We must also test the package people will install.

Inspect the npm tarball

Run:

npm pack --dry-run

npm prints every file that would be published.

Look for:

• dist files
• package.json
• README.md
• LICENSE

Look for things that should not be there:

• .env
• test fixtures
• private keys
• editor files
• large source maps you did not intend to ship

Then create the actual tarball:

npm pack

Install that tarball in a temporary consumer project:

mkdir /tmp/tiny-duration-consumer
cd /tmp/tiny-duration-consumer
npm init -y
npm install /path/to/tiny-duration/tiny-duration-1.0.0.tgz

Test ESM:

import { formatDuration } from 'tiny-duration'

console.log(formatDuration(90500))

Test CommonJS:

const { formatDuration } = require('tiny-duration')

console.log(formatDuration(90500))

The tarball test catches bad export paths that source tests cannot see.

Write the README before publishing

A useful package README should answer:

1. what does this package do?
2. how do I install it?
3. what is the smallest working example?
4. what inputs and outputs does the API use?
5. which runtimes are supported?

Keep examples executable. The first code block should not depend on information explained three sections later.

Add repository and license metadata to package.json:

{
  "repository": {
    "type": "git",
    "url": "git+https://github.com/yourname/tiny-duration.git"
  },
  "license": "MIT",
  "engines": {
    "node": ">=18"
  }
}

Do not claim runtime support you have not tested.

Choose the next version

npm package versions normally follow semantic versioning:

• patch: bug fix that preserves the public API
• minor: backward-compatible feature
• major: breaking change

Commands such as this update the version and create a Git tag:

npm version patch

Do not reuse a published version. The npm registry does not let you overwrite package contents at the same name and version.

Publish manually once

Create an npm account, enable two-factor authentication, and log in:

npm login

For an unscoped public package:

npm publish

For a new scoped public package:

npm publish --access public

The prepack script runs tests and builds before the tarball is created.

After publishing, install the registry version in the temporary consumer project. Do not stop at seeing the package page.

Publish from GitHub Actions without a token

npm trusted publishing uses OpenID Connect. GitHub Actions receives short-lived permission to publish a specific package, so you do not store a long-lived npm token.

In the npm package settings, add a trusted publisher for the repository and workflow filename.

Create .github/workflows/publish.yml:

name: publish

on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22.14.0
          registry-url: https://registry.npmjs.org

      - run: npm ci
      - run: npm test
      - run: npm run build
      - run: npm publish

Trusted publishing requires a recent npm CLI and supported Node.js version. Use npm 11.5.1 or newer and Node 22.14 or newer unless the npm documentation lists newer minimums when you set it up.

For public packages published through a trusted publisher from a public repository, npm can automatically include provenance that links the package to its source and workflow.

Protect the release process:

• publish only from a protected environment
• require review for releases
• keep the workflow filename stable
• ensure repository.url exactly identifies the source repository
• build from the release commit, not an arbitrary branch

Keep the package maintainable

Every export becomes something users may depend on.

Before adding one, ask whether it needs to be public.

For every release:

1. update and test the public behavior
2. choose the semantic version
3. inspect npm pack --dry-run
4. test the packed artifact
5. publish through a protected workflow
6. install the registry result

The package is not src/index.ts. The package is the tarball, its metadata, its type declarations, and the compatibility promise attached to its version.

Related posts about node: