Tianyi Cui
3dfb16008d
Code already treats $DSH_HOME/.env as ordinary launch environment and stores managed credentials in .credentials.yaml, but public docs still described the old store, old precedence, removed literal adapter keys, and the deleted TUI. That directed users to the wrong file and overstated the supported configuration surface. Update the existing English and Chinese owners in place, document inherited > managed > project > user credential resolution, and record the loadLayeredEnv export. Regenerate only pairing records and the source-line catalog; add no new section or site route.
2.6 KiB
5. Configuration
English | 中文
Each cordis.yml entry can carry a config block, and the plugin declares a schema that validates it before apply runs. Bad config fails the load with a precise error — the plugin never starts half-configured.
A configurable plugin
Create config-demo.ts in tmp/cordis-tutorial:
import type { Context } from 'cordis'
import Schema from 'schemastery'
export const name = 'config-demo'
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 exported Config is both a TypeScript interface and a runtime schema with the same name — consumers get the type, Cordis gets the validator. This repo uses Schemastery for schemas; Cordis itself accepts any Standard Schema validator, so a plain object exported as Config will not work.
Configure it:
- name: './config-demo.ts'
config:
targets: ['alpha', 'beta']
Run:
Hello, alpha!
Hello, beta!
greeting was omitted, so the schema default filled it in — apply always receives complete, validated config.
Fail loud
Now feed it something invalid:
- name: './config-demo.ts'
config:
targets: 'not-an-array'
ValidationError: invalid config:
- $.targets expected array but got not-an-array (at targets)
The plugin's fiber goes to FAILED, and this tutorial's launcher exits with status 1 after printing the error. A plugin should also reject schema-valid config that names an unavailable resource or provider as soon as it can resolve that reference.
Computed config values
The loader used in this repo supports a !!js tag for config values that must be computed at load time:
- name: './config-demo.ts'
config:
greeting: !!js process.env.DEMO_GREETING ?? 'Hello'
!!js works only inside config. Entry metadata (name, id, disabled, inject, ...) is static; disabled: !!js ... produces a truthy expression object that always disables the entry. See loader configuration.
Next: Composition and HMR — treating cordis.yml as the application.
