@genoacms/config

The package a config is written with, and the loader, host and build integration that read it. What a config means is under configuration ; this page is the API.

Entry pointExportsFor
@genoacms/configdefineConfig, the provider helpers, secret, env, inline, the config typesconfig authors
@genoacms/config/loadloadConfig, LoadOptionstooling
@genoacms/config/hostcreateHosttooling
@genoacms/config/vitegenoa()core's Vite config
@genoacms/config/buildthe artifact's package.jsonthe CLI

Authoring

defineConfig(config) returns its argument. It exists so TypeScript infers each stanza's provider names and checks every reference to them: a bucket naming a provider that does not exist is a type error.

import type { CollectionReference } from '@genoacms/contracts/database'
import type { Secret } from '@genoacms/contracts'
import type { Permission } from '@genoacms/internal/authorization'

/** One provider: which adapter descriptor, and that adapter's options. */
interface ProviderEntry<S extends string = string, O = unknown> {
  readonly adapter: S
  readonly options: O
}

/** Providers keyed by name. A record, so names are unique by construction. */
type Providers = Record<string, ProviderEntry>

/**
 * Tier-1 authorization: what this instance declares about who may do what.
 *
 * Separate from `security` because everything here is **authority** — re-read on every
 * resolution, never consumed — while `security` holds values that seed the Tier-2 policy document
 * once and are owned by it thereafter. Holding both in one stanza meant the difference had to be
 * explained per key; holding them apart lets the shape of the file say it.
 */
interface AuthorizationConfig {
  /**
   * Roles declared before deployment, as role name to grants.
   *
   * **Authoritative, not seeding.** A role declared here is immutable at runtime: an attempt to
   * alter or remove it through the CMS is refused when it is made. Runtime administration may
   * still create roles this does not name.
   *
   * Declarations are merged when authorization is read, never written into `roles.json`. Deleting
   * a role from here therefore removes it — and revokes the access it granted — rather than
   * leaving an editable copy behind in storage.
   */
  roles?: Record<string, Array<{ permission: Permission | '*', resource: unknown, fields?: string[] | '*' }>>
  /**
   * Role assignments declared before deployment, as subject to role names.
   *
   * Immutable at runtime on the same terms as `roles`, and resolved **without consulting
   * storage** — which is what makes an instance recoverable when its `users.json` is absent or
   * fails verification. Every subject named here can act on such an instance; nobody else can.
   *
   * The key is a subject as the authentication provider issues it, never an email address.
   */
  assignments?: Record<string, string[]>
  /**
   * Refuses **all** runtime role and assignment administration when true.
   *
   * For instances whose authorization should be fixed at deployment. Independent of the
   * immutability above, which applies only to what this file declares: with this set, even roles
   * created at runtime can no longer be changed.
   *
   * Declared here rather than under `security` because it governs exactly what this stanza
   * declares. In `security` it would be a switch deciding whether `authorization` may be edited,
   * pointing across the boundary these two stanzas exist to draw.
   */
  lockRoles?: boolean
}

/**
 * Tier-1 security defaults.
 *
 * Every value here **seeds** the signed security policy document at first start; the live values
 * live there afterwards, and editing this stanza does not move an instance that has already run.
 */
interface SecurityConfig {
  /**
   * Default lifetime of a subordinate signing key, in days.
   *
   * Declared here rather than embedded in code so that no limit is a constant.
   */
  subordinateKeyRotationDays?: number
  /** Access token lifetime in minutes. */
  accessTokenMinutes?: number
  /**
   * How long resolved grants are cached per subject, in seconds.
   *
   * The window during which a revoked permission is still honored.
   */
  grantCacheSeconds?: number
  /** Refresh token lifetime in days. */
  refreshTokenDays?: number
  /**
   * Loop iterations and recursive branches a dynamic component may spend in one render.
   *
   * A ceiling rather than a budget: it is compiled into each artifact and covered by its
   * signature, and a consumer may run below it but never above it.
   */
  maxFuel?: number
  /** How deep a dynamic component's recursive calls may nest. */
  maxDepth?: number
  /** Cumulative elements and bytes a dynamic component may ask for across one render. */
  maxAllocation?: number
  /**
   * The origins a dynamic component's data bridge may reach.
   *
   * Each an origin and nothing more — scheme, host and optional port. Empty by default, which
   * permits nothing: a bridge reaching everywhere until somebody narrowed it would be
   * indistinguishable from no bridge at all for as long as nobody noticed.
   */
  fetchOrigins?: string[]
}

