# Development Mode for GraphQL Federation

Start building against the router in one line of config. `dev_mode: true` turns on human-readable logs, detailed subgraph error output, and automatic localhost fallback inside Docker.

## Local federation should not fight you

Defaults that protect production often erase the signal you need on your laptop. Docker networking and half-configured YAML make it worse.

### Production defaults hide what you need to see

Structured JSON logs and sanitized errors are useful in production, but harder to debug locally. Reading a 400-line JSON blob for a single request is not how debugging should start.

### Inside a container, localhost is not your host

A subgraph URL like `http://localhost:4001` works on your laptop because `localhost` is your machine. From the router running in Docker, the same URL still means “this container,” so the process never reaches services on your Mac or Windows host. That mismatch trips teams constantly during local federation.

### Development settings drift over time

Teams often end up maintaining separate debug flags, error settings, and logging overrides across environments. Months later, nobody remembers why stack traces appear in one setup but not another.

## One line of config enables development-friendly router defaults

Cosmo Router development mode bundles the router settings most teams enable during local development into a single preset, so developers can debug locally without hand-configuring logging, error propagation, and Docker networking behavior.

### What happens when the preset is on

1. Set `dev_mode: true` in the router config. At startup, the router loads a development-focused preset instead of requiring individual debugging settings to be configured manually.
2. The preset bundles settings you would otherwise flip one by one. It disables JSON logs, enables full subgraph error propagation (HTTP status codes, GraphQL locations, and stack trace fields when the subgraph sends them), and turns on Advanced Request Tracing (ART) for local development.
3. When a subgraph URL uses `localhost` and the connection fails inside Docker, the router retries against `host.docker.internal` automatically (unless you disable the fallback).
4. Config changes reload automatically during development, so teams can iterate without restarting the router.
5. You spend time building, not configuring multiple settings manually, and you remove or set `dev_mode: false` before production so debug output does not appear in production responses.

## Before & After

| Before Cosmo | With Cosmo |
| --- | --- |
| Five separate toggles to get useful dev output | `dev_mode: true` flips them all at once |
| JSON logs that are hard to read during debugging | Human-readable, terminal-friendly logs |
| Sanitized errors, unclear why a query failed | Expanded subgraph error context: status codes, locations, and stack traces when available |
| Docker-to-localhost networking needs manual setup | Automatic fallback to `host.docker.internal` on failure |

### What `dev_mode: true` enables

`dev_mode: true` is a preset equivalent to:

- json_log: false
- subgraph_error_propagation:
  - propagate_status_codes: true
  - omit_locations: false
  - allowed_extension_fields: ["code", "stacktrace"]

Plus: Advanced Request Tracing (ART) is enabled automatically in local development environments, as well as automatic Docker-to-localhost fallback.

## Using development mode

### Flip the toggle

Add `dev_mode: true` to the router config and start the router locally.

### Same development settings every time the router starts

At startup the preset applies in one go: readable logs, richer subgraph errors, local ART, and the Docker fallback.

### See failures where they happen.

Run queries against the router locally. Errors become easier to debug, logs are readable in the terminal, and Docker localhost failures recover automatically.

### Production configs stay explicit.

Disable development mode in production configs to keep production logging and error responses sanitized.

## Where teams lean on dev mode

### First-time router setup

A new developer pulls the repo, starts the router with `dev_mode: true`. Within a minute they have readable logs, working Docker networking, and expanded error output, none of which they had to configure.

### Debugging a failing federated query

A query returns an error. Development mode surfaces the subgraph's HTTP status code, the error location in the query, and the stack trace when the subgraph provides one.

### Docker Compose with local subgraphs

Router in Docker; subgraphs on the host at `localhost:4001` and `localhost:4002`. If `localhost` fails in-container, retries use `host.docker.internal:4001`.