The Rover dev command
Query a locally federated GraphQL API
⚠️ Do not run rover dev
in production! This command is for local development only.
A subgraph is a graph that contributes to the composition of a federated supergraph:
You can use Rover to start a local router that can query across one or more running GraphQL APIs (i.e., subgraphs) through one endpoint. As you add, edit, and remove subgraphs, Rover automatically composes their separate schemas into a unified supergraph schema that the router reloads and serves.
Think plug-n-play USB devices but with your GraphQL APIs!
Creating a federated session
Starting the session
Before using rover dev
, you need at least one running GraphQL API (subgraph). You'll need the URL the GraphQL API is serving, along with the location of its schema in your filesystem.
If you don't have a local schema file, your subgraph must enable introspection.
Here's an example rover dev
command that provides a locally running subgraph:
rover dev --name products --schema ./products.graphql --url http://localhost:4000
This starts the rover dev
session, which watches ./products.graphql
for changes to the schema. It also starts up a local Apollo Router instance at its default endpoint (http://localhost:3000
). Finally, the session listens for other rover dev
processes that include different subgraph schemas.
Stopping the session
If you stop the first rover dev
session (by pressing CTRL+C
), it shuts down the local router instance. It also detaches and shuts down any secondary rover dev
processes.
Attaching additional subgraphs to a session
To add a new GraphQL API (i.e., subgraph) to a session, run rover dev
in a new terminal with the necessary arguments for that new subgraph. If a session is already running, Rover automatically attaches subsequent rover dev
processes to that existing session.
When you add a new subgraph to a session, Rover handles recomposing the supergraph schema and printing the build result in the outputs of both the primary process and the attached process.
Triggering recomposition on subgraph changes
Each rover dev
process is responsible for monitoring any changes to its subgraph schema.
Via filesystem update (recommended)
If you pass the --schema <PATH>
argument, rover dev
watches that schema file for changes and reports any updates to the main rover dev
process if a schema's contents change.
Via introspection
If you don't pass the --schema <PATH>
argument, rover dev
introspects the URL specified by the --url <SUBGRAPH_URL>
argument once every second. The command prefers to use the same query as rover subgraph introspect
but it falls back to rover graph introspect
if your GraphQL API doesn't support introspecting federated SDL. If this is the case, directives are stripped from the subgraph schema.
Stopping an attached process
If you stop an attached rover dev
process (by pressing CTRL+C
), the supergraph will recompose its schema without the removed subgraph and reload the router.
Health check
By deafult, the 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.
Advanced configuration
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
.
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
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_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 router 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.