Will my GraphQL queries still work after the router swap?

Yes. Cosmo Router supports the same Federation query execution model as Apollo Router. Existing queries continue working without changes.

Do I need to update my subgraphs?

No. Your existing Federation-compatible subgraphs work without modification. Cosmo Router communicates with subgraphs using the same protocols.

Do GraphQL clients need to update?

No. GraphQL clients send requests to the same endpoint and receive responses in the same format. The router swap is transparent to client applications.

What about custom directives?

All core Federation v1 and v2 directives are fully supported. Custom directives outside the Federation specification are stripped during composition by default. To preserve a custom directive in the supergraph, first import it with @link in your subgraph schema, then annotate it with @composeDirective.

Can I migrate gradually rather than all at once?

Yes. Deploy Cosmo Router alongside Apollo Router and use your load balancer to split traffic. Gradually increase the Cosmo Router percentage, then roll back instantly if needed.

Replace Apollo Router with Cosmo Router | WunderGraph Cosmo

Q: Do I need to complete the GraphOS migration first?

The one-click GraphOS migration is the easiest path. After migration, fetch the router config with npx wgc federated-graph fetch . Manual Cosmo setup is also supported if you prefer not to use the migration tool.

The problem

Router migration feels too risky to attempt

Compatibility unknowns, potential subgraph changes, and client coordination all add up to a project that seems harder than it is.

Directive compatibility is unknown before you commit

Teams cannot risk a router swap if they are unsure whether Federation v1 and v2 directives behave the same way. Uncertainty about compatibility blocks migration planning entirely.

Subgraph modification risk is too high

If the new router requires changes to subgraph schemas or resolvers, the migration scope expands from a router deployment into a multi-team schema rewrite.

Client-side changes cannot be coordinated across consumers

Changing how GraphQL clients connect to the router requires coordinating updates across every consumer of the API. Teams need the router swap to be transparent to clients.

Our solution

A drop-in replacement for Apollo Router

Cosmo Router implements the Federation specification and supports the same directives as Apollo Router. After migrating your graph configuration, fetch the router config from Cosmo and deploy. No subgraph code changes, no client updates.

From Apollo Router to Cosmo Router

Complete the Apollo GraphOS graph migration (or set up Cosmo manually).
Deploy Cosmo Router using the router config available in Cosmo after migration. Fetch it with: npx wgc federated-graph fetch <graph-name>.
Update your load balancer or API gateway to route traffic to Cosmo Router.
Cosmo Router handles query planning, subgraph orchestration, and response aggregation.
No changes are required in your subgraphs or GraphQL clients. For a detailed breakdown of how Cosmo handles Apollo Router compatibility, see the compatibility post.
Access Cosmo Studio immediately for observability, analytics, and schema management.

Deploy once. Existing subgraphs and clients keep working.

Apollo Router Migration

Before & After

Before Cosmo	With Cosmo
Concerns about Federation directive compatibility	Full support for Federation v1 and v2 directives
Manual router configuration required	Router config available in Cosmo after migration — fetch with npx wgc federated-graph fetch <graph-name>
Subgraph modification risk	Zero subgraph changes required
Client updates needed after router swap	Clients continue working without changes

Immediate gains

Cosmo Studio from day one

Advanced observability: Real-time metrics, request tracing, and schema analytics are available in Cosmo Studio the moment the router is live.
Schema management: Manage subgraphs, view composition results, and track schema changes across all environments from a single interface.

How Apollo Router migration works

01

Router config available immediately.

Migrate

Use the Apollo GraphOS migration tool to bring your graph configuration into Cosmo. After migration, fetch the router config with npx wgc federated-graph fetch <graph-name>. Manual Cosmo setup is also supported.

02

Any container platform.

Deploy

Deploy Cosmo Router to your infrastructure using the router config fetched with npx wgc federated-graph fetch <graph-name>. The router runs as a binary, in Docker, or on Kubernetes. Subgraph endpoints do not change.

03

Compatible query execution.

Route

Update your load balancer or API gateway to direct GraphQL traffic to Cosmo Router. The router handles query planning and subgraph orchestration compatibly with Apollo Router behavior.

04

Observability from day one.

Monitor

Access Cosmo Studio for real-time observability, schema analytics, and federated graph management. These capabilities are available from the moment the router is live.

What's included

Everything you need for the router swap

Available on Free, Pro, and Enterprise.

Federation v1 and v2 support

All standard Federation v1 and v2 directives through version 2.5 are supported. Existing subgraph schemas work without modification.

Router config ready after migration

After migration, fetch the router config with npx wgc federated-graph fetch <graph-name>. No manual configuration is needed.

Zero subgraph changes

Cosmo Router communicates with subgraphs using the same HTTP/GraphQL protocols as Apollo Router. Existing subgraph code, resolvers, and schemas need no changes.

Client compatibility

GraphQL clients continue working after the router swap. The router endpoint and response format remain compatible, so no client-side updates are required.

Switch to Cosmo Router today

Migrate your graph from Apollo GraphOS, fetch the router config, and deploy Cosmo Router.

Start Free Read the Docs

Replace Apollo Router with Cosmo Router, no subgraph changes required