The Rover dev command
Query a locally federated GraphQL API
⚠️ Note: The
rover dev command is only for local development. Do not run this command in production.
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 (i.e., supergraph). 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!
Before using Rover's
dev command, you first need to have access to a running GraphQL API (subgraph). You'll need the URL the GraphQL API is serving and the location of the schema in the filesystem. If you don't have a local schema file, your subgraph must enable introspection.
rover dev command for running a local subgraph might look something like this:
rover dev --name products --schema ./products.graphql --url http://localhost:4000
The above command starts the
rover dev session, watching
./products.graphql for changes to the schema, and starts up a local Apollo Router at the default endpoint (i.e.,
http://localhost:3000). This session also listens for other
rover dev processes that include different subgraph schemas.
If you stop the first
rover dev session (by pressing
CTRL+C), it will shut down the router, and any attached
rover dev processes are detached and shut down.
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.
rover dev process is responsible for monitoring any changes to its subgraph schema.
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.
If you don't pass the
--schema <PATH> argument,
rover dev will introspect 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 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.
If you stop an attached
rover dev process (by pressing
CTRL+C), the supergraph will de-compose the removed subgraph and reload the router.
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.