ADR-0003: Framework adapters only on subpath exports
ADR-0003: Framework adapters only on subpath exports
Section titled “ADR-0003: Framework adapters only on subpath exports”Status: Accepted · Date: 2026-09-20 (released in v4.0.0)
Context
Section titled “Context”Adapters import framework packages: express, vue, react, svelte,
solid-js, @angular/core, hono, better-auth, photoswipe, Nuxt’s
safe conventions, and so on. If the main barrel re-exported them, a bare
import { useLogger } from "katanakit-js" would drag peers into every
bundle, every install would demand them, and the “zero side effects on
import” guarantee would be impossible to defend.
Decision
Section titled “Decision”Anything that imports a framework stays out of src/index.ts and is published
only through the exports map as a subpath: katanakit-js/adapters/express,
/vue, /nuxt, /react, /svelte, /solid, /angular, /vanilla,
/hono, /nestjs, /astro, /better-auth, /photoswipe, /notion,
/wordpress, /insforge, /telegram, /whatsapp, /assistant, plus
/prisma and /schemas. Framework dependencies are peerDependencies with
peerDependenciesMeta.optional, never dependencies. The
examples:check script typechecks example projects against the built dist/,
so a broken or missing subpath fails the build instead of reaching npm.
Consequences
Section titled “Consequences”Better. The main bundle stays free of frameworks; consumers install only the peers they use; and the two guarantees that depend on this — zero side effects on import and a minimal install — hold without audit.
Worse. The import path differs per adapter and there is no “kitchen sink”
entry; nothing is discoverable from the main barrel, so docs must carry the
map (the entry-point list is
it). Adding an adapter means touching package.json, the docs and examples
in the same change — by design, since that is the change the reviewer must
see.
- Getting Started — import entry points
- Architecture — the exports map in context.