Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt

Use this file to discover all available pages before exploring further.

The ConfigPlugin supports loading configuration from YAML files via the loadYaml option. This enables structured, hierarchical configuration alongside environment variables.

​
Overview

When loadYaml is enabled, the loadConfig function:
  1. Loads and parses YAML config files using js-yaml (v4.1.1+)
  2. Merges YAML config with environment variables (env vars take precedence)
  3. Validates the merged config against your Zod schema

​
Quick Start

​
1. Enable YAML loading

import { ConfigPlugin } from '@frontmcp/sdk';

@App({
  plugins: [
    ConfigPlugin.init({
      basePath: __dirname,
      loadYaml: true,           // Enable YAML loading (default: false)
      configPath: 'config.yml', // Path to YAML file (default: 'config.yml')
    }),
  ],
})
class MyApp {}

​
2. Create a YAML config file

# config.yml
database:
  url: postgres://localhost:5432/myapp
  port: 5432
  pool:
    min: 2
    max: 10

api:
  key: your-api-key
  timeout: 30000

debug: false

​
3. Define your schema

import { z } from '@frontmcp/sdk';

const configSchema = z.object({
  database: z.object({
    url: z.string(),
    port: z.number().default(5432),
    pool: z.object({
      min: z.number().default(2),
      max: z.number().default(10),
    }).default({ min: 2, max: 10 }),
  }),
  api: z.object({
    key: z.string(),
    timeout: z.number().default(30000),
  }),
  debug: z.boolean().default(false),
});

​
Using loadConfig Directly

For programmatic configuration loading outside of plugins: 
import { loadConfig } from '@frontmcp/sdk';
import { z } from '@frontmcp/sdk';

const schema = z.object({
  database: z.object({
    url: z.string(),
    port: z.number().default(5432),
  }),
});

// Load with YAML support
const config = await loadConfig(schema, {
  basePath: __dirname,
  loadYaml: true,
  configPath: 'config.yml',
});

console.log(config.database.url);

​
Configuration Options

​
loadYaml

PropertyTypeDefaultDescription
loadYamlbooleanfalseEnable YAML config file loading
When false (default), only environment variables and .env files are loaded. Set to true to also load YAML configuration.

​
configPath

PropertyTypeDefaultDescription
configPathstring'config.yml'Path to YAML config file relative to basePath

​
Accepted File Extensions

The loader automatically tries these extensions in order:
  • .yml
  • .yaml
  • No extension (if configPath includes the extension)
// All of these work:
configPath: 'config'      // → tries config.yml, config.yaml
configPath: 'config.yml'  // → tries config.yml
configPath: 'config.yaml' // → tries config.yaml
configPath: 'app/settings.yml'  // → relative path supported

​
Priority and Merging

Configuration sources are merged with this priority (highest to lowest):
  1. Environment variables (process.env)
  2. .env.local file
  3. .env file
  4. YAML config file (when loadYaml: true)
  5. Schema defaults (from Zod .default())
Environment variables always override YAML values. This allows you to commit safe defaults in YAML while overriding sensitive values via environment variables in production.

​
Example: Override YAML with Env Vars

# config.yml
database:
  url: postgres://localhost:5432/dev_db
  port: 5432

# .env.local (overrides YAML)
DATABASE_URL=postgres://prod-server:5432/prod_db
The final database.url will be postgres://prod-server:5432/prod_db.

​
Error Handling

​
File Not Found

If the YAML file doesn’t exist, loading continues silently (no error). Schema defaults will be used.

​
Parse Errors

If the YAML file contains invalid syntax, loadConfig throws a standard YAML parse error from js-yaml.

​
Validation Errors

If the merged configuration fails schema validation, a ConfigValidationError is thrown: 
import { ConfigValidationError } from '@frontmcp/sdk';

try {
  const config = await loadConfig(schema, { loadYaml: true });
} catch (error) {
  if (error instanceof ConfigValidationError) {
    console.error('Config validation failed:', error.message);
    console.error('Zod errors:', error.zodError.issues);
  }
}

​
Dependency

YAML loading depends on js-yaml version ^4.1.1 or higher. This dependency is included in @frontmcp/sdk and requires no additional installation. 
// @frontmcp/sdk package.json
{
  "dependencies": {
    "js-yaml": "^4.1.1"
  }
}
Version 4.1.1+ is required to address CVE-2025-64718. Earlier versions should not be used.

​
Complete Example

import { FrontMcp, App, Tool, ToolContext, ConfigPlugin } from '@frontmcp/sdk';
import { z } from '@frontmcp/sdk';

// Define typed schema
const configSchema = z.object({
  database: z.object({
    url: z.string().describe('Database connection URL'),
    port: z.number().default(5432).describe('Database port'),
  }),
  features: z.object({
    darkMode: z.boolean().default(false),
    maxItems: z.number().default(100),
  }).default({ darkMode: false, maxItems: 100 }),
});

type Config = z.infer<typeof configSchema>;

@App({
  name: 'my-app',
  plugins: [
    ConfigPlugin.init({
      basePath: __dirname,
      loadYaml: true,
      configPath: 'config.yml',
      schema: configSchema,
    }),
  ],
  tools: [MyTool],
})
class MyApp {}

@Tool({
  name: 'get-settings',
  description: 'Get current configuration settings',
  inputSchema: {},
})
class MyTool extends ToolContext {
  async execute() {
    return {
      dbPort: this.config.getNumber('database.port'),
      darkMode: this.config.getBoolean('features.darkMode'),
    };
  }
}

@FrontMcp({
  info: { name: 'YAML Config Demo', version: '1.0.0' },
  apps: [MyApp],
})
export default class Server {}