interface Config<AP extends Providers, DP extends Providers, SP extends Providers,
  XP extends Providers, LP extends Providers, TP extends Providers> {
  authentication: {
    /** Tried in key order; the first `Identity` wins. */
    providers: AP
    cookieName: string
    /**
     * Agents, keyed by their subject `agent:<name>`. An agent identifies itself with its token
     * alone, on `/mcp` alone, and holds the roles `authorization.assignments` gives it.
     */
    agents?: Record<string, { label: string, token: Secret<string> }>
  }
  database: {
    providers: DP
    databases: Record<string, { provider: keyof DP & string, collections: CollectionReference[] }>
  }
  storage: {
    providers: SP
    buckets: Record<string, { provider: keyof SP & string }>
    defaultBucket: string
    /** Segment separator in storage browser URLs. Default `'|->'`. */
    pathDelimiter?: string
  }
  /** Exactly one provider. A secret store is a single authority; see @genoacms/contracts/secrets. */
  secrets: { providers: XP }
  /** Keyed by the language name a component records. */
  languages: { providers: LP }
  /** Optional: a config used only by the dev server needs no target. A build requires one. */
  deployment?: { targets: TP, default?: keyof TP & string }
  authorization: AuthorizationConfig
  security: SecurityConfig
}

/** Identity function. Exists so provider keys are inferred and cross-references are checked. */
function defineConfig<AP extends Providers, DP extends Providers, SP extends Providers,
  XP extends Providers, LP extends Providers, TP extends Providers> (
  config: Config<AP, DP, SP, XP, LP, TP>): Config<AP, DP, SP, XP, LP, TP> {
  return config
}

/** A loaded config: provider options are plain JSON, references collapsed to their `$…` objects. */
type SerializedConfig = Config<Providers, Providers, Providers, Providers, Providers, Providers>

export { defineConfig }
export type { Config, SerializedConfig, ProviderEntry, Providers, AuthorizationConfig, SecurityConfig }
ts
Expand code

authentication.agents declares the accounts of AI agents, keyed by subject agent:<name>, each with a label and a token that is a secret() of at least 43 characters. See AI agents and the MCP tools .

Provider helpers

One per service, so an adapter's options are looked up in that service's registry. Each returns { adapter, options }.

import type {
  OptionsOf,
  StorageAdapters,
  DatabaseAdapters,
  AuthenticationAdapters,
  SecretsAdapters,
  LanguageAdapters,
  DeploymentTargets
} from '@genoacms/contracts'
import type { ProviderEntry } from './config.js'

/**
 * One typed constructor per service, so an adapter's registered option type is looked up in the
 * right registry: the same specifier string may not mean the same options in two services.
 */
const entry = <S extends string, O> (adapter: S, options: O): ProviderEntry<S, O> => ({ adapter, options })

function storageProvider<S extends string> (adapter: S, options: OptionsOf<StorageAdapters, S>): ProviderEntry<S, OptionsOf<StorageAdapters, S>> {
  return entry(adapter, options)
}

function databaseProvider<S extends string> (adapter: S, options: OptionsOf<DatabaseAdapters, S>): ProviderEntry<S, OptionsOf<DatabaseAdapters, S>> {
  return entry(adapter, options)
}

function authenticationProvider<S extends string> (adapter: S, options: OptionsOf<AuthenticationAdapters, S>): ProviderEntry<S, OptionsOf<AuthenticationAdapters, S>> {
  return entry(adapter, options)
}

function secretsProvider<S extends string> (adapter: S, options: OptionsOf<SecretsAdapters, S>): ProviderEntry<S, OptionsOf<SecretsAdapters, S>> {
  return entry(adapter, options)
}

function languageProvider<S extends string> (adapter: S, options: OptionsOf<LanguageAdapters, S>): ProviderEntry<S, OptionsOf<LanguageAdapters, S>> {
  return entry(adapter, options)
}

function deploymentTarget<S extends string> (adapter: S, options: OptionsOf<DeploymentTargets, S>): ProviderEntry<S, OptionsOf<DeploymentTargets, S>> {
  return entry(adapter, options)
}

export { storageProvider, databaseProvider, authenticationProvider, secretsProvider, languageProvider, deploymentTarget }
ts
Expand code

References

HelperReturnsResolved
secret(key){ $secret: key }from the configured secrets provider, when the provider using it is constructed
env(variable){ $env: variable }from process.env, at the same moment
inline(value){ $inline: value }never: the value travels with the build

