TypeScript Template

A template for a TypeScript application on the Bun runtime. Bun runs TypeScript with no build step, Biome lints and formats, and the tsconfig is strict. It starts from github-project-template, so it has the same hooks, CI gate, and documentation convention.

Stack

Tool	Owns
Bun	The runtime, install, and tests
TypeScript	The type check
Biome	Lint and format
convict	Configuration
mise	Tool versions and tasks
lefthook	Git hooks
cocogitto	Conventional Commits checks
rumdl	Markdown lint
gitleaks	Secret scan
Renovate	Updates to the pinned versions

Getting started

1. Install mise.

2. Clone the repo and install the tools, dependencies, and hooks:

   git clone git@github.com:tabmadi/ts-template.git
   cd ts-template
   mise install
   mise run setup

3. Start the server in watch mode, then call it:

   mise run dev
   curl http://localhost:3000/health

Tasks

Task	Does
mise run setup	Installs the locked dependencies and the git hooks
mise run dev	Runs the app and reloads on change
mise run start	Runs the app
mise run format	Applies every formatter
mise run lint	Runs lint:ts, lint:md, and lint:secrets
mise run test	Runs the tests
mise run check	Runs lint and test. Run it before you finish a change
mise run ci	Runs exactly what CI runs. The pre-push hook runs it too

Layout

.
├── src/
│   ├── index.ts      The HTTP server with a /health route
│   ├── config.ts     The configuration schema
│   └── __tests__/    The tests
├── docs/adr/         The decisions: foundations, doc conventions, toolchain
├── biome.json        Lint and format rules
├── tsconfig.json     Compiler settings
├── .mise.toml        Tool pins and tasks
└── .lefthook.yml     Git hooks

Configuration

Variable	Description	Default
PORT	The port the server binds	3000

Using this template

1. Create a repository from this template on GitHub.
2. Change name in package.json.
3. Replace the sample server in src/ with your own code.
4. Update the contacts in SECURITY.md and the copyright line in LICENSE.
5. Install the Renovate app on the new repository.

Decisions

The ADRs in docs/adr record every decision and the reason for it. ADR-0001 is the house style for all text.

Contributing

Follow the Code of Conduct. Commit messages follow Conventional Commits, and the commit-msg hook checks them. Run mise run check before you open a pull request.

Security

To report a vulnerability, follow SECURITY.md.

License

Apache License 2.0. See LICENSE.