Upgrade to v6
Upgrade to KatanaKit v6
Section titled “Upgrade to KatanaKit v6”This guide migrates you from 5.x to 6.x. It has two breaking changes and a handful of deprecations that will become breaking in v7.
Removed in 6.11.2. The Telegram and WhatsApp adapters (
katanakit-js/adapters/telegram,katanakit-js/adapters/whatsapp) were removed in 6.11.2, together withdefineTelegramConfiganddefineWhatsAppConfig. That release was a patch, so a^6.11.2range pulls the removal in without a major bump — pin~6.11.1if you still need those subpaths. The rename tables below still describe what happened in v6, where those entry points did exist. See ADR-0006.
npm install katanakit-js@^6Breaking changes
Section titled “Breaking changes”useInit* replaced by define*Config (6.0.0)
Section titled “useInit* replaced by define*Config (6.0.0)”Every configuration entry point now has a define*Config counterpart that
registers the config and returns it in one call, so a whole file can be
export default define*Config({ … }) with no second step.
| 5.x | 6.x |
|---|---|
useInit(apis) / useInitApis(config) |
defineApiConfig |
useInitNotion(config) |
defineNotionConfig |
useInitWordPress(config) |
defineWordPressConfig |
useInitInsforge(config) |
defineInsforgeConfig |
useInitTelegram(config) |
defineTelegramConfig |
useInitWhatsApp(config) |
defineWhatsAppConfig |
Before (5.x) — register, then use the API by name:
import { useInitApis, useFetch } from "katanakit-js";
useInitApis({ pokeapi: { baseUri: "https://pokeapi.co/api/v2", endpoints: { users: "/users" }, }, debug: true,});After (6.x) — one declaration that registers and hands back a facade. The
props and flags land on this.config, and your own methods sit next to them:
import { defineApiConfig, useFetch } from "katanakit-js";
export default defineApiConfig({ pokeapi: { baseUri: "https://pokeapi.co/api/v2", endpoints: { users: "/users" }, }, debug: true, getPokemon: async function () { return useFetch("pokeapi", "byId", { params: { id: 25 } }); },});import api from "./katanakit.config.js";
const pokemon = await api.getPokemon();console.log(api.config.debug);Three rules that are easy to get wrong:
- Declare methods with
function, never arrows — arrow functions have nothis, and TypeScript reports it. defineTelegramConfiganddefineWhatsAppConfigare config-only: they accept their config type and nothing else, so a method there is a compile error.- For
defineApiConfig, only entries shaped like{ baseUri, endpoints }reach the registry. Boolean flags stay onconfigfor your methods to read, and anything else throws a typed error instead of registering garbage.
::: warning The useInit* aliases are deprecated, not removed
They still compile, so 5.x code runs unchanged on 6.x — but they are no longer
the documented API, and their “not configured” errors now point at the
define*Config replacement. Plan to move before v7, when the aliases go away.
The same @deprecated marks are on IFetchApiManager, INotionService and
IWordPressService.
:::
useInitDummyJson() removed (6.0.2)
Section titled “useInitDummyJson() removed (6.0.2)”Unlike the other entry points this one is gone, not deprecated. It took no
arguments and did exactly one thing: call useInitApis with a fixed preset.
Before (6.0.1 and earlier):
import { useInitDummyJson } from "katanakit-js/adapters/bun";
useInitDummyJson();After (6.0.2+):
import { defineApiConfig } from "katanakit-js";import { dummyJsonApiConfig, useDummyJsonProducts,} from "katanakit-js/adapters/bun";
defineApiConfig(dummyJsonApiConfig);dummyJsonApiConfig is exported as plain data, so importing the module runs
nothing until you register it. The migration is a rename: same behaviour, one
call, no hidden preset.
Deprecated in v6 — removed in v7
Section titled “Deprecated in v6 — removed in v7”Move these now and the next major is a package bump.
-
FetchOptions.urlOptions(6.0.1) — passparams,queryandignoreDefaultQueryat the top level, next tomethod/headers/body, matchinguseGet,useRequestand Nuxt’suseFetch:// olduseFetch("api", "byId", { urlOptions: { params: { id: 25 } } });// new — flat keys win key by key over a legacy nestuseFetch("api", "byId", { params: { id: 25 } }); -
useBuildApiUrl(6.0.1) — it was a behaviourally identical wrapper with no real usage. UseuseBuildUrl.
Added in v6
Section titled “Added in v6”- Config-file entry points —
defineApiConfig,defineNotionConfig,defineWordPressConfig,defineInsforgeConfig,defineTelegramConfig,defineWhatsAppConfig, plus the sharedConfigFacade/ConfigData/ConfigMethodtypes. useFetchflat URL options —params,queryandignoreDefaultQueryat the top level; the old nest still works as a compatibility shim.useFetchtransform— maps the parsed body toTbefore it is returned. It runs on success only, and a failing transform comes back as aTransform ErrorSafe Result instead of escapinguseFetch, so the never-throws contract holds.
Migration checklist
Section titled “Migration checklist”- Install
katanakit-js@^6. - Replace
useInit*calls withdefine*Config(table above) and import the config file where the side effect is supposed to happen. - Replace
useInitDummyJson()withdefineApiConfig(dummyJsonApiConfig). - Flatten any
urlOptions: { … }nests and swapuseBuildApiUrlforuseBuildUrl. - Run your test suite — nothing else in v6 changes behaviour.
Full detail per release: changelog.