8. A stub subgraph


In this lesson, we will:

  • Set up and publish a stub
  • Set up our local development environment

✏️ Setting up the accounts stub subgraph

Each we create will be located in its own folder prefixed with subgraph-. We can see that there's already a folder in the starter repo called subgraph-template. This subgraph-template folder contains all of the files you'll need to set up an with boilerplate code!

📂 subgraph-template
┣ 📂 datasources
┣ 📄 index.js
┣ 📄 package.json
┣ 📄 resolvers.js
┗ 📄 schema.graphql

This template contains a stub subgraph: an empty equipped with the bare minimum needed to get it up and running.

Let's take a peek at the schema.graphql file.

extend schema
url: "https://specs.apollo.dev/federation/v2.7"
import: ["@key", "@shareable", "@inaccessible"]
type Query {
_todo: String @shareable @inaccessible

We can see the federation definition at the top, along with 2 new : @shareable and @inaccessible. Both of these enable us to add an arbitrary (Query._todo). This won't be available for (it's @inaccessible!) and it can be defined in other (it's @shareable). This barebones schema lets us spin up as many stub as we need to; but let's start with one for now.

  1. Duplicate the subgraph-template folder in the root of the repo and rename the folder to subgraph-accounts.

  2. Open up the index.js file. We'll need to fill in the port and subgraphName .

    The accounts should be running on port 4002.

    const port = 4002;
    const subgraphName = "accounts";

    We'll fill in the last TODO for dataSources later on!

  3. In a new terminal, navigate to the subgraph-accounts directory.

    cd subgraph-accounts
  4. Install the packages.

    npm install
  5. Run the server using npm start.

    npm start

You should now be able to for the following using Sandbox at http://localhost:4002.

query {
_todo # returns "TODO". This field will be inaccessible from the router

Publishing the accounts stub subgraph

Starting with an empty stub enables us to start fresh and catch any errors as we migrate our .

Note: This is also a good time to set up and deployment in your 's CI/CD piplines. We'll tackle those in Voyage III.

To publish our accounts , we'll use the rover subgraph publish command with the corresponding values. Since this is the first time we're publishing the accounts , we'll also need to add a routing-url. (Our is running locally, so make sure you specify http and not https!)

rover subgraph publish <APOLLO_GRAPH_REF> \
--schema ./subgraph-accounts/schema.graphql \
--name accounts \
--routing-url http://localhost:4002

Remember to replace the <APOLLO_GRAPH_REF> value with your own, and take note that we're running this command in the root directory of our project.

With a successful publish, we can head over to the Subgraphs page in Studio and see our new accounts . The is growing!

Studio Subgraphs page showing the accounts subgraph added to the list


Setting up the local supergraph development environment

Now that we have two in the mix, we'll need a way to see the results of our schema changes locally as we migrate , catching any errors as we go along. provides a development tool with called rover dev that helps us do just that.

We'll provide rover dev with all the details of our configuration (all the details for each such as its name, schema, and where it's running) as well as our configuration (like which headers should be propagated). Both of these configurations can be found in the router directory, in supergraph-config.yaml and router-config.yaml respectively. Feel free to take a peek!

Note: Before you start, make sure both the monolith and accounts are running, along with the services (npm run launch in the monolith directory).

  1. If your is still running, stop it now.

  2. Open up a new terminal window at the root of the server directory.

  3. Run the rover dev command, passing in the config files.

    rover dev --supergraph-config ./router/supergraph-config.yaml \
    --router-config ./router/router-config.yaml
  4. We'll get a few lines of output in the terminal:

    ⚠️ Do not run this command in production! ⚠️ It is intended for local development.
    🛫 starting a session with the 'monolith' subgraph
    🛫 starting a session with the 'accounts' subgraph
    🎶 composing supergraph with Federation v2.8.0
    🚀 your supergraph is running! head to http://localhost:4000 to query your supergraph
    👀 watching ./monolith/schema.graphql for changes
    🎶 composing supergraph with Federation v2.8.0
    ✅ successfully composed after adding the 'accounts' subgraph
    👀 watching ./subgraph-accounts/schema.graphql for changes

has spun up a local for us running on localhost:4000, pulling in our local schemas.

Note that this is different from the "production" we ran earlier in the course, which was pulling in the schemas hosted in identified by the .

We've got our local development set up; let's keep going with the implementation plan!

What's in the accounts subgraph?

The accounts will be responsible for all things related to accounts and users, login details, and user profiles.

Take a few moments to review the monolith/schema.graphql file and answer the following questions:

  • Which entities belong in the accounts ?
  • Which in these entities belong in the accounts ?
  • Which in the Query and Mutation types belong in the accounts ?

When you're ready with your list, compare it with ours!

Here's a list of types and their corresponding that would be appropriate for the accounts to handle:

Diagram to display the fields above
  • User interface with id, name, profilePicture
  • Host type with id, name, profilePicture and profileDescription
  • Guest type with id, name, profilePicture
  • Query.user
  • Query.me
  • Mutation.updateProfile
  • The types used by the updateProfile : UpdateProfileInput, UpdateProfileResponse and MutationResponse


Which of the following does rover dev not do?

Key takeaways

  • A stub is an empty subgraph equipped with the bare minimum needed to get it up and running. It enables us to start with a clean state, set up any CI/CD pipelines with and approach schema migration incrementally.
  • rover dev helps us with local development by composing our locally and spinning up a .

Up next

We're ready to start migration! Let's learn about the @override to help us make this migration go smoothly.


Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.