Links

Mastering Local Development for GraphQL Federation

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

Overview

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.

Prerequisites

  1. 1.
    Install the latest wgc
  2. 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:
compose.yaml
version: 1
subgraphs:
- name: subgraph-a
routing_url: http://localhost:4001/graphql
# a) Specify a schema to introspect by file OR
schema:
file: ../schemas/subgraph-a.graphqls
- name: subgraph-b
routing_url: http://localhost:4002/graphql
# b) Specify introspection to introspect on a running subgraph
introspection:
url: http://localhost:4002/graphql
headers:
Authorization: 'Bearer YOUR_TOKEN_HERE'
Property
Description
Required
name
The unique name of the subgraph
true
routing_url
The unique url (endpoint) of the subgraph (typically ends with /graphql)
true
introspection.url
Required if you want to dynamically introspect a running subgraph server
false
introspection.headers
Headers to pass on the introspection request
false
schema.file
Path to the subgraph GraphQL schema
false

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.
config.yaml
dev_mode: true
# Path to the previous generated file
router_config_path: config.json
graph:
# 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.
./router