The Rover dev Command
Run your supergraph in your local dev environment
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 the effects of subgraph 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 and provides it to your local router session.
rover dev
in production. It's for local development only.Starting a router session
To use 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
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, 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.
Starting a session with multiple subgraphs
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.7
subgraphs:
products:
routing_url: http://localhost:4000
schema:
file: ./products.graphql # Schema provided via file
reviews:
schema:
subgraph_url: http://localhost:4001 # Schema provided via introspection, routing_url can be omitted
users:
# 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 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.
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.
Starting a session from a GraphOS Studio variant
To start a local router instance using a GraphOS Studio variant, include the variant's graph ref with the --graph-ref
option like so:
rover dev --graph-ref docs-example-graph@current
When you include a graph ref, Rover uses the associated variant's subgraph routing URLs and schemas from Studio as the supergraph config. This information is stored in memory and not saved to disk. You can view a variant's subgraphs, including their routing URLs and schemas, on the variant's Subgraphs page in Studio.
Overriding variant subgraphs
While developing locally, you may want to override one or more subgraph(s) in your Studio variant with subgraphs from your local environment. You can do this by passing a supergraph config file alongside a graph ref. Any subgraphs defined in the supergraph config file override those from the graph ref.
For example, given a supergraph_override.yaml
file like this:
subgraphs:
products:
routing_url: http://localhost:4000
schema:
file: ./products.graphql
You can override a variant's published products
subgraph like so:
rover dev \
--graph-ref docs-example-graph@current \
--supergraph-config path/to/supergraph_override.yaml
This command overrides the variant's published products
subgraph in your local development session.
If the Studio variant doesn't include a products
subgraph, this command adds the subgraph and recomposes the supergraph schema.
Overriding federation versions
You can also use a supergraph config file to safely test a new federation version locally before putting it in production.
For example, given a federation_override.yaml
file like this:
federation_version: =2.4.7
You can override a variant's federation version like so:
rover dev \
--graph-ref docs-example-graph@current \
--supergraph-config federation_override.yaml
Adding a subgraph to a session
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 users
subgraph:
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.
--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 router 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 router session recomposes its supergraph schema without the corresponding subgraph and reloads the router.
Health check
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.
Configuring the router
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-port
and --supergraph-address
, and/or pass the same router configuration file path via --router-config
.
Enterprise features
If you want to use enterprise router features , you must provide both:
A graph ref via the
APOLLO_GRAPH_REF
environment variable.A graph API key either via the
APOLLO_KEY
environment or by configuring credentials in Rover.
Federation 2 ELv2 license
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.
Versioning
By default, rover dev
uses a recent version of the router and composition to use for you. This is currently configured in the Rover GitHub repo, however, you can override these by setting the environment variables 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 v2, and a router with a major version of v1. 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.