apollographql / hack-the-supergraph

Hack the Supergraph - Example Fullstack Supergraph

This repository contains an example of a Fullstack Supergraph with GraphOS.

📖 Prerequisites

In order to run the project locally, you'll need node>=14 installed on your development machines.

🏃‍♂️🕐 Powered by GraphOS

GraphOS automatically provisions and hosts a serverless cloud router for this example. Clients query the router instead of individual subgraphs, which enables the router to automatically collect operation metrics and usage data that you can then visualize in Apollo Studio.

Create your free serverless cloud router with GraphOS by signing up for free here.

👩‍🚀🚀✨ Exploring the Supergraph with Explorer, our GraphQL IDE

GraphOS makes it possible to expose a public set of docs for your supergraph that anyone can use! Check out this supergraph's example and try running some queries.

You can create operation collections in the Apollo Studio Explorer, enabling you to save, organize, and share your frequently used GraphQL operations. There is an operation collection for the Website's grouped queries.

🌐 Using @defer in a React App hosted on Netlify

Deployed on Netlify, try @defer

This fullstack application contains a simple React app that utilizes @apollo/client to query GraphOS.

🖥️ Local development

If you would like to run the website locally, setup the website:

cd website
npm install

To start a local copy of the app on port 3000:

npm start

To debuge the instance, open VS Code and use the launch configuration available in the Debug panel:

code .

Subgraphs

All of the subgraph projects are located in the subgraphs folder. There are currently five subgraphs: orders, products, reviews, shipping, users. Each subgraph is currently built with @apollo/server and hosted on Railway

GitHub Actions

All of the subgraphs in this example have GitHub Action workflows to interact with GraphOS. We created separate workflows to isolate each subgraphs tests and deploys. It was easy enough to do this using paths for each subgrpah folder.

This README

We keep this repositories README in sync with GraphOS in case anyone visits our public Explorer referenced above. We are using the Rover CLI to do this in this example, but you can also using the public GraphOS Platform API if you want.

Schema Checks

Certain changes to your graph's schema (such as removing a field or type) might break one of your application's clients. GraphOS provides schema checks to help you identify breaking changes before you make them, and to help you identify when a potentially dangerous change won't break anything.

To try out schema checks on this repository:

1. Navigate to the products subgraph
2. Edit the file and remove the mediaUrl filed from the Product type
3. Create a new PR and commit
4. GitHub Actions will trigger in PR and fail due to schema checks

Deploying Subgraph changes with Launches

In GraphOS, a launch represents the complete process of making a set of updates to a supergraph, usually initiated by changes to one of its subgraphs.

For this example we've kept it simple and have the minimum of what you want, keeping the main branch of this repository in sync with the main variant in GraphOS. Each variant of a supergraph has its own subgraph schemas, supergraph schema, change history, and metrics. You might have a staging or pre-production environment and that's exactly what variants are for!

Deploy to Railway and GraphOS

You can easily deploy all of the subgraphs to Railway by clicking the button above—just configure your first subgraph with the repo you want to clone this to, and click into the rest to accept the defaults. Once all of the subgraphs are deployed, create a new supergraph in GraphOS pointing to the users subgraph, then add new subgraphs in this order:

1. reviews
2. products
3. orders
4. shipping

Once your last deploy finishes in Studio, you can test it out by running a query like this:

  fragment ProductFragment on Product {
    averageRating
    reviews {
      content
      rating
    }
  }
  query GetProductDetails {
    products {
      id
      title
      description
      mediaUrl
      ...ProductFragment @defer
    }
  }

hack-the-supergraph's Issues

Add numbers to steps in each subgraph

It's hard to explain to someone where I am in the instructions

For "I don't want to code path", remove modifying any schema

Also enable introspection on the subgraphs so they don't have to copy/paste

Michelle Fricton Log

start

