TypeScript Library Template

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

Test

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. Quick Start

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

2. 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