What is a feature subgraph?

A feature subgraph is an alternative implementation of a base subgraph in your federated graph. When a feature flag is active for a request, the router composes the graph using the feature subgraph instead of the base subgraph for that request. The base subgraph remains unchanged and serves all other requests.

How are feature flags activated per request?

Feature flags are activated based on request context: specific HTTP headers, JWT claims, or cookies. The router uses this request context at the routing layer to select the appropriate graph composition. Requests that match the criteria receive the feature composition; all other requests use the base composition.

Shadow mode routes traffic to both the base implementation and the feature implementation, then compares results before exposing the change. Validate correctness and performance with production traffic before wider rollout.

Does enabling or disabling a flag require redeployment?

No. Feature flags are toggled at runtime. Changes propagate in under one second without deploying a new router version.

What are the version requirements?

Feature Flags require Cosmo Router v0.95.0 or later and wgc CLI v0.58.0 or later.

Can multiple feature flags be active at once?

Cosmo supports unlimited feature flags per federated graph.

Is there a latency cost to feature flag evaluation?

Feature flag evaluation is computed at composition time and adds zero additional latency for evaluation.

Is Feature Flags available on the Free tier?

No. Feature Flags require a Pro or Enterprise plan.

Do Cosmo Feature Flags replace LaunchDarkly or Split?

No. Cosmo Feature Flags work at the federation composition level. They complement app-level feature flags rather than replacing them.

GraphQL Feature Flags | Cosmo by WunderGraph

The problem

Why GraphQL schema changes are hard to release safely

In a federated GraphQL architecture, one breaking change or performance regression can affect every client immediately. Staging alone cannot show how a change behaves with real production traffic.

Schema changes can affect every client immediately

A breaking change or performance regression can reach every client before teams know how it behaves in production. Without progressive rollout, teams cannot validate changes with a small user segment before rolling out to more traffic.

Rollback depends on another deployment

When a released feature causes problems, teams often have to revert code, redeploy services, or perform a full rollback deployment. That takes time during the exact moment when they need a fast, low risk way to disable the change.

Subgraph teams block each other during coordinated releases

When multiple teams change different subgraphs, releases slow down because everyone has to coordinate timing, validation, and rollback plans. Teams often create separate staging environments, but those environments still do not prove how the change behaves with real production traffic.

Our solution

Feature flags for safer GraphQL schema delivery

Feature subgraphs are alternative implementations of base subgraphs in your federated graph. When a feature flag is active for a request, Cosmo Router uses the feature subgraph instead of the base subgraph for that request. Teams can roll out schema changes by header, JWT claim, or cookie without deploying a new router version.

How it works

Create a feature subgraph as an alternative implementation of a base subgraph.
Create a feature flag that activates the feature subgraph for matching requests.
Define activation criteria using headers, JWT claims, or cookies.
For matching requests, Cosmo Router uses the graph composition with the feature subgraph. Other requests continue using the base composition.
Enable or disable the flag at any time. Changes propagate in under one second without deploying new router versions.

Schema-aware. Federation-native. Without deploying new router versions.

Feature flags

What changes with Cosmo

Before Cosmo	With Cosmo
Release schema changes broadly	Gradually roll out changes to selected traffic segments, such as 1%, 10%, 50%, then 100%, using request context such as headers, JWT claims, or cookies
No native way to validate schema changes with production traffic	Use shadow mode to compare behavior before exposing the change
Problematic changes often require rollback deployments	Disable the feature flag in under one second without deploying new router versions
Separate staging environments for each feature	Shared staging with per-developer feature isolation

Activation methods

Activate flags from request context

HTTP headers — activate a feature subgraph when a request includes a matching header value.
JWT claims — activate a feature subgraph when a token includes a matching claim, such as a subscription tier.
Cookies — activate a feature subgraph when a request includes a matching cookie value.
Shadow mode — compare the feature subgraph against the base implementation with real traffic before exposing the change.

