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:
While you're making local changes to an individual subgraph, you can use the
rover dev command to start a local router instance and test out the effects of those changes on your entire supergraph.
Whenever you add, modify, or remove a subgraph from your local supergraph, Rover automatically re-composes your individual subgraph schemas into a unified supergraph schema, which your local router session automatically begins using.
rover dev, you need at least one running GraphQL API (subgraph). Rover can obtain a subgraph's schema via introspection (either standard or federated introspection), or you can provide a local schema file.
Here's an example
rover dev command that points to a locally running subgraph and provides its schema via a local file:
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 subgraphs, which is helpful for testing local changes against your staging subgraphs.
When you start your first
rover dev process:
- Rover obtains the subgraph schema you provide (via either introspection or file path).
- Rover composes a supergraph schema from the subgraph schema.
- Rover starts a locally running router session and provides it the supergraph schema.
- Rover starts watching the provided subgraph schema for changes (via either introspection or file), and it recomposes the supergraph schema whenever it detects a change. This automatically reloads the router.
After you start a local router session with your first
rover dev process, you can run additional
rover dev processes to add subgraphs to the session.
If you have a standard set of subgraphs that you're always developing with, you can create a supergraph config file to add all of them to your local router session with a single
rover dev command.
For example, this
supergraph.yaml file provides the necessary details for two subgraphs:
federation_version: =2.4.7subgraphs:products:routing_url: http://localhost:4000schema:file: ./products.graphql # Schema provided via filereviews:schema:subgraph_url: http://localhost:4001 # Schema provided via introspection, routing_url can be omittedusers:# routing_url: <Optional, pulled from GraphOS registry by default>schema: # Schema downloaded from GraphOS registry, does not poll for updatesgraphref: mygraph@currentsubgraph: actors
You provide this file to
rover dev like so:
rover dev --supergraph-config supergraph.yaml
If you do, a router session starts with one of the subgraphs listed, then adds the remaining subgraphs one at a time (order is undefined). Because of this, you might observe composition errors during intermediate steps.
supergraph.yaml file also enables you to take advantage of other config options, such as
If you start your session with a config file, you can still add other subgraphs individually. However, you can't provide another config file.
After you start a router session with your first
rover dev command, you can then add other subgraphs to that same session.
To add a subgraph, open a new terminal window and run
rover dev again, this time providing the details of the subgraph to add. For example, this command adds a
rover dev --name users --url http://localhost:4002
Rover detects your existing session and attaches this new process to it.
When you add a new subgraph to a session, Rover recomposes the supergraph schema and updates the router so you can query all added subgraphs via the single router endpoint.
⚠️ Rover uses the port of the running router to identify an existing session. If you specify a custom port via
--router-config, make sure to specify the same port for all
rover dev processes that you want to attach to the same session.
If you stop your initial
rover dev process (by pressing
CTRL+C), it shuts down the local router session. This also shuts down any secondary
rover dev processes attached to that same session.
If you stop a secondary
rover dev process (by pressing
CTRL+C), its associated router session recomposes its supergraph schema without the corresponding subgraph and reloads the router.
By default, the router's health check endpoint is disabled in
rover dev. You can enable it again by enabling it in a router configuration YAML file and passing it to
rover dev via the
--router-config argument described in the following section.
To configure advanced router functionality like CORS settings or header passthrough for subgraphs, you can pass a valid router configuration YAML file to
rover dev via the
--router-config <ROUTER_CONFIG_PATH> argument.
Note that only the main
rover dev process uses this router 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-address, and/or pass the same router configuration file path via
If you want to use enterprise router features, you must provide both:
- A graph ref via the
- A graph API key either via the
APOLLO_KEYenvironment or by configuring credentials in Rover.
The first time you use Federation 2 composition on a particular machine, Rover prompts you to accept the terms and conditions of the ELv2 license. On future invocations, Rover 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.
rover dev will select a recent version of the router and composition to use for you. You can override these by setting the environment variables
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 router with a major version of 1. If you already have the plugins installed, you can pass
rover dev in order to keep the plugins at the same version.