Configuration: Give Plugins Validated Options and Defaults

Behavior choices can stay in cordis.yml or a profile patch while runtime preconditions remain explicit.

01 / Keep the type and schema together

A configurable plugin can declare its options like this:

import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'

export interface Config {
  greeting: string
  targets: string[]
}

export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  targets: Schema.array(String).default(['world']),
})

export function apply(ctx: Context, config: Config) {
  for (const target of config.targets) {
    console.log(config.greeting + ', ' + target + '!')
  }
}

The Config interface supplies static TypeScript types. The runtime schema with the same name validates and defaults values. A plain object is not enough because Cordis needs a runtime validator that follows Standard Schema.

02 / Configuration comes from cordis.yml

- name: './config-demo.ts'
  config:
    targets: ['alpha', 'beta']

Because greeting is omitted, the schema fills in Hello. apply receives a complete configuration:

Hello, alpha!
Hello, beta!

03 / Errors appear before apply

Pass a string where the schema requires an array:

- name: './config-demo.ts'
  config:
    targets: 'not-an-array'

Loader reports a path-aware ValidationError, for example:

ValidationError: invalid config:
  - $.targets expected array but got not-an-array (at targets)

The Fiber enters FAILED and the launcher exits with failure. The plugin does not run several steps with bad input and leave an ambiguous error deeper in the runtime.

04 / The schema is part of the configuration API

A schema records input types, defaults, and constraints together. If a field changes deployment behavior, make it a schema field instead of scattering a DEFAULT_* constant through the plugin.

This repository uses Schemastery, while Cordis accepts validators that follow Standard Schema. Schemas can also express required values, unions, arrays, and objects.

05 / Keep computed values in explicit locations

The repository’s loader extension supports !!js:

- name: './config-demo.ts'
  config:
    greeting: !!js process.env.DEMO_GREETING ?? 'Hello'

It is evaluated only inside config and an entry’s disabled field. Metadata such as name, id, and inject stays static. A config expression is evaluated against the plugin Context after required services are active; disabled is evaluated against the Loader Context at each mount decision. For environment-specific composition, a profile overlay is usually clearer than making every metadata field dynamic.

Where to go next

• cordis.yml: Configuration as Composition
• Lifecycle and effects
• Composition and HMR

Sources: configuration tutorial, Schemastery, and Fiber implementation.