Key benefits

Release GraphQL changes gradually with instant rollback

Feature Flags are available on Cosmo Pro and Enterprise.

Roll out changes to specific user segments

Activate feature subgraphs for matching requests based on headers, JWT claims, or cookies. Move from small user segments to broader rollout by changing the request criteria or upstream traffic routing, without deploying new router versions.

Validate schema changes with real traffic before exposing them

Use shadow mode to compare the feature subgraph against the base implementation with real traffic. Validate correctness and performance before wider exposure.

Disable risky changes without deploying new router versions

If a feature causes problems, disable the feature flag in under one second. Changes propagate without code changes or deploying new router versions.

Serve different graph compositions by request context

Activate feature flags based on headers, JWT claims, or cookies. Different requests can use different graph compositions from the same router, enabling A/B testing, premium feature access, and personalized API experiences.

Let developers test in isolation on shared staging

Each developer can create a feature subgraph for their changes and use a unique header or cookie while testing. Matching requests use their feature subgraph. Other traffic stays on the base composition, without dedicated staging infrastructure per developer.

How Cosmo Feature Flags work

01

Alternative, not replacement.

Create a feature subgraph

Publish a feature subgraph as an alternative implementation of a base subgraph. When the flag is active, matching requests use the feature subgraph instead of the base subgraph.

02

Links feature to base.

Create a feature flag

Create a feature flag that connects the feature subgraph to the base subgraph it can replace for matching requests. Keep the flag disabled until you are ready to test or roll out the change.

03

Header, JWT, or cookie.

Set activation criteria

Define activation criteria using headers, JWT claims, or cookies. Cosmo Router evaluates matching requests and routes them to the feature composition.

04

Compare before exposing.

Use shadow mode before exposure

Compare the feature subgraph against the base implementation with real traffic before wider exposure. Use it to validate correctness and performance before rollout.

05

Under one second to propagate.

Roll out, expand, or disable the flag

Enable the flag for a target user segment, expand traffic rollout over time, or disable it if something goes wrong. Changes propagate in under one second without deploying new router versions.

Use cases

Where Cosmo Feature Flags help most

Migrate from a monolith to federation safely

Migration

Create a feature subgraph that overrides fields from the monolith using `@override`. Use shadow mode to compare the monolith and federated implementation with real traffic, then gradually increase traffic to the new subgraph while monitoring performance. Once the migration is validated, publish the schema change without the feature flag.

Roll out experimental features to selected user segments

Rollout

Create a feature subgraph for the new implementation, then activate matching requests for a selected user segment using a JWT claim, header, or cookie. Validate performance and gather feedback before expanding rollout by updating activation criteria or upstream traffic routing that sets the relevant headers, claims, or cookies.

Let developers test independently on shared staging

Staging

Each developer creates a feature subgraph for their changes and uses a unique header or cookie while testing. Matching requests use their feature subgraph. Other traffic stays on the base composition, so teams can avoid dedicated staging infrastructure per developer.

When to use Cosmo Feature Flags

Use Feature Flags when

You want to release schema changes or new features to a small user segment before a full traffic rollout.
You need to validate changes with real production traffic before exposing them broadly.
You need to disable a problematic feature quickly without deploying a new router version.

Requirements

You need an existing federated graph with base subgraphs. Feature subgraphs act as alternatives to those base subgraphs.
You need Cosmo Router v0.95.0 or later and wgc CLI v0.58.0 or later.
Feature Flags are available on Cosmo Pro and Enterprise.

Roll out GraphQL schema changes safely

Use Cosmo Feature Flags to test, roll out, and disable schema changes without deploying a new router version.

Talk to Sales Read the rollout tutorial

Ready to go deeper?

Full reference for feature flag concepts, CLI commands for feature flags and feature subgraphs, and a step-by-step tutorial.

Concepts docs →CLI reference →Tutorial →

Safely roll out GraphQL schema changes with feature flags