Skip to content

Upgrade to 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.

Terminal window
npm install katanakit-js@^6

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:

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.

::: 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. :::

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.

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.

  • 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.
  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.