A credential option's type, Secret<T>, admits all three; the secrets provider's own options are BootstrapSecret<T>, which admits env() and inline() only. See secrets .

Loading

interface LoadOptions {
  /** Absolute project root. */
  root: string
  /** Absolute config file. Omitted: the default lookup under `root`. */
  file?: string
  mode: 'development' | 'production'
  /** `genoa build --no-inline`: inline() becomes an error in production mode. */
  forbidInline?: boolean
  /** Receives warnings (code 'config/inline'). Default: console.warn. */
  onWarning?: (issue: ConfigIssue) => void
}

declare function loadConfig (options: LoadOptions): Promise<Manifest>
ts

loadConfig evaluates the config, loads every adapter's descriptor, validates the whole config, and resolves to a Manifest, or rejects with a ConfigError holding every problem it found, each with a code and a path; the codes are listed under services . It resolves no secret and reaches no provider. Loads of one file and mode are memoized per process.

import type { SecretEncoding } from '@genoacms/contracts'
import type { SerializedConfig } from './config.js'

type AdapterKind = 'storage' | 'database' | 'authentication' | 'secrets' | 'language' | 'deployment'

/** What the host needs about one adapter without loading its descriptor again. */
interface AdapterRecord {
  readonly kind: AdapterKind
  /** Bare specifier of the runtime module. Absent for deployment targets. */
  readonly runtime?: string
  readonly secretOptions: Readonly<Record<string, SecretEncoding>>
  readonly developmentOnly: boolean
  /** npm package that owns the descriptor, and its installed version. */
  readonly package: string
  readonly version: string
}

interface Manifest {
  readonly version: 1
  readonly mode: 'development' | 'production'
  readonly config: SerializedConfig
  /** Keyed by descriptor specifier. */
  readonly adapters: Readonly<Record<string, AdapterRecord>>
  /** Development only. `dependencies` includes the config file itself. */
  readonly source?: { readonly root: string, readonly file: string, readonly dependencies: readonly string[] }
}

/** Embedded in the server bundle: no deployment stanza, no deployment adapters, no watch list. */
interface RuntimeManifest {
  readonly version: 1
  readonly mode: 'development' | 'production'
  readonly config: Omit<SerializedConfig, 'deployment'>
  readonly adapters: Readonly<Record<string, AdapterRecord>>
  readonly source?: { readonly root: string, readonly file: string }
}

const withoutDeploymentAdapters = (adapters: Manifest['adapters']): Record<string, AdapterRecord> =>
  Object.fromEntries(Object.entries(adapters).filter(([, record]) => record.kind !== 'deployment'))

/**
 * The subset of a manifest that ships inside a build.
 *
 * Deployment options are used by `genoa deploy` on the operator's machine, so they never enter the
 * artifact, and neither does anything an inline credential there might hold.
 */
function toRuntimeManifest (manifest: Manifest): RuntimeManifest {
  const { deployment, ...config } = manifest.config
  return {
    version: manifest.version,
    mode: manifest.mode,
    config,
    adapters: withoutDeploymentAdapters(manifest.adapters),
    ...(manifest.source === undefined ? {} : { source: { root: manifest.source.root, file: manifest.source.file } })
  }
}

export { toRuntimeManifest }
export type { Manifest, RuntimeManifest, AdapterRecord, AdapterKind }
ts
Expand code

The RuntimeManifest is what a build embeds: the deployment stanza and every deployment adapter are left out, so a target's options, credentials included, never enter the artifact.

The host

createHost({ manifest, load }) returns the one object per process that constructs providers. It does no I/O until a provider is asked for; then it resolves that provider's references, calls its runtime's create, and caches the instance by provider name, so two providers of one adapter are two instances. Core creates one host per server process, and the CLI one per command. Tooling that needs a constructed provider outside core — a migration script, a backup — creates its own, with a manifest from loadConfig and load: specifier => import(specifier).

Build integration

genoa() is the Vite plugin core's vite.config.ts uses. It loads the config, exposes the runtime manifest to core as a virtual module, restarts the dev server when the config or anything it imports changes, and leaves adapter runtimes external to the bundle. The CLI passes it what to load through four environment variables, the only facts that cross from the CLI into Vite:

VariableHolds
GENOA_PROJECTthe absolute project root
GENOA_CONFIGthe absolute config file; unset, the default lookup
GENOA_TARGETthe deployment target, when building
GENOA_MODEdevelopment or production

A relative path in GENOA_PROJECT or GENOA_CONFIG is an error. The CLI never lets Vite inherit these from your shell: it sets each one itself.