GraphQL Feature Flags | Cosmo by WunderGraph - WunderGraph
Safely roll out GraphQL schema changes with feature flags
Activate feature subgraphs for matching requests based on headers, JWT claims, or cookies. Test changes with real traffic, roll them out gradually, and disable risky changes without deploying new router versions.
Gradual rollouts. Shadow mode validation. Instant rollback. Without deploying new router versions.
Why GraphQL schema changes are hard to release safely
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.
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.
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 |
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.
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
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.
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.
Set activation criteria: Define activation criteria using headers, JWT claims, or cookies. Cosmo Router evaluates matching requests and routes them to the feature composition.
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.
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.
Where Cosmo Feature Flags help most
Migrate from a monolith to federation safely
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
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
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.
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.