ts-lib-base

A GitHub template for starting new ESM-only TypeScript libraries.

Using this template

1. Click "Use this template" on GitHub to create a new repository from this one.

2. Clone your new repository and run:

   pnpm install && pnpm setup:template

   You will be asked for a package name, a description, and an author. The script rewrites package.json, README.md, and LICENSE accordingly, fills in repository, homepage, and bugs from your origin remote, then removes itself.

   setup:template runs a TypeScript file directly, so it needs Node 22.18 or newer (Node 24 is what CI uses). The published package itself only requires Node 22.

Scripts

| Script | Purpose | | --- | --- | | typecheck | Type-check the project with tsc --noEmit. | | test | Run the test suite once with Vitest. | | test:watch | Run the test suite in watch mode. | | test:coverage | Run the test suite with coverage reporting. | | bench | Run the benchmark suite with Vitest bench. | | build | Build the package with tsdown. | | check:package | Check the built package with publint and attw. | | lint | Check formatting and lint rules with Biome. | | lint:fix | Apply Biome's automatic fixes. | | verify | Run typecheck, lint, test, build, and check:package in sequence. | | prepare | Install git hooks via Husky. | | changeset | Record a changeset for the next release. | | version-packages | Apply pending changesets and bump the version. | | release | Build and publish the package via Changesets. |

Releasing

Releases are automated with Changesets, and the release workflow publishes via npm's trusted publishing (OIDC) rather than a long-lived token, so there is no NPM_TOKEN secret to manage.

Trusted publishing can only be configured for a package that already exists on npm, so the very first release needs a one-time manual bootstrap:

1. Run pnpm setup:template, then npm login and npm publish --access public --no-provenance (or --access restricted for a scoped private package) locally, once, to reserve the name. --no-provenance is required here: publishConfig.provenance: true otherwise forces provenance generation, which only works from a supported CI provider (GitHub Actions, GitLab CI, ...) and errors out locally with Automatic provenance generation not supported for provider: null. This one bootstrap release just won't carry a provenance attestation; every release after it publishes from CI and gets one automatically.
2. On the package's npm page, open Settings > Trusted Publisher, choose GitHub Actions, and fill in your GitHub org/user, the repository name, the workflow filename release.yml, and "npm publish" as the allowed action. Leave "Environment name" blank unless the workflow is gated behind a GitHub environment.
3. From then on, every release goes through CI: merge a changeset to main, the release workflow opens a "Version Packages" pull request, and merging that pull request publishes the package to npm.

Under Settings > Actions > General, "Allow GitHub Actions to create and approve pull requests" must be enabled, or the version pull request cannot be opened.

changeset publish runs pnpm publish under the hood, which in turn shells out to npm publish - trusted publishing is npm CLI's feature, not pnpm's, so the workflow installs the latest npm before publishing to guarantee the

=11.5.1 it requires. Provenance is generated automatically by trusted publishing for a public repository publishing a public package; the publishConfig.provenance: true field in package.json is kept for documentation but isn't what triggers it anymore. Provenance still requires repository.url in package.json to match the repository the release is published from, so double-check it if the remote ever changes.

Placeholder library

src/greet.ts, test/greet.test.ts, and bench/greet.bench.ts are placeholders that exist to keep the test, build, and bench scripts runnable out of the box. Replace them with your own code as your first commit rather than just deleting them: pnpm test fails once no file matches test/**/*.test.ts, so swap in your own test instead of leaving the directory empty.