---
title: "good-typescript-library-template"
description: "Production ready minimal template for developing and releasing TypeScript libraries, including automated GitHub repository setup. And believe me, it is good."
canonical_url: "https://neg4n.dev/projects/good-typescript-library-template"
md_url: "https://neg4n.dev/projects/good-typescript-library-template.md"
---

# good-typescript-library-template

## Resources

- [GitHub](https://github.com/neg4n/good-typescript-library-template)

## README

Good TypeScript Library TemplateAn opinionated production-ready TypeScript library template with automated builds, testing, and releases.And believe me. It is good.[!IMPORTANT]
Looking for a monorepo template tailored for multi-library development, with nx and same features as this template?Check out good-typescript-libraries-template!Features📦 Dual Package Support - Outputs CommonJS and ESM builds🛡️ Type Safety - Extremely strict TypeScript configuration🔐 Always up-to-date deps - Renovate bot for CVE-aware automatic dependency updates✅ 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 secretsTech StackTypeScript - Strict configuration for type safetyRollup - Builds both CommonJS and ESM formatsBiome - Fast linting and formattingVitest - Testing with coverage reportsHusky - Pre-commit hooks for code qualitySemantic Release - Automated versioning and releasespnpm - Fast package management with CorepackGitHub Actions - CI/CD pipelineSetup1. Use the templateRun this in your terminal GitHub CLI requiredgh repo create my-typescript-library --clone --template neg4n/good-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 documentation2. Minimal SetupRun the initialization script to automatically configure your repository:# One-command setup
./init.shThis 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 instructions3. Required SecretsThe 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=  --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"ScriptsCommandDescriptionpnpm devWatch mode buildpnpm buildProduction buildpnpm build:checkBuild + package validationpnpm testRun testspnpm test:watchWatch mode testingpnpm test:coverageGenerate coverage reportpnpm lintCheck linting and formattingpnpm lint:fixFix linting and formatting issuespnpm typecheckTypeScript type checkingpnpm releaseCreate release (CI only)Renovaterenovate.json5 already turns onboarding off, so Renovate will start opening update PRs as soon as the GitHub App is installed. Enable it like this:Visit https://github.com/apps/renovate and click Install.Choose your personal account or organization, then pick All repos or Only select repos (include this one).Approve the requested permissions to finish installation. Renovate will run shortly after and open PRs based on renovate.json5.Notes:Want to stop it? Uninstall the app or set "enabled": false in renovate.json5.Need custom rules (schedules, groups, automerge)? Extend renovate.json5 - no extra onboarding PR is required.FAQHow do I modify the merging methods?good-typescript-library-template sets rebase-only at both repository and main branch levels. Here's how to modify this:Current SetupRepository: Rebase merging only (squash/merge disabled)Main branch ruleset: Requires rebase mergingTo Change Merge MethodsFor repository-wide changes:Settings > General > Pull Requests - toggle merge methodsFor branch-specific changes:Settings > Rules - edit the main branch ruleset's "Require merge type"Precedence RulesRepository settings define what's availableRulesets add restrictions on topMost restrictive wins - if repository disallows a method but ruleset requires it, merging is blockedCommon ModificationsAllow all methods: Enable squash/merge in repo settings + remove "Require merge type" from rulesetSquash-only: Change repo settings to squash-only OR keep current repo settings + change ruleset to require squashDifferent rules per branch: Create additional rulesets for other branch patterns[!TIP]
Since good-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  /package.json

[...]Why This HappensThis 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.SolutionRun the following command locally:pnpm installThis will:Update your pnpm-lock.yaml to match your package.jsonInstall any new dependenciesResolve version conflictsThen 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 issuesSimplified releases - Semantic release works better with linear commitsClear changelog - Each commit represents a complete changeBetter debugging - git bisect works more effectivelyConsistent workflow - Forces proper PR review processContributingSee CONTRIBUTING.md for development workflow, commit conventions, and contribution guidelines.LicenseThe MIT License