• Location entity reference resolver was already there. The way the README was worded ("this is where we'll define...") made it seem like I was supposed to add it myself.
• There's also a bunch more things in the resolver that aren't present in the README code snippet. (sleep, name, etc)
• Specify "In a new terminal window..." for this instruction: Try running rover dev and use the server you have running locally:
• specify the url and subgraph name we want them to use (4001 and start)
• what query am I supposed to run in Sandbox? make it copy-pastable instead of just a screenshot
• I took a peek at the "I don't want to write code..." and it seems like they are also writing code?
• Got stuck at the step to create a supergraph - seeing the warning that is also in the screenshot but no way to move forward. Uploaded schema after some prompting from the group, but wouldn't have known to select "advanced options" to do this.

Add discord invite to start of hackathon

Finalize Complete branch

Add instructions on path/folder of where to run the command

Add prettier for markdown files

Minor thing, shall we add prettier for the markdown files, so we get consistent line length, formatting, and we also get formatting for the code snippets?

Include Learning Outcomes / Summary for each Substation on Main Readme

A suggestion, but for folks who are self-guiding (myself :D) and want to focus on specific topics, it would be useful if there was some sort of summary / learning outcomes for each substation to help navigate and keep things focused (studio & text editor).

Have a plan for if things don't work to keep things delightful

If setting up cloud routing doesn't work for someone, we should be able to reset expectations and keep them going on the right track without losing too much speed. :)

solar seas, i don't want to write code, put query at end of instructions

Since we are asking the user to rerun the query from the begining of the lesson, it would be helpful to put that query there for them to easily access and run

In Start, for both code and no code options, explicitly call out naming subgraph 'start'

Since solar-seas assumes a subgraph name of start for the initial subgraph, and to prevent especially no code participants from editing code, make explicit the instruction to name the initial monolith 'start'. Currently it is just implied in the screenshots.

Space Beach, I don't want to write code, explorer query fails

The Query provided in the instructions for this path fails when pasted into explorer without changes.

For existing studio accounts, have a path where they create a personal account

Add a note into start readme for getting setup with account

• SSO users have to create a personal account
• Existing account - upgrade path to free serverless tier
  • screenshots of workflow

Put together internal display/1-pager for prizes at each station - how attendees know what to get

Solar Seas, I don't want to write code, no completed schema

Seems we should have a schema_final.graphql (or something similar) in the solar-seas folder for the people who do not want to write code. Alternatively, provide what the solar-seas schema should look like (in whole) upon completion as part of this track so it can be easily copied into the schema file.

Space Beach, I don't want to write code missing image

At the end of the "I don't want to write code" path there is a placeholder, (gif of everything working) that should probably contain said gif

e-commerce schemas questions

I was looking at the schema for users and noticed some things that can be updated:

Cart:

type Cart {
  """
  Items saved in the cart session
  """
  items: [Product]

  """
  The current total of all the items in the cart, before taxes and shipping
  """
  subtotal: Float
}

I think we can change this to

type Cart {
  """
  Items saved in the cart session
  """
  items: [Product!]! # made this non nullable

  """
  The current total of all the items in the cart, before taxes and shipping
  """
  subtotal: Money! # made this money and non nullable (default could be 0 USD?)
}

OrderFilters

input OrderFilters {
  orderId: ID!
  priceHigh: Float
  priceLow: Float
  itemsInOrder: Int
}

is orderId non-nullable on purpose?

---

There's other places where we have nullable list of nullables, I can update those to non-nullable list of non-nullables if we prefer that approach :)

user and orders

Users shouldn't have orders inside this subgraph

"""
An user account in our system
"""
type User @key(fields: "id") {
  id: ID!

  """
  The users login username
  """
  username: String!

  """
  The user's active cart session. Once the cart items have been purchases, they transition to an Order
  """
  cart: Cart

  """
  The users previous purchases
  """
  orders(filters: OrderFilters): [Order]

Change "box" "artifact" to a very specific thing

Add screenshots

• Account sign-up section
• Screenshot for initial schema upload/pasting