Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio

The Rover dev command

Run your supergraph in your local dev environment

⚠️ Do not run rover dev in production! This command is for local development only.

A supergraph is an architecture consisting of multiple GraphQL APIs (subgraphs) and a graph router that runs in front of them:

Graph Router
Subgraph A
Subgraph B

While you're making local changes to an individual , you can use the rover dev command to start a local instance and test out the effects of those changes on your entire .

Whenever you add, modify, or remove a from your local , automatically re-composes your individual subgraph s into a unified supergraph schema, which your local session automatically begins using.

Starting a router session

To use rover dev, you need at least one running GraphQL API (subgraph). can obtain a 's via (either standard or federated introspection), or you can provide a local file.

Here's an example rover dev command that points to a locally running and provides its via a local file:

Example command
rover dev --name products --schema ./products.graphql --url http://localhost:4000

You don't have to provide a locally running subgraph! You can point to any GraphQL endpoint that your local environment can reach. You can even mix and match local and remote s, which is helpful for testing local changes against your staging subgraphs.

When you start your first rover dev process:

  1. obtains the you provide (via either or file path).
  2. composes a supergraph schema from the .
  3. starts a locally running router session and provides it the .
  4. starts watching the provided for changes (via either or file), and it recomposes the schema whenever it detects a change. This automatically reloads the .

After you start a local session with your first rover dev process, you can run additional rover dev processes to add subgraphs to the session.

Starting a session with multiple subgraphs

If you have a standard set of s that you're always developing with, you can create a supergraph config file to add all of them to your local session with a single rover dev command.

For example, this supergraph.yaml file provides the necessary details for two s:

federation_version: =2.4.7
routing_url: http://localhost:4000
file: ./products.graphql # Schema provided via file
subgraph_url: http://localhost:4001 # Schema provided via introspection, routing_url can be omitted
# routing_url: <Optional, pulled from GraphOS registry by default>
schema: # Schema downloaded from GraphOS registry, does not poll for updates
graphref: mygraph@current
subgraph: actors

You provide this file to rover dev like so:

rover dev --supergraph-config supergraph.yaml

If you do, a session starts with one of the s listed, then adds the remaining subgraphs one at a time (order is undefined). Because of this, you might observe composition errors during intermediate steps.

Providing a supergraph.yaml file also enables you to take advantage of other config options, such as introspection_headers.

If you start your session with a config file, you can still add other subgraphs individually. However, you can't provide another config file.

Adding a subgraph to a session

After you start a session with your first rover dev command, you can then add other s to that same session.

To add a , open a new terminal window and run rover dev again, this time providing the details of the to add. For example, this command adds a users :

rover dev --name users --url http://localhost:4002

detects your existing session and attaches this new process to it.

When you add a new to a session, recomposes the and updates the so you can query all added s via the single endpoint.

⚠️ Rover uses the port of the running router to identify an existing session. If you specify a custom port via --supergraph-port or --router-config, make sure to specify the same port for all rover dev processes that you want to attach to the same session.

Stopping a session

If you stop your initial rover dev process (by pressing CTRL+C), it shuts down the local session. This also shuts down any secondary rover dev processes attached to that same session.

Removing a subgraph

If you stop a secondary rover dev process (by pressing CTRL+C), its associated session recomposes its without the corresponding and reloads the .

Health check

By default, the 's health check endpoint is disabled in rover dev. You can enable it again by enabling it in a configuration YAML file and passing it to rover dev via the --router-config described in the following section.

Configuring the router

To configure advanced functionality like CORS settings or header passthrough for s, you can pass a valid router configuration YAML file to rover dev via the --router-config <ROUTER_CONFIG_PATH> .

Note that only the main rover dev process uses this configuration file when starting the router. If you specify a different listen address with supergraph.listen, all other rover dev processes need to pass the same values to --supergraph-port and --supergraph-address, and/or pass the same configuration file path via --router-config.

Enterprise features

If you want to use enterprise router features, you must provide both:

  1. A graph ref via the APOLLO_GRAPH_REF environment .
  2. A graph API key either via the APOLLO_KEY environment or by configuring credentials in .

Federation 2 ELv2 license

The first time you use Federation 2 composition on a particular machine, prompts you to accept the terms and conditions of the ELv2 license. On future invocations, remembers that you already accepted the license and doesn't prompt you again (even if you update Rover).

The ELv2-licensed plugins, supergraph (built from this source) and router (built from this source) are installed to ~/.rover/bin if you installed with the curl | sh installer, and to ./node_modules/.bin/ if you installed with npm.


By default, rover dev will select a recent version of the and composition to use for you. You can override these by setting the environment s APOLLO_ROVER_DEV_COMPOSITION_VERSION=2.0.0 and/or APOLLO_ROVER_DEV_ROUTER_VERSION=1.0.0. By default, rover dev will always use a composition library with a major version of 2, and a with a major version of 1. If you already have the plugins installed, you can pass --skip-update to rover dev in order to keep the plugins at the same version.

Edit on GitHubEditForumsDiscord