Skip to content
Public template

About

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.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

TypeScript Essential

CI License: MIT

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.

What you get

  • 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

Requirements

  • Node.js 22 or newer
  • pnpm 12 (corepack enable picks the right version from package.json)

Quick start

Click Use this template on GitHub (or run gh repo create my-project --template essential-registry/typescript-essential), then:

pnpm install
pnpm test
pnpm build

Rename the package in package.json, replace src/lib/result.ts with your code and export your public API from src/index.ts.

Commands

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

Project structure

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

Architecture

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.

Documentation

Quality gate and CI

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.

Working with AI agents

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.

Make it yours

  1. Change name, description and repository in package.json.
  2. Replace the example module and update tests/public-api.test.ts.
  3. Adjust coverage thresholds in vitest.config.ts to your standard.
  4. Set up npm publishing (trusted publishing with provenance is recommended).

License

MIT. See LICENSE.

About

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.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Used by

Contributors

Languages