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 with defineTelegramConfig and defineWhatsAppConfig. That release was a patch, so a ^6.11.2 range pulls the removal in without a major bump — pin ~6.11.1 if 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@^6

Breaking changes

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:

// katanakit.config.ts
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 no this, and TypeScript reports it.
• defineTelegramConfig and defineWhatsAppConfig are 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 on config for your methods to read, and anything else throws a typed error instead of registering garbage.

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)

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

Move these now and the next major is a package bump.

• FetchOptions.urlOptions (6.0.1) — pass params, query and ignoreDefaultQuery at the top level, next to method/headers/body, matching useGet, useRequest and Nuxt's useFetch:

  // old
  useFetch("api", "byId", { urlOptions: { params: { id: 25 } } });
  // new — flat keys win key by key over a legacy nest
  useFetch("api", "byId", { params: { id: 25 } });

• useBuildApiUrl (6.0.1) — it was a behaviourally identical wrapper with no real usage. Use useBuildUrl.

Added in v6

• Config-file entry points — defineApiConfig, defineNotionConfig, defineWordPressConfig, defineInsforgeConfig, defineTelegramConfig, defineWhatsAppConfig, plus the shared ConfigFacade / ConfigData / ConfigMethod types.
• useFetch flat URL options — params, query and ignoreDefaultQuery at the top level; the old nest still works as a compatibility shim.
• useFetch transform — maps the parsed body to T before it is returned. It runs on success only, and a failing transform comes back as a Transform Error Safe Result instead of escaping useFetch, so the never-throws contract holds.

Migration checklist

1. Install katanakit-js@^6.
2. Replace useInit* calls with define*Config (table above) and import the config file where the side effect is supposed to happen.
3. Replace useInitDummyJson() with defineApiConfig(dummyJsonApiConfig).
4. Flatten any urlOptions: { … } nests and swap useBuildApiUrl for useBuildUrl.
5. Run your test suite — nothing else in v6 changes behaviour.

Full detail per release: changelog.