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:

import type { CraftConfig } from '@routecraft/routecraft'

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

Configuration fields

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.

Environment variables

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

# .env
LOG_LEVEL=debug
NODE_ENV=development

Related