Scaffold TypeScript npm packages using this template to bootstrap your next library.

Built with Vite for fast builds and development with HMR, plus vite-plugin-dts for bundled type definitions.

Use this template via GitHub's "Use this template" button or:

gh repo create <name> --template="https://github.com/jasonsturges/vite-typescript-npm-package"

Important: Check package name availability before you start to avoid renaming later:

npm search <term>

The following tasks are available:

• npm run build - Build production distributable (JS + types)
• npm run dev - Watch mode to detect changes (rebuilds dist/ and types)
• npm start - Vite dev server with HMR for local development

This template builds multiple distribution formats:

• ESM (dist/index.mjs) - Modern ES modules for import
• CommonJS (dist/index.cjs) - Node.js compatibility for require()
• IIFE (dist/index.iife.js) - Browser global variable for CDN usage
• Types (dist/index.d.ts) - Bundled TypeScript declaration file

Export everything from the top-level index.ts for inclusion in the build.

For example, if you have a utils/ folder with an arrayUtils.ts file:

// src/utils/arrayUtils.ts
export const distinct = <T>(array: T[] = []) => [...new Set(array)];

Include that export in the top-level index.ts:

// src/index.ts
export { distinct } from "./utils/arrayUtils"

Multiple strategies for development are available.

Vite's dev server provides real-time HMR updates:

npm start

This starts Vite's dev server hosting index.html for local development with hot module replacement. This file is not included in the production build. Only exports from src/index.ts are bundled into the library.

The template includes a React app example, which can be replaced with Vue, Solid.js, Svelte, or any framework.

For UI projects, consider adding Storybook to isolate component development.

For development with npm link or when working with other projects:

npm run dev

Vite detects changes and compiles all modules to dist/, including bundled type declarations.

To test your library in other projects before publishing:

1. From this library: Start watch mode and link the package

   npm run dev
   npm link

2. From your app: Link to this library

   npm link "mylib"

A symlink is created in your app's node_modules/. Changes to your library are automatically rebuilt and reflected in your app.

Create a tarball to test the exact package that will be published:

npm pack

This creates a [name].tgz tarball. Install it in your test app:

npm install /path/to/[name].tgz

Once development completes, unlink both projects:

• From your app:

  npm unlink "mylib"

• From your library:

  npm unlink

If you forget to unlink, manually clean up:

For yarn:

rm -rf ~/.config/yarn/link/mylib

For npm:

sudo npm rm --global "mylib"
npm ls --global --depth 0  # confirm removal

Or simply reinstall dependencies in your app to clear symlinks:

rm -rf node_modules && npm install

Update your package.json to the next version number and tag a release.

Add publishConfig to your package.json:

"publishConfig": {
  "registry": "https://registry.npmjs.org/",
  "access": "public"
}

For private GitHub packages:

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

Before publishing, ensure a clean build:

rm -rf dist
npm run build

Verify your package name is available:

npm search <term>

Once ready to publish:

npm login
npm publish --access public

For continuous integration with GitHub Actions, create .github/workflows/publish.yml

name: Publish Package to npmjs
on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      - run: npm ci
      - run: npm run build
      - run: npm publish

name: Publish Package to GitHub Packages
on:
  release:
    types: [created]

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

Obtain an "Automation" CI/CD access token from npm to bypass 2FA:

1. Click your profile image � Access Tokens
2. Generate a new Automation token

Add secrets to your repository:

1. Repository � Settings � Security � Secrets and variables � Actions
2. Add NPM_TOKEN secret

For more information:

• Using secrets in GitHub Actions
• Publish to npmjs and GPR with npm