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@^2

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)

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)

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

• Singleton guards (TimingService, ViewportService) and the FIND_ENTRY scope bug in AstroService.
• Express server: listen honours the configured port/host, the user router is mounted, and handler req/res argument 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

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

1. Rename katanakit-dev to katanakit-js in package.json and all imports.
2. Check for anything that depended on import-time side effects and make those calls explicit.
3. Run your test suite.

Full detail per release: changelog.