Full reference for CraftConfig fields and logging options.

CraftConfig

The main configuration object for context settings. Export it as craftConfig (named export) alongside your capabilities when using craft run. The recommended pattern is defineConfig, an identity helper that preserves literal-type inference (so autocomplete works for first-class keys):

import { defineConfig } from '@routecraft/routecraft'

export const craftConfig = defineConfig({
  store: new Map([
    ['my.adapter.config', { apiKey: 'xyz' }]
  ]),
  on: {
    'context:starting': ({ ts }) => console.log('Starting at', ts)
  },
})

defineConfig is a no-op at runtime; it returns the input unchanged. The legacy satisfies CraftConfig pattern continues to work.

Configuration fields

Ecosystem keys (added by @routecraft/ai)

When @routecraft/ai is imported (anywhere in the project), CraftConfig is augmented with first-class keys for the AI plugins. Each key carries the same options as the corresponding factory and participates in the standard plugin lifecycle.

import { defineConfig } from '@routecraft/routecraft'
import '@routecraft/ai' // augments CraftConfig with llm/mcp/embedding/agent

export const craftConfig = defineConfig({
  llm: {
    providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
    defaultProvider: 'openai',
  },
  mcp: { clients: { /* ... */ } },
})

The legacy plugins: [llmPlugin(...)] form continues to work and is the right escape hatch for shared plugin instances or programmatic composition.

Core adapter defaults

Core adapters have dedicated config fields so you can set context-wide defaults without importing a plugin. See Merged Options for how the merge hierarchy works.

cron

Default options applied to every cron() source in this context. Per-adapter options always take precedence.

const config: CraftConfig = {
  cron: { timezone: 'UTC', jitterMs: 2000 },
}

direct

Sets the channel implementation used by all direct() endpoints in this context. Use this to swap the default in-memory channels for a distributed implementation (e.g. Kafka, Redis).

import { KafkaChannel } from 'my-kafka-adapter'

const config: CraftConfig = {
  direct: { channelType: KafkaChannel },
}

When omitted, direct endpoints use the built-in in-memory channel (single-consumer, blocking send).

Logging configuration

Logging uses a single pino instance configured at module load. Precedence (highest wins):

1. Environment variables -- LOG_LEVEL / CRAFT_LOG_LEVEL, LOG_FILE / CRAFT_LOG_FILE, LOG_REDACT / CRAFT_LOG_REDACT (comma-separated paths to redact)
2. Config file in cwd -- craft.log.cjs or craft.log.js in the current working directory
3. Config file in home -- craft.log.cjs or craft.log.js in ~/.routecraft/
4. Defaults -- level "warn", stdout, no redact

The config file exports a native pino options object (e.g. level, redact, formatters, transport). Env vars are merged on top, so env always wins.

Example craft.log.js (or craft.log.cjs in a CommonJS project):

// craft.log.js
export default {
  level: "info",
  redact: ["req.headers.authorization"],
};

When using the CLI, pass --log-level or --log-file to set the corresponding env var before the logger initializes, so CLI flags override any config file.

Service name

Set name on the context to tag every log line with a service.name field (the OpenTelemetry semantic convention). This identifies the originating application when shipping logs to an aggregator, and lines up with OTel resource mappings such as BetterStack's resources.service.name.

import { defineConfig } from "@routecraft/routecraft";

export const craftConfig = defineConfig({
  name: "eywa",
});

Every log emitted through the context, its routes, and their exchanges then carries the field:

{ "level": "info", "service.name": "eywa", "route": "zoe-mail", "msg": "..." }

When name is omitted, no service.name field is added. The value is a per-context log binding; it does not configure OpenTelemetry trace resources. If you also export traces via telemetry({ tracerProvider }), set the matching service.name on that provider's Resource so logs and spans agree.

Environment variables

Routecraft automatically loads environment variables from .env files when using the CLI:

# .env
LOG_LEVEL=debug
NODE_ENV=development

Related