Upgrade to v2
Upgrade to KatanaKit v2
Section titled “Upgrade to KatanaKit v2”This guide migrates you from 1.x to 2.x. Most of v2 was a rework of the codebase rather than of the public API, but two things affect you directly: the package name and the removal of side effects on import.
npm install katanakit-js@^2The package was renamed
Section titled “The package was renamed”v2 was developed and published as katanakit-dev. The npm package was
renamed to katanakit-js on 2026-09-04 — katanakit-dev is unpublished and
can no longer be installed. Every import changes accordingly:
// before (1.x)import { useFetch } from "katanakit-dev";import { useBunCreate } from "katanakit-dev/adapters/bun";
// after (2.x)import { useFetch } from "katanakit-js";import { useBunCreate } from "katanakit-js/adapters/bun";Update package.json and every import in one pass:
grep -rl 'katanakit-dev' src/ | xargs sed -i 's/katanakit-dev/katanakit-js/g'Side effects on import are gone (2.0.0)
Section titled “Side effects on import are gone (2.0.0)”Importing the library no longer does anything by itself. The top-level fetch
to dummyjson.com, the console calls, the storage writes and the timers that
1.x ran at module scope were removed. You opt in by calling a function.
If you relied on an import “warming up” a service, call its entry point explicitly instead.
Changed structure (2.0.0)
Section titled “Changed structure (2.0.0)”The project was reorganized into hexagonal architecture:
types/, core/services/, infrastructure/, adapters/, config/ and
prisma/. The public API is exposed through barrel files — src/index.ts and
a index.ts per layer — so your imports keep working; only deep paths
into src/ change, and those were never supported.
Fixed in v2
Section titled “Fixed in v2”- Singleton guards (
TimingService,ViewportService) and theFIND_ENTRYscope bug inAstroService. - Express server:
listenhonours the configured port/host, the user router is mounted, and handlerreq/resargument order is correct. - Logger call sites now pass the level as the first argument to
useLog. - TypeScript compile errors in broken imports.
Removed in v2
Section titled “Removed in v2”Duplicate type definitions (unified in src/types/), dead code, empty files
and the abandoned signals draft. Demos moved to examples/ and the wiki/
documentation tree was dropped.
Migration checklist
Section titled “Migration checklist”- Rename
katanakit-devtokatanakit-jsinpackage.jsonand all imports. - Check for anything that depended on import-time side effects and make those calls explicit.
- Run your test suite.
Full detail per release: changelog.