defineConfig | Kizuna.js

defineConfig({ adapter, routes, identities, ... }) is where an API comes together. It takes what you declared with k, resolves each route's auth, checks the pieces against one another, and hands back the api you mount.

It lives in kizuna.config.ts at the root of your app, which is where the CLI looks for it.

import { defineConfig } from 'kizunajs';
import { expressAdapter } from '@kizunajs/express';
import { routes } from './src/routes';
import { user } from './src/identities';

export default defineConfig({
    adapter: expressAdapter(),
    routes,
    auth: {
        identities: {
            user,
        },
    },
});

import express from 'express';
import kizuna from '../kizuna.config';

const app = express();

kizuna.api.mount(app);

What it takes

Field	What it is
`adapter`	The framework this API is served on, as a call: `expressAdapter()`. Its request reaches every handler, typed.
`routes`	A list of what `k.routes` returned, in any order. Each route is keyed by its group, and carries its own handler. Omit it while setting up.
`auth`	Who may call this API: `identities`, each declared with `k.identity` and carrying its own guard, and the `guardSchema` their `deny()` produces.
`requestContext`	What every route resolves before its guards run, declared with `k.requestContext`.
`validation`	How a request is checked: `issueCodes`, the `code` values `k.issue` may emit beyond Zod's own.
`jobs`	Scheduled work, declared with `k.jobs`.
`jobRunner`	How this deployment runs them: `mode`, `path`, `method`, `transport`, `onError`. See Jobs.
`plugins`	What this API installs beside its own routes, as a list. See Create a Plugin.
`groups`	The groups routes are filed under, from `k.groups`.
`typescript`	Where `kizuna generate` writes the `Config`, as `{ outputFile }`.
`clients`	The clients `kizuna generate` writes from this API, each built with `defineClient`.

jobs is what the jobs are, and jobRunner is how this deployment runs them: the first is shared by every config that serves these routes, the second differs between dev and production.

What it hands back

The api: everything you declared, plus the ability to serve it. It carries routes, securitySchemes, groups and the rest, so anything that reads a declaration takes it directly:

import { generateOpenApi } from '@kizunajs/openapi';
import kizuna from '../kizuna.config';

const document = generateOpenApi(kizuna.api);

And clients, which the CLI reads when it generates.

Access control

Every route carries its own auth: the identity it requires, and the roles it accepts or the permissions the caller has to hold. Once a config declares an identity, a route without an auth does not compile, so public takes an explicit false. See Access Control for the walkthrough.

export const workspaceRoutes = k.routes.workspace({
    getWorkspace: k
        .route({
            method: 'GET',
            path: '/workspace',
            auth: 'member',
            responses: {
                200: WorkspaceSchema,
            },
        })
        .handler(({ auth }) => ({
            status: 200,
            body: db.workspaces.find(auth.member.workspaceId),
        })),
});

defineConfig resolves each auth onto that route's security, roles and requires, which the guards, the route handler types, and the OpenAPI document all read.

An identity a route names has to carry a guard, or the config refuses to assemble.

Jobs

Jobs declared with k.jobs go under jobs, beside routes:

export default defineConfig({
    adapter: expressAdapter(),
    routes,
    jobs,
    jobRunner: {
        mode: 'http',
    },
});

jobRunner is required once jobs declares one, and its mode says how they run: 'http' serves the two job endpoints, 'in-process' leaves them unmounted for startJobs to tick. A job carries its own identity, so it declares no auth, and it stays out of api.routes, the OpenAPI document, and the generated Swift, Kotlin and MCP surfaces. See Jobs.

Plugins

Plugins go under plugins, as a list. Each carries the name your handlers read it under:

export default defineConfig({
    adapter: expressAdapter(),
    routes,
    plugins: [
        mcpPlugin({
            name: 'My API',
        }),
        openApiPlugin({
            info: {
                title: 'My API',
                version: '1.0.0',
            },
        }),
    ],
});

Their routes are served by api.mount, and reach the clients like your own unless they're marked hidden. See Create a Plugin.