Mastering Local Development for GraphQL Federation

A Step-by-Step Guide to Running and Enhancing Your Federated Graph for Rapid Development.


In development, you aim to test your schema changes as quickly as possible, bypassing the need to check and update your federated graph on the control plane. This approach does not replace the necessity of pushing your subgraph to the control plane in production; however, it serves as a more expedient method for iterating on your graph during the development phase.

If you want to start your router in production with a static config please use the fetch command instead. This will fetch the latest valid production config from the control plane. wgc router compose should only be used for local development.


  1. Install the latest wgc

  2. Download and extract the latest router here

Getting started

1. Add your subgraphs

In order to compose locally, we need to create a compose.yaml file that includes all the subgraphs you wish to include and compose into a federated graph. The information you are required to provide is as follows:

version: 1
  - name: subgraph-a
    routing_url: http://localhost:4001/graphql
    # a) Specify a schema to introspect by file OR
      file: ../schemas/subgraph-a.graphqls
  - name: subgraph-b
    routing_url: http://localhost:4002/graphql
    # b) Specify introspection to introspect on a running subgraph
      url: http://localhost:4002/graphql
        Authorization: 'Bearer YOUR_TOKEN_HERE'


The unique name of the subgraph



The unique url (endpoint) of the subgraph (typically ends with /graphql)



Required if you want to dynamically introspect a running subgraph server



Headers to pass on the introspection request



Path to the subgraph GraphQL schema


2. Generate the Router config

After you have configured everything, you can generate the static router config as follows:

wgc router compose -i compose.yaml -o config.json

This command introspects all your subgraphs and produces a config.json that can be passed to the router in the next step.

3. Run the config with the router

Create a config.yaml file in the same directory as your router binary.

dev_mode: true
# Path to the previous generated file
router_config_path: config.json
   # Result of `wgc router token create`. Can be omitted for local testing.
   token: ""

If you omit the token, analytics and tracing are disabled. For production create a token wgc router token create and use polling instead. This ensures that the latest valid config is deployed to your routers automatically.

4. Open the playground

Finally, run the router and go to localhost:3002 . You will see a playground and you're ready to test your changes.


Last updated