Runtime Configuration reference

Look up the createVectorBuilder() runtimeConfig option, file paths, precedence, schema output, slug constraints, and failure behavior.

A builder opts into per-installation Runtime Configuration with the runtimeConfig option.

import { createVectorBuilder } from '@evilkiwi/vector';
import * as z from 'zod';

const RuntimeConfig = z.object({
  audience: z.string().default('the team'),
});

const vector = createVectorBuilder({
  runtimeConfig: {
    slug: 'project-tools',
    schema: RuntimeConfig,
  },
});

export default vector.defineVector({
  id: 'project-tools',
  build: (context) => {
    context.runtimeConfig.audience;

    return {};
  },
});

Definition fields

Field	Type	Required	Meaning
`slug`	`string`	Yes	Safe basename shared by global and project Runtime Configuration files.
`schema`	Standard Schema V1 instance	Yes	Validates the merged JSON and determines `context.runtimeConfig`.

Vector accepts any Standard Schema V1 implementation. Schema defaults and transformations become the context.runtimeConfig value and type. Vector does not generate a fixed Runtime Configuration schema.

Paths and precedence

For the slug project-tools, Vector reads these files in order:

$XDG_CONFIG_HOME/opencode/project-tools.json, or ~/.config/opencode/project-tools.json when XDG_CONFIG_HOME is unset or empty.
<cwd>/.opencode/project-tools.json.

A missing file contributes an empty object. Global and project plain objects merge recursively. Project values take precedence. Arrays, scalars, null, and type changes replace the global value. Vector validates the merged value once and passes the schema output unchanged to every build callback.

When createVectorBuilder() receives no runtimeConfig, Vector skips both files and supplies a fresh mutable empty object through context.runtimeConfig for each activation.

Slug constraints

The slug uses lowercase ASCII letters and digits separated by single hyphens. It cannot begin or end with a hyphen, contain repeated hyphens, or equal a Windows reserved device name such as con, prn, aux, nul, com1 through com9, or lpt1 through lpt9. An invalid slug throws synchronously when the builder is created.

Failures

Read, JSON parse, and schema errors name the affected source and path without including raw Runtime Configuration contents. Correct the named file, schema, or value, then reload OpenCode. Vector does not watch either Runtime Configuration file.

Use Add Runtime Configuration for a complete task. See Context for callback types.