{"id":35514347,"url":"https://github.com/neg4n/good-typescript-library-template","last_synced_at":"2026-01-03T22:03:55.102Z","repository":{"id":300620147,"uuid":"1006570976","full_name":"neg4n/good-typescript-library-template","owner":"neg4n","description":"Production ready minimal template for developing and releasing TypeScript libraries, including automated GitHub repository setup. And believe me, it is good.","archived":false,"fork":false,"pushed_at":"2025-11-23T23:01:05.000Z","size":80,"stargazers_count":26,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-24T01:08:06.952Z","etag":null,"topics":["biomejs","github","github-actions","husky-hooks","javascript-template","pnpm","project-template","rollup","template","typescript","typescript-library","typescript-template"],"latest_commit_sha":null,"homepage":"https://neg4n.dev/explore/good-typescript-library-template/overview","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neg4n.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-22T15:03:51.000Z","updated_at":"2025-11-23T23:02:31.000Z","dependencies_parsed_at":"2025-06-22T19:32:41.288Z","dependency_job_id":null,"html_url":"https://github.com/neg4n/good-typescript-library-template","commit_stats":null,"previous_names":["neg4n/typescript-library-template","neg4n/good-typescript-library-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/neg4n/good-typescript-library-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neg4n%2Fgood-typescript-library-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neg4n%2Fgood-typescript-library-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neg4n%2Fgood-typescript-library-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neg4n%2Fgood-typescript-library-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neg4n","download_url":"https://codeload.github.com/neg4n/good-typescript-library-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neg4n%2Fgood-typescript-library-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28194899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-03T02:00:06.471Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["biomejs","github","github-actions","husky-hooks","javascript-template","pnpm","project-template","rollup","template","typescript","typescript-library","typescript-template"],"created_at":"2026-01-03T22:03:20.127Z","updated_at":"2026-01-03T22:03:55.094Z","avatar_url":"https://github.com/neg4n.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Good TypeScript Library Template\n\nAn opinionated production-ready TypeScript library template with automated builds, testing, and releases.\n\nAnd believe me. **It is good.**\n\n\u003e [!IMPORTANT]\n\u003e Looking for a monorepo template tailored for multi-library development, with **nx** and same features as this template?  \n\u003e [Check out `good-typescript-libraries-template`!](https://github.com/neg4n/good-typescript-libraries-template)\n\n\u003cimg width=\"380\" src=\"https://github.com/user-attachments/assets/e3ecf54c-13c4-4baa-a253-d2861d4bf4e9\" /\u003e\n\n## Features\n\n- 📦 **Dual Package Support** - Outputs CommonJS and ESM builds\n- 🛡️ **Type Safety** - Extremely strict TypeScript configuration\n- 🔐 **Always up-to-date deps** - [Renovate](https://github.com/renovatebot/renovate) bot for CVE-aware automatic dependency updates\n- ✅ **Build Validation** - Uses `@arethetypeswrong/cli` to check package exports\n- 🧪 **Automated Testing** - Vitest with coverage reporting\n- 🎨 **Code Quality** - Biome linting and formatting with pre-commit hooks\n- 🚀 **Automated Releases** - Semantic versioning with changelog generation\n- ⚙️ **CI/CD Pipeline** - GitHub Actions for testing and publishing\n- 🔧 **One-Click Setup** - Automated repository configuration with `init.sh` script\n    - 🏛️ **Repository rulesets** - Branch protection with linear history and PR reviews\n    - 🚷 **Feature cleanup** - Disable wikis, projects, squash/merge commits\n    - 🔄 **Merge restrictions** - Rebase-only workflow at repository and ruleset levels\n    - 👑 **Admin bypass** - Repository administrators can bypass protection rules\n    - 🔍 **Actions verification** - Ensure GitHub Actions are enabled\n    - 🗝️ **Secrets validation** - Check and guide setup of required secrets\n\n## Tech Stack\n\n- **TypeScript** - Strict configuration for type safety\n- **Rollup** - Builds both CommonJS and ESM formats\n- **Biome** - Fast linting and formatting\n- **Vitest** - Testing with coverage reports\n- **Husky** - Pre-commit hooks for code quality\n- **Semantic Release** - Automated versioning and releases\n- **pnpm** - Fast package management with Corepack\n- **GitHub Actions** - CI/CD pipeline\n\n## Setup\n\n### 1. Use the template\n\nRun this in your terminal _[GitHub CLI](https://cli.github.com) required_\n\n```bash\ngh repo create my-typescript-library --clone --template neg4n/good-typescript-library-template --private \u0026\u0026 cd my-typescript-library\n```\n\n\u003e [!NOTE]\n\u003e 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](https://cli.github.com/manual/gh_repo_create)\n\n#### Setup via GitHub web interface\n\nIf 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)\n\n\u003ca href=\"https://github.com/new?template_name=good-typescript-library-template\u0026template_owner=neg4n\"\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/784be0dd-530f-4135-b042-ab59dc9124a6\" width=\"200\" /\u003e\n\u003c/a\u003e\n\n\n### 2. Minimal Setup\n\nRun the initialization script to automatically configure your repository:\n\n```bash\n# One-command setup\n./init.sh\n```\n\nThis script will:\n- 🔒 **Create repository rulesets** for branch protection (linear history, PR reviews)\n- 🚫 **Disable unnecessary features** (wikis, projects, squash/merge commits)\n- ⚙️ **Configure merge settings** (rebase-only workflow at repository and ruleset levels)\n- 👤 **Grant admin bypass** permissions for repository administrators\n- 🔧 **Verify GitHub Actions** and validate repository configuration\n- 🔑 **Check required secrets** and provide setup instructions\n\n### 3. Required Secrets\n\nThe script will guide you to set up these secrets if missing:\n\n**NPM_TOKEN** (for publishing):\n```bash\n# Generate NPM token with OTP for enhanced security\npnpm token create --otp=\u003cYOUR_OTP\u003e --registry=https://registry.npmjs.org/\n\n# Set the token as repository secret\ngh secret set NPM_TOKEN --body \"your-npm-token-here\"\n```\n\n**ACTIONS_BRANCH_PROTECTION_BYPASS** (for automated releases):\n```bash\n# Create Personal Access Token with 'repo' permissions\n# Visit: https://github.com/settings/personal-access-tokens/new\n\n# Set the PAT as repository secret\ngh secret set ACTIONS_BRANCH_PROTECTION_BYPASS --body \"your-pat-token-here\"\n```\n\n## Scripts\n\n| Command | Description |\n|---------|-------------|\n| `pnpm dev` | Watch mode build |\n| `pnpm build` | Production build |\n| `pnpm build:check` | Build + package validation |\n| `pnpm test` | Run tests |\n| `pnpm test:watch` | Watch mode testing |\n| `pnpm test:coverage` | Generate coverage report |\n| `pnpm lint` | Check linting and formatting |\n| `pnpm lint:fix` | Fix linting and formatting issues |\n| `pnpm typecheck` | TypeScript type checking |\n| `pnpm release` | Create release (CI only) |\n\n## Renovate\n\n`renovate.json5` already turns onboarding off, so Renovate will start opening update PRs as soon as the GitHub App is installed. Enable it like this:\n\n1. Visit https://github.com/apps/renovate and click **Install**.\n2. Choose your personal account or organization, then pick **All repos** or **Only select repos** (include this one).\n3. Approve the requested permissions to finish installation. Renovate will run shortly after and open PRs based on `renovate.json5`.\n\nNotes:\n- Want to stop it? Uninstall the app or set `\"enabled\": false` in `renovate.json5`.\n- Need custom rules (schedules, groups, automerge)? Extend `renovate.json5` - no extra onboarding PR is required.\n\n## FAQ\n\n#### How do I modify the merging methods?\n\n`good-typescript-library-template` sets **rebase-only** at both repository and main branch levels. Here's how to modify this:\n\n##### **Current Setup**\n- **Repository**: Rebase merging only (squash/merge disabled)\n- **Main branch ruleset**: Requires rebase merging\n\n##### **To Change Merge Methods**\n\n**For repository-wide changes:**\n- **Settings \u003e General \u003e Pull Requests** - toggle merge methods\n\n**For branch-specific changes:**\n- **Settings \u003e Rules** - edit the main branch ruleset's \"Require merge type\"\n\n##### **Precedence Rules**\n1. Repository settings define what's **available**\n2. Rulesets add **restrictions** on top  \n3. **Most restrictive wins** - if repository disallows a method but ruleset requires it, merging is **blocked**\n\n##### **Common Modifications**\n- **Allow all methods**: Enable squash/merge in repo settings + remove \"Require merge type\" from ruleset\n- **Squash-only**: Change repo settings to squash-only OR keep current repo settings + change ruleset to require squash\n- **Different rules per branch**: Create additional rulesets for other branch patterns\n\n\u003e [!TIP]\n\u003e Since `good-typescript-library-template` is rebase-only, you must enable other methods in repository settings before rulesets can use them.\n\n#### How to solve pnpm lockfile error on my CI/CD?\n\nIf you're seeing this error in your CI/CD (GitHub Actions) pipeline:\n\n```\n[...]\n\nERR_PNPM_OUTDATED_LOCKFILE  Cannot install with \"frozen-lockfile\" because pnpm-lock.yaml is not up to date with \u003cROOT\u003e/package.json\n\n[...]\n```\n\n##### **Why This Happens**\nThis 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.\n\n##### **Solution**\nRun the following command locally:\n```bash\npnpm install\n```\n\nThis will:\n1. Update your `pnpm-lock.yaml` to match your `package.json`\n2. Install any new dependencies\n3. Resolve version conflicts\n\nThen commit the updated lockfile:\n```bash\ngit add pnpm-lock.yaml\ngit commit -m \"chore: update pnpm lockfile\"\n```\n\n\u003e [!TIP]\n\u003e This is expected behavior and ensures your CI/CD uses the exact same dependency versions as your local environment.\n\n#### Why Linear History?\n\nLinear history provides several benefits for library releases:\n\n- **Clean commit history** - Easy to track changes and debug issues\n- **Simplified releases** - Semantic release works better with linear commits\n- **Clear changelog** - Each commit represents a complete change\n- **Better debugging** - `git bisect` works more effectively\n- **Consistent workflow** - Forces proper PR review process\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, commit conventions, and contribution guidelines.\n\n## License\n\nThe MIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneg4n%2Fgood-typescript-library-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneg4n%2Fgood-typescript-library-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneg4n%2Fgood-typescript-library-template/lists"}