TypeScript Library Template

An opinionated production-ready TypeScript library template with automated builds, testing, and releases.

Features

• 📦 Dual Package Support - Outputs CommonJS and ESM builds
• 🛡️ Type Safety - Extremely strict TypeScript configuration
• ✅ Build Validation - Uses @arethetypeswrong/cli to check package exports
• 🧪 Automated Testing - Vitest with coverage reporting
• 🎨 Code Quality - Biome linting and formatting with pre-commit hooks
• 🚀 Automated Releases - Semantic versioning with changelog generation
• ⚙️ CI/CD Pipeline - GitHub Actions for testing and publishing
• 🔧 One-Click Setup - Automated repository configuration with init.sh script
  • 🏛️ Repository rulesets - Branch protection with linear history and PR reviews
  • 🚷 Feature cleanup - Disable wikis, projects, squash/merge commits
  • 🔄 Merge restrictions - Rebase-only workflow at repository and ruleset levels
  • 👑 Admin bypass - Repository administrators can bypass protection rules
  • 🔍 Actions verification - Ensure GitHub Actions are enabled
  • 🗝️ Secrets validation - Check and guide setup of required secrets

Tech Stack

• TypeScript - Strict configuration for type safety
• Rollup - Builds both CommonJS and ESM formats
• Biome - Fast linting and formatting
• Vitest - Testing with coverage reports
• Husky - Pre-commit hooks for code quality
• Semantic Release - Automated versioning and releases
• pnpm - Fast package management with Corepack
• GitHub Actions - CI/CD pipeline

Setup

1. Use the template

Run this in your terminal GitHub CLI required

gh repo create my-typescript-library --clone --template neg4n/typescript-library-template --private && cd my-typescript-library

[!NOTE] Replace my-typescript-library with your new library name, you can also change the visiblity of the newly created repo by passing --public instead of --private! Read more about possible options in GitHub CLI documentation

Setup via GitHub web interface

If for some reason you can't run the mentioned commands in your terminal, click the "Use this template ▾" button below (or in the top right corner of the repository page)

2. Minimal Setup

Run the initialization script to automatically configure your repository:

# One-command setup
./init.sh

This script will:

• 🔒 Create repository rulesets for branch protection (linear history, PR reviews)
• 🚫 Disable unnecessary features (wikis, projects, squash/merge commits)
• ⚙️ Configure merge settings (rebase-only workflow at repository and ruleset levels)
• 👤 Grant admin bypass permissions for repository administrators
• 🔧 Verify GitHub Actions and validate repository configuration
• 🔑 Check required secrets and provide setup instructions

3. Required Secrets

The script will guide you to set up these secrets if missing:

NPM_TOKEN (for publishing):

# Generate NPM token with OTP for enhanced security
pnpm token create --otp=<YOUR_OTP> --registry=https://registry.npmjs.org/

# Set the token as repository secret
gh secret set NPM_TOKEN --body "your-npm-token-here"

ACTIONS_BRANCH_PROTECTION_BYPASS (for automated releases):

# Create Personal Access Token with 'repo' permissions
# Visit: https://github.com/settings/personal-access-tokens/new

# Set the PAT as repository secret
gh secret set ACTIONS_BRANCH_PROTECTION_BYPASS --body "your-pat-token-here"

Scripts

| Command | Description | |---------|-------------| | pnpm dev | Watch mode build | | pnpm build | Production build | | pnpm build:check | Build + package validation | | pnpm test | Run tests | | pnpm test:watch | Watch mode testing | | pnpm test:coverage | Generate coverage report | | pnpm lint | Check linting and formatting | | pnpm lint:fix | Fix linting and formatting issues | | pnpm typecheck | TypeScript type checking | | pnpm release | Create release (CI only) |

FAQ

How do I modify the merging methods?

typescript-library-template sets rebase-only at both repository and main branch levels. Here's how to modify this:

Current Setup

• Repository: Rebase merging only (squash/merge disabled)
• Main branch ruleset: Requires rebase merging

To Change Merge Methods

For repository-wide changes:

• Settings > General > Pull Requests - toggle merge methods

For branch-specific changes:

• Settings > Rules - edit the main branch ruleset's "Require merge type"

Precedence Rules

1. Repository settings define what's available
2. Rulesets add restrictions on top
3. Most restrictive wins - if repository disallows a method but ruleset requires it, merging is blocked

Common Modifications

• Allow all methods: Enable squash/merge in repo settings + remove "Require merge type" from ruleset
• Squash-only: Change repo settings to squash-only OR keep current repo settings + change ruleset to require squash
• Different rules per branch: Create additional rulesets for other branch patterns

[!TIP] Since typescript-library-template is rebase-only, you must enable other methods in repository settings before rulesets can use them.

How to solve pnpm lockfile error on my CI/CD?

If you're seeing this error in your CI/CD (GitHub Actions) pipeline:

[...]

ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with <ROOT>/package.json

[...]

Why This Happens

This template uses --frozen-lockfile flag to ensure consistent installations in CI/CD. The error occurs when your package.json has been modified but the pnpm-lock.yaml hasn't been updated to match.

Solution

Run the following command locally:

pnpm install

This will:

1. Update your pnpm-lock.yaml to match your package.json
2. Install any new dependencies
3. Resolve version conflicts

Then commit the updated lockfile:

git add pnpm-lock.yaml
git commit -m "chore: update pnpm lockfile"

[!TIP] This is expected behavior and ensures your CI/CD uses the exact same dependency versions as your local environment.

Why Linear History?

Linear history provides several benefits for library releases:

• Clean commit history - Easy to track changes and debug issues
• Simplified releases - Semantic release works better with linear commits
• Clear changelog - Each commit represents a complete change
• Better debugging - git bisect works more effectively
• Consistent workflow - Forces proper PR review process

Contributing

See CONTRIBUTING.md for development workflow, commit conventions, and contribution guidelines.

License

The MIT License