Building & Publishing a TypeScript Library with **Microbundle** (2025)

Microbundle-Library.md

Lightweight Guide: Building & Publishing a TypeScript Library with Microbundle (2025)

Scope & audience – This walkthrough is aimed at advanced beginners: you’ve built a couple of Node projects and want a no‑fuss way to turn your reusable code into a shareable package.

Why Microbundle? One dev‑dependency gives you:

• automatic ESM + CJS + UMD bundles
• zero‑config TypeScript support
• minification via Terser
• a single microbundle CLI for build & watch (github.com)

---

1  Prerequisites

• Node 20 or newer & npm 10 (ships with Node)
• GitHub account & Personal Access Token (classic) with write:packages (for publishing to GitHub Packages)
• Git configured globally (git --version)

---

2  Project bootstrap

# create & enter a new directory
git init my-lib && cd my-lib

# generate a bare package.json
npm init -y

# install Microbundle + TypeScript
npm install -D microbundle typescript

Create src/index.ts and export something small (e.g. a function).

---

3  package.json essentials

Add (or edit) the fields below so Microbundle knows where to read and where to write:

{
  "name": "@OWNER/my-lib",        // scoped name
  "version": "0.1.0",
  "description": "Handy utilities for …",
  "repository": "https://github.com/OWNER/my-lib",
  "type": "module",               // publish ESM by default
  "source": "src/index.ts",        // Microbundle entry
  "main": "dist/my-lib.cjs",       // CommonJS build
  "module": "dist/my-lib.mjs",     // ESM build
  "exports": {
    "require": "./dist/my-lib.cjs",
    "default": "./dist/my-lib.mjs"
  },
  "types": "dist/index.d.ts",      // generated declarations
  "scripts": {
    "dev": "microbundle watch",   // rebuild on change
    "build": "microbundle",       // one‑shot build
    "test": "echo \"(add tests)\""
  }
}

Microbundle’s default output creates all three bundles and declarations in dist (github.com).

---

4  Minimal tsconfig.json

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "declaration": true,
    "declarationDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Microbundle overrides target & module internally, so setting them to ESNext keeps things aligned (github.com).

---

5  Local workflow

npm run dev   # hot‑rebuild while coding
npm test      # run your tests (once you add them)
npm run build # produce production bundles

Everything lands in dist/ and is ready to publish.

---

6  Committing to GitHub

git add .
git commit -m "chore: initial library skeleton"
git branch -M main
git remote add origin https://github.com/OWNER/my-lib.git
git push -u origin main

---

7  Choose your registry

7.1  GitHub Packages (private / internal / limited public)

1. Authenticate – create a PAT with write:packages and save it as an environment variable:

   export NODE_AUTH_TOKEN="<PAT>"

2. Configure scope mapping – add .npmrc in the project root:

   @OWNER:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

   GitHub Packages always requires authentication, even for public packages (docs.github.com).

3. (Optional) add

   "publishConfig": {
     "registry": "https://npm.pkg.github.com/"
   }

   inside package.json so CI jobs pick the right registry (docs.github.com).

7.2  Public npm (easiest for OSS consumers)

• Run npm login once.

• When publishing a scoped package, remember:

  npm publish --access public

  Without --access public, npm assumes the package is private (docs.npmjs.com).

---

8  Manual publish (one‑off release)

npm run build
# GitHub Packages
npm publish            # uses NODE_AUTH_TOKEN from .npmrc
#   – or –
# npm registry
npm publish --access public

---

9  Automating releases with GitHub Actions (recommended)

Create .github/workflows/release.yml:

name: Release & Publish
on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write   # for GitHub Packages
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://npm.pkg.github.com
          scope: '@OWNER'
      - run: npm ci
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The setup-node action writes an .npmrc on the runner and uses the repo‑scoped GITHUB_TOKEN for authentication (docs.github.com).

(Swap the registry-url for https://registry.npmjs.org and use an NPM_TOKEN secret if you prefer the public npm registry.)

---

10  Verify & consume

npm info @OWNER/my-lib     # see the metadata
npm install @OWNER/my-lib  # in another project

If installation works and dist files resolve correctly, you’re done 🎉.

---

References

• Microbundle – README & docs (github.com)
• GitHub Docs – Working with the npm registry (docs.github.com)
• GitHub Docs – Publishing Node.js packages with GitHub Actions (docs.github.com)
• npm Docs – Creating & Publishing Scoped Public Packages (docs.npmjs.com)