## Overview

Router-level feature flags let you swap a subgraph at request time without a redeploy. Each flag defines a replacement subgraph. When a request includes the matching header or cookie, the router resolves the target subgraph to the flagged replacement.

For a primer on Cosmo feature flags and rollout strategies, see the [concepts guide](https://cosmo-docs.wundergraph.com/concepts/feature-flags).

## Manage feature flags with Cosmo (recommended)

The recommended way to manage and deploy feature flags is with the **wgc** CLI and **Cosmo Cloud** (or self-hosted Control Plane). You create feature subgraphs, compose them into a feature flag via [`wgc feature-flag create`](https://cosmo-docs.wundergraph.com/cli/feature-flags/create-feature-flag), and Cosmo produces the feature-flag configuration as part of the router config. The router then receives this configuration when it fetches its config from the Control Plane—no local YAML needed.

To get started:

1. Create a feature subgraph with [`wgc feature-subgraph create`](https://cosmo-docs.wundergraph.com/cli/feature-subgraph/create-feature-subgraph).
2. Create and enable a feature flag with [`wgc feature-flag create`](https://cosmo-docs.wundergraph.com/cli/feature-flags/create-feature-flag), attaching the feature subgraph(s) and labels for your federated graph(s).

For a full walkthrough, see the [gradual rollout with feature flags tutorial](https://cosmo-docs.wundergraph.com/tutorial/gradual-and-experimental-feature-rollout-with-feature-flags).

## Alternative: Local composition

If you run the router using a **local config file** (e.g. `router-compose.yaml`) instead of fetching config from Cosmo, you can still use feature flags. Define `feature_flags` and `feature_graphs` in the same input file you pass to [`wgc router compose`](https://cosmo-docs.wundergraph.com/cli/router/compose). The compose command will include the flag configuration in the generated router config. For the input file structure and a full example, see [Compose — Feature flags (optional)](https://cosmo-docs.wundergraph.com/cli/router/compose#feature-flags-optional).

Key points:

- `feature_flags[*].name` is the value you will send from the client (case sensitive).
- `feature_graphs[*].subgraph_name` must match the corresponding entry under `subgraphs` (`checkout` in the example).
- The router swaps the referenced `subgraph_name` with the replacement defined in `feature_graphs` when the flag is active.

Name feature flag schemas using the `feature-flag_*.graphql` convention and check in an empty placeholder subgraph file to keep composition predictable.

## Trigger the Flag

Activate a flag by sending the header (or matching cookie) with the desired flag name. All requests that include the header are routed through the replacement subgraph.

```
GET /graphql HTTP/1.1
Host: router.example.com
X-Feature-Flag: test_checkout
```

When the router receives `X-Feature-Flag: test_checkout`, it composes the operation against the replacement schema and forwards traffic to the routing URLs declared in the flag configuration.