tslib-template

A modern, minimal, runtime-agnostic TypeScript library template

This is my personal template, crafted to kickstart TypeScript libraries with best-in-class tooling, continuos integration, and a focus on developer experience.

Features

• ⚡ tsdown — Super fast TypeScript build system with modern output
• 🧹 Biome — Next-gen and fast code formatter & linter
• 🔬 Vitest — Next-gen unit testing framework
• 📦 pnpm — Performant, disk-efficient package manager
• 🛡️ CI — Automated build and tests for Node.js & Bun
• 🚀 Auto publishing - Safe and automated releases with npm provenance support

Getting Started

1. Use This Template

• Click "Use this template"
• or clone manually:

git clone https://github.com/arobsn/tslib-template.git your-lib-name
cd your-lib-name
pnpm install

2. Update Project Info

• Edit package.json (name, description, author, etc.)
• Update LICENSE and README.md as needed

3. Start Coding

• Source files go in src/.
• Export your main API from src/index.ts.

4. Publish Your Library

1. Make sure that publishConfig & repository are set accordingly in package.json
2. Ensure NPM_TOKEN is set in repository secrets (see instruction on how to create an Automation npm token and how to set it as a repository secret)
3. Create a release on GitHub to trigger publish workflow

Scripts

| Script | Description | | -------------------- | ------------------------------ | | pnpm build | Build the library using tsdown | | pnpm build:watch | Watch & rebuild on changes | | pnpm lint:check | Lint code with Biome | | pnpm lint:fix | Auto-fix lint issues | | pnpm format:check | Check formatting with Biome | | pnpm format:fix | Format code with Biome | | pnpm test | Run unit tests with Vitest | | pnpm test:watch | Watch mode for tests | | pnpm test:coverage | Test with coverage report |

Continuous Integration

| Script | Description | | ---------------------------------------------------------------- | ------------------------------------------------------------------------- | | .github/workflows/ci.yml | Test all pushes/PRs on Node.js & Bun | | .github/workflows/publish.yml | Publish the package to the NPM every time a new Github release is created |

NPM Provenance

This template supports npm provenance for secure and transparent releases. Provenance allows users to verify that the published npm package was built from the source in your repository.

Requirements

For provenance to work properly, you must:

• Use a public GitHub repository (provenance only works for public repos)
• Ensure your package.json contains:
  • "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" } (✅ already set in this template)
  • A correct "repository" field (GitHub HTTPS or git+https URL matching your repository name)
  • A "license" field (e.g., "MIT") (✅ already set, but you must choose yours)
• Publish using GitHub Actions with OIDC and the --provenance flag (✅ already set)
• Use npm CLI v9.6.0+ for publishing (✅ already set)
• Set your NPM_TOKEN secret in the repo settings

Disabling Provenance

If you do not want provenance statements when publishing to npm (e.g., if you encounter issues or your workflow doesn't require it), you can disable it:

1. Edit .github/workflows/publish.yml
2. Remove the --provenance flag from both npm publish commands.

- run: npm publish --provenance
+ run: npm publish

- run: npm publish --tag beta --provenance
+ run: npm publish --tag beta

3. Save and commit the changes.

Without the --provenance flag, npm will not attempt to attach provenance statements to your package.

See more:

• [npm] Provenance Docs
• [github] GitHub Actions for npm provenance
• [npm] Creating and viewing access tokens
• [github] Using secrets in GitHub Actions