Skip to content
Kit

Context

Reference for the context Kubb passes to plugin code: what this, the ctx argument and useKubb() are in each hook, which composables work where, and withContext.

Kubb runs every plugin hook with one context object. In each hook, this, the ctx argument and useKubb() are that same object, also after an await. Composables read it, so they work in every hook, not only in setup.

Where code runs

The context depends on where your code runs. Printer handlers and macro callbacks are the exceptions: they get their own small context as this and as their second argument, while useKubb() keeps returning the context of the hook that runs them.

Codethis and ctxuseKubb() returns
setup and kubb:plugin:setupThe setup contextThe setup context
Events Kubb fires: kubb:build:start, kubb:plugin:start, kubb:plugin:end, kubb:plugins:end, kubb:build:endThe plugin's own visit contextThe plugin's own visit context
Events fired inside a hook, with ctx.hooks.callHook(...)The context of the hook that fired the eventThe context of the hook that fired it
Visit hooks: kubb:plugin:visit:start, :schema, :operation, :endThe plugin's visit contextThe plugin's visit context
Generator match, schema, operation, operations, the printer factory and the kubb:generate:* eventsThe generator contextThe generator context
Printer handlersThe printer context, with transform and baseThe generator context
Macro callbacksThe walk context, with the node's parentThe visit context of the running hook

A plugin has one visit context per build. Its bus hooks and its visit hooks get the same object, so a value you set on it in kubb:build:start is there in kubb:plugin:visit:schema.

  • The setup context holds options, setOptions, injectFile and the members every context has.
  • The visit context holds config, plugin, memo, hooks, requirePlugin, upsertFile and the other visit hook members.
  • The generator context is the visit context plus resolver, getResolver(name), per-node options and printer.

Composables

Use composables for plugin-level concepts in setup, and read ctx for the rest.

ComposableWorks in
useKubb(), tryUseKubb()Any hook. tryUseKubb() returns undefined outside one instead of throwing.
useConfig(), requirePlugin(name)Any hook.
memo(key, fn), memo.get, memo.set, memo.hasAny hook. They read the build memo of the running hook.
memo(store, key, fn)Anywhere. It caches in the store you pass and needs no hook.
getResolver(name)Any hook. Pass a memo as the second argument, getResolver(name, memo), outside a hook.
setOptions(), useOptions(), injectFile()setup and kubb:plugin:setup. Elsewhere they throw KUBB_NO_CONTEXT.
addGenerator(), setResolver(), addMacro(), setMacros(), setPrinter(), provide()setup and kubb:plugin:setup of a plugin defined with defineExtension from kubb/kit.

Outside every hook, a composable that needs a context throws KUBB_NO_CONTEXT.

plugin.ts
import { defineExtension, getResolver, memo, useConfig } from 'kubb/kit'

export const pluginExample = defineExtension({
  kind: 'plugin',
  meta: { name: 'plugin-example' },
  hooks: {
    'kubb:plugin:visit:schema'(node) {
      const names = memo('plugin-example:names', () => new Set<string>())
      if (node.name) names.add(getResolver('plugin-ts').name(node.name))
      console.log(useConfig().root, this.plugin.name)
    },
  },
})

Setup methods

In a plugin defined with defineExtension from kubb/kit, the setup context also has the setup composables as methods. See Setup context.

withContext

withContext(ctx, fn) runs fn with ctx as its this, its argument and the value useKubb() returns, also after an await in fn. It returns what fn returns. Kubb runs every hook through it.

Type definition
function withContext<TContext extends object, TResult>(ctx: TContext, fn: (this: TContext, ctx: TContext) => TResult): TResult

Extension authors use it to run their own callbacks with a context, so composables work there too:

import { useKubb, withContext } from 'kubb/kit'

await withContext(ctx, async function () {
  console.log(this === useKubb()) // true
})

In tests

A plugin test can call a generator or hook through withContext instead of kubbContext.run. It also sets this, so code that reads this or useKubb() sees your test context:

generator.test.ts
import { withContext } from 'kubb/kit'

const files = await withContext(ctx, (ctx) => typeGenerator.schema?.call(ctx, node, ctx))