GraphQL Router Configuration | Cosmo by WunderGraph - WunderGraph

GraphQL Router Configuration - Validated YAML with Env Expansion

Configure the router once, run it in every environment YAML with validation, environment-variable expansion, and file merging. Config errors show up before the router ever starts.

Auto-complete in VS Code and JetBrains. Secrets stay out of config files.

The problem

Config should fail in the editor, not in prod

Typed YAML, env expansion, and merges turn router config into something you can review like code.

Errors show up at runtime

A typo in a field name, a missing required setting, a deprecated option: none of that surfaces until the router boots. At that point, you are rolling back in production.

Every environment needs a different config

Dev, staging, and production share most settings but differ on URLs, log levels, and feature flags. Teams copy-paste full files per environment or reach for a templating tool that now owns your deploy process.

Secrets leak into config files

API tokens and credentials need to be in the config at runtime. If they live in the file, they end up in git.

Our solution

Catch configuration mistakes in your editor before deploy

Cosmo Router configuration is YAML validated against the JSON Schema, with environment variable expansion and multi-file merging, so mistakes show up while you type.

Point the YAML language server at the router JSON Schema from the top of your file (see the official configuration docs for the exact $schema URL). VS Code with the Red Hat YAML extension and JetBrains IDEs pick up auto-completion, hover documentation, and invalid or deprecated values while you edit.
Use ${VAR_NAME} placeholders in YAML for values that should come from the process environment. The router expands them before schema validation so tokens and other secrets do not need to live in the file you commit.
Pass several files through CONFIG_PATH as a comma-separated list (or pass --config multiple times). Each file is validated, then merged in order, and later files override earlier keys for the same setting, which covers base plus per-environment overlays without an external templating step.

Same binary everywhere, different overlay files per environment.

Before & after

Validation & secrets

Before Cosmo	With Cosmo
Config errors discovered when the router fails to boot	JSON schema catches typos and invalid values in the editor
Per-environment config duplication or external templating	Base file + override file per environment, merged by CONFIG_PATH
Secrets checked into config files	`${VAR_NAME}` expansion pulls secrets from env at runtime
No IDE help for config discovery	Auto-completion, hover docs, deprecation warnings in VS Code and JetBrains

Config merging rules

Precedence

Environment variables are lowest precedence
YAML configurations override environment variables
Later files in CONFIG_PATH override earlier files
List values are replaced wholesale, not concatenated
An empty value in a YAML file overrides a non-empty default

Configuration examples

Multi-environment setup · IDE schema header

Layer prod overrides on base, launch with CONFIG_PATH, and pin the schema for completions.

# base.config.yaml
version: "1"
listen_addr: "0.0.0.0:3002"
graph:
  token: "${GRAPH_API_TOKEN}"
poll_interval: 10s
log_level: "info"

How router configuration is loaded

Merge order is deterministic.

Load config file(s)

Router reads config.yaml in the working directory by default, or path(s) set in CONFIG_PATH. Multiple comma-separated paths load in order, with later files overriding earlier ones.

Secrets stay out of Git.

Expand environment variables

Any ${VAR_NAME} reference is replaced with the value of that environment variable. An override env file can also be loaded via OVERRIDE_ENV.

Fail fast before traffic.

Validate against the schema

Final merged configuration is validated against the JSON Schema. Type mismatches, missing required fields, and invalid enum values are reported with the offending path.

Invalid config fails before listening.

Apply and run

Fields such as intervals expect Go duration strings (10s, 5m, 1h) where the schema defines them. When validation succeeds, the router starts with the merged configuration applied.

Validate config before it reaches the cluster

Schema in the header. Secrets in the environment. Overrides in layered files.

FAQ

Router configuration

What is the minimum config I need to run the router?
Can I split config across more than two files?
How do list fields merge across files?
Where does the JSON schema live?
Does env-var expansion run before or after validation?
What happens if I reference a deprecated field?

Reference: router configuration documentation.