Development
pnpm install # `prepare` compiles the packagepnpm check-types # tsc over sources and testspnpm test # vitestpnpm format # prettier --write .pnpm pack # what would actually shippnpm install runs prepare, which compiles into dist/. A broken build therefore
fails at install time rather than at publish time, which is also why CI’s first step is
enough to catch it.
The repository
Section titled “The repository”src/├── index.ts # re-exports /http and /runtime├── http/ # the type provider, controllers, routers, plugins, response types├── runtime/ # Pino↔Effect logging, memoizedConfig, the two small helpers├── openapi/ # swagger + Scalar wiring├── sse/ # the SSE handler factory└── sql/ # Drizzle over @effect/sql: repositories, filters, paginationdocs/ # the Starlight site — a separate project, its own lockfiletsconfig.main.json # the shared config, also shipped to consumersEvery directory under src/ with an index.ts is a published entry point, declared in
package.json’s exports. Architecture explains
what belongs in each and why they are separate.
Conventions
Section titled “Conventions”Entry points are the API. A symbol not re-exported from its directory’s index.ts
is internal, whatever its visibility in TypeScript. Adding to the public surface means
touching three places: the implementation, the index.ts, and — if it is a new entry
point — the exports map plus the tables in README.md and
Install.
Peer dependencies stay peers. Nothing that could end up duplicated in a consumer’s
process may become a dependency: effect and fastify most of all, since two copies of
either break Context.Tag identity and Fastify’s plugin symbols respectively. The
/sql peers are pinned to exact versions rather than ranges, and bumping them is a
release. The reasoning for both is on the
Design decisions page.
Imports carry the .ts extension. rewriteRelativeImportExtensions in
tsconfig.main.json rewrites them on the way out, and it is what lets consumers run the
shipped src/ directly under Node’s type stripping.
No non-erasable syntax. erasableSyntaxOnly is on, so enums, namespaces and
parameter properties will not compile — deliberately, so nothing keel ships needs a
transform to run.
Comments explain the reason, not the mechanism. The ones already in the source are
the model: paginate.ts documenting why the subquery is taken before limit,
typeProvider.ts documenting why local $defs are inlined. If a line only makes sense
with context that is not in the diff, that context belongs next to it.
Vitest, with test files colocated next to what they test (src/**/*.test.ts) and
excluded from the build.
Three kinds live in the suite, and it is worth knowing which one a change needs:
- Unit tests over pure helpers —
parsing.test.ts,operators.test.ts,filter.test.ts. - Integration tests through a real Fastify instance and
inject—keel.test.tsbuilds a runtime, defines routes, and asserts on statuses, bodies and what reached the logger. Anything touching the request path belongs here, because the compilers and the error handler only exist at that level. - Type-level tests with
expectTypeOf, and files whose job is to fail compilation if an inference regresses —sql/integration.types.test.tstype-checks the SQL helpers against real Drizzle types without connecting to anything.
That last category matters more than usual here: most of keel’s guarantees are types, so
a change to routeTypes.ts or controller.ts that keeps every runtime test green can
still remove a check entirely. pnpm check-types runs tsc over sources and tests
for that reason.
Three workflows, all on pull requests:
- CI —
check-types,testandpack --dry-runon Node 22 and 24, the two versions the consuming services run on, plus aprettier --checkjob. - Docs — builds the Starlight site, which also validates every internal link, and
deploys to GitHub Pages on
main. - Release — manual only, and it owns the whole sequence: bump, publish through npm’s trusted publisher, then push the commit and tag.
pnpm pack --dry-run is not ceremony: it catches a missing dist/ or a dropped
tsconfig.main.json before the release workflow does.
The documentation site
Section titled “The documentation site”docs/ is a separate project with its own lockfile, so Astro’s dependency tree never
enters the published package’s.
pnpm docs:install # docs/ has its own lockfilepnpm docs:dev # Starlight dev serverpnpm docs:build # static build, and internal link validationPages are Markdown under docs/src/content/docs/, with title and description in the
frontmatter. The sidebar is explicit in docs/astro.config.mjs — a new page needs an
entry there, or it exists at its URL and appears in no navigation.
Internal links are absolute and include the base path (/keel/controllers/), because
the site is served from a project page. starlight-links-validator fails the build on a
link — or an anchor — that does not land, so a renamed heading breaks CI rather than
shipping a dead cross-reference. That check is the reason cross-linking between pages is
safe to do liberally.
context7.json at the repository root points Context7 at docs/src/content/docs and
carries a short list of rules about how keel is meant to be used. New material is picked
up automatically; the rules list is worth revisiting when a convention changes.
Making a change
Section titled “Making a change”- Write it, with the tests — a type-level one if the change is type-level.
pnpm check-types && pnpm test && pnpm format.- Update the docs in the same commit. A behaviour change that is not in
docs/is not finished: the site is the manual, and the README only links to it. - If the public surface changed, check
index.ts,package.jsonexports, and the entry-point tables in bothREADME.mdand Install.