A starter for writing and publishing a TypeScript library: strict types, a small public API, ESM and CommonJS output, tests with coverage thresholds, release automation with changesets and package checks.
Part of Essential: starter templates with the tooling, structure, docs and AI-agent guide already in place.
- Strict TypeScript (
noUncheckedIndexedAccess,verbatimModuleSyntax) - tsdown builds ESM (
.mjs), CommonJS (.cjs) and type declarations from one entry - Single public entry point:
src/index.ts; a test pins the export list so API changes are deliberate - Result type (
ok,err,attempt) as an example module with tests - vitest with coverage thresholds, oxlint (type-aware, warnings denied) and oxfmt
- publint and arethetypeswrong verify the package works for Node ESM, Node CJS and bundlers
- Changesets for versioning and changelogs, Husky, GitHub Actions CI
- Docs and AGENTS.md for people and coding agents
Click Use this template on GitHub (or run gh repo create my-project --template essential-registry/typescript-essential), then:
pnpm install
pnpm test
pnpm buildRename the package in package.json, replace src/lib/result.ts with your code and export your public API from src/index.ts.
| Command | What it does |
|---|---|
pnpm dev |
Rebuild on change (tsdown --watch) |
pnpm build |
Build dist/ (ESM, CJS, types) |
pnpm typecheck |
tsc --noEmit |
pnpm lint / pnpm lint:fix |
oxlint, type-aware, warnings denied / auto-fix |
pnpm format / pnpm format:check |
oxfmt write / check |
pnpm test / pnpm coverage |
vitest / with coverage thresholds |
pnpm check:package |
publint and arethetypeswrong on the packed package |
pnpm changeset |
Record a release note |
pnpm run ci |
The non-mutating gate CI runs |
pnpm build:prepare |
Fix lint and format, then run the full gate |
src/
index.ts the public API (semver surface), re-exports only
lib/ implementation modules, each with a sibling *.test.ts
tests/ public-API and integration tests
docs/ architecture, publishing, tooling
.changeset/ release notes
tsdown.config.ts build config
src/index.ts is the only entry point and everything it exports is covered by semver. Implementation lives in src/lib, one module per concern with tests beside it. package.json exports maps import and require to the ESM and CJS builds with matching types, and pnpm check:package proves the mapping works.
Full details: docs/architecture.md.
docs/architecture.md: layers, folders and how the pieces fitdocs/publishing.md: releasing the package with changesetsdocs/tooling.md: every command, tool and the quality gate
pnpm run ci runs typecheck, lint, format check, tests, the build and the package checks. GitHub Actions runs exactly that on every push and pull request, and the Husky pre-commit hook runs the fast checks. Releases: add a changeset per change, then follow docs/publishing.md.
AGENTS.md is the guide coding agents follow: commands, layout, conventions and a "never" list (CLAUDE.md points to it). .claude/ adds safe permissions, a formatter hook, a read-only reviewer agent and task skills. Commits always use your own git identity; the guide tells agents not to add attribution lines and not to commit unless asked.
- Change
name,descriptionandrepositoryinpackage.json. - Replace the example module and update
tests/public-api.test.ts. - Adjust coverage thresholds in
vitest.config.tsto your standard. - Set up npm publishing (trusted publishing with provenance is recommended).
MIT. See LICENSE.