---
title: defineVector() API reference
description: Define one Vector Configuration from its identity and a builder-bound Context callback that returns the complete Extension Plan for each activation.
sidebar:
  label: defineVector
---

Import `defineVector()` from `@evilkiwi/vector`.

```ts title="TypeScript"
function defineVector(definition: VectorDefinition): Plugin.Plugin;
```

## VectorDefinition

| Field   | Required | Meaning                                                                                       |
| ------- | -------- | --------------------------------------------------------------------------------------------- |
| `id`    | Yes      | Non-empty Vector Configuration identity. Empty or whitespace-only values throw synchronously. |
| `build` | Yes      | Synchronous callback from the builder-bound `Context` to its `ExtensionPlan`.                 |

`defineVector()` does not accept `runtimeConfig`. Pass Runtime Configuration metadata to [`createVectorBuilder()`](/api/create-vector-builder), then call that builder's `defineVector()` method. The root helper and `createVectorBuilder()` without options provide no-config behavior.

`defineVector()` captures `id` and `build` when called. It returns the pinned `Plugin.Plugin` type from OpenCode 2. Default-export that value as the OpenCode Plugin Entrypoint.

## ExtensionPlan

The `build(context)` callback may return arrays for all Extension Definition domains:

`agents`, `catalogProviders`, `commands`, `integrationMethods`, `integrations`, `mcpServers`, `models`, `references`, `skills`, `tools`, and `webSearchProviders`.

It may also select `defaultAgent`, `defaultModel`, and `defaultWebSearchProvider`. A default must name a compatible extension in the same completed Snapshot. `defaultWebSearchProvider` may be `false` to select the host's disabled value. Omitted arrays materialize as empty arrays.

### instructionFiles

`instructionFiles?: (string | URL)[]` selects ordered Configuration Package files that supply Global Instructions. Use a `file:` URL to select a file relative to the current module:

```ts title="vector.ts"
const plan: ExtensionPlan = {
  instructionFiles: [new URL('../instructions/global.md', import.meta.url)],
};
```

String entries must be absolute paths or begin with `~/`; URL strings, globs, and relative paths remain invalid. URL objects must use `file:`. Other URL schemes, directories, and missing or unreadable files fail activation before any host transform registration.

Vector converts file URL objects with Node's `fileURLToPath`, expands `~/` in strings, resolves each source to its canonical regular file, deduplicates canonical paths by first occurrence, and reads the retained files as UTF-8 in order. Symlink aliases therefore contribute one block, while distinct files with identical content each contribute a block. A zero-byte file contributes nothing.

Each retained block has this exact shape, where `<exact content>` is not trimmed or normalized:

```text
Instructions from: <canonical path>
<exact content>
```

Vector joins the blocks with `\n\n`. The agent transform applies selected Agent Definitions first, preserves each agent's existing `system`, appends the joined Global Instructions to every built-in, host-defined, and Vector-defined agent returned by OpenCode, then selects `defaultAgent`. Replay does not append an identical trailing block again. Omitting `instructionFiles` or returning an empty array leaves agent systems unchanged.

Read [`createVectorBuilder()`](/api/create-vector-builder) to bind inferred Runtime Configuration and computed Context types across configuration and extension callbacks. See [Extensions](/api/extensions) for helper inputs and identity behavior.