Hive Gateway: Local Subgraph Development Just Got Easier

Imagine you’re adding a field to your subgraph and wiring it into your frontend. The resolver may be a ten line change, but verifying it across your stack is not. The subgraph needs to be composed into the supergraph and served by the gateway along with the other subgraphs.

Hive Gateway now has a supergraph source built for exactly this loop. Tell the gateway which subgraphs are running locally, and the gateway composes them with the rest of your graph and serves the result. No other commands or processes required.

The loop today

Federated teams usually end up with one of the following setups for local development:

• Run everything. Clone every subgraph, start them all, introspect them, compose, then start the gateway. It works, but it’s heavy, and the copies of the subgraphs you did not touch drift away from what is deployed the moment changes get pushed.
• Use hive dev. The Hive CLI takes the schema that is published to a target, adds or replaces your local subgraph, composes, and writes a supergraph.graphql file that a local gateway can watch. This is much lighter, because the registry already knows every other subgraph. But it is still a second process you have to remember to start, with a file in between.
• Rely on a deployed environment. Subgraphs are valid GraphQL servers on their own, so many changes can be tested without a gateway at all. But federation directives like @key and @requires only show their effect once composed, and the frontend cannot be tested against the change until it is published.

A dev supergraph source

The new source folds the hive dev process into the gateway, so testing new features locally becomes a single step. Configure it in your gateway.config.ts or straight from the CLI.

import { defineConfig } from '@graphql-hive/gateway'

export const gatewayConfig = defineConfig({
  supergraph: {
    type: 'dev',
    services: [
      // the subgraph you are working on, running on your machine
      { name: 'products', url: 'http://localhost:4001/graphql' }
    ],
    // compose through the Hive registry with the rest of the graph.
    // token is required when remote is enabled; registry defaults to Hive Cloud
    remote: true,
    token: '<registry access token>',
    target: {
      bySelector: {
        organizationSlug: 'my-org',
        projectSlug: 'my-project',
        targetSlug: 'staging'
      }
    }
  }
})

hive-gateway supergraph \
  --dev-service products=http://localhost:4001/graphql \
  --dev-remote \
  --hive-target my-org/my-project/staging \
  --hive-access-token "$HIVE_ACCESS_TOKEN"

On start, the gateway fetches the SDL of each listed service, composes a supergraph, and serves it. On every polling interval it fetches the SDLs again and recomposes only when one of them changed, so you can leave it running while you edit resolvers and schema. Save the change, and the next poll picks it up.

Each service can provide its schema in the way that suits it:

• federation (the default) queries the subgraph’s _service { sdl } field.
• graphql runs a standard introspection query, for services that are not federation aware.
• file reads an SDL file from disk. The url is still where the gateway will route requests, but the schema comes from the file, which means you can compose a schema before a single resolver exists.

Compose locally, or through the registry

The remote flag is the interesting part, and it is where Hive’s view of schema governance shows up in a local development feature.

Without remote, the gateway composes the listed services and nothing else, entirely on your machine. It is instant, it works offline, and it is a good fit for prototyping or for the case where you really do have several subgraphs running locally and want them composed together.

With remote, the gateway sends the SDLs of your local services to the Hive registry, which composes them with the latest composable schema version published to the target you point at. Your local products replaces the registry’s products; every other subgraph comes from the registry as it was last published. You only run what you are changing.

So which one? Use remote composition when:

• your graph is published to a Hive target and you want the result to match what schema checks and production will see
• you want to run only the services you are changing, with everything else taken from the registry as last published
• unrelated subgraphs should always be their latest published versions, so schema drift shows up while you are still editing, not after you open the pull request

Use local composition when:

• you are offline or prototyping without a registry
• every subgraph you need is already running locally
• you want the fastest possible feedback loop

One difference matters more than it looks: the composition engine. Composition is a strict process with a lot of rules, and those rules evolve. If every developer composes on their own machine, every developer is running their own version of the composer. When the registry composes, the same engine that validates the pull request and the production deploy validates your work locally. What composes on your laptop composes in CI.

Our recommendation is simple: use remote whenever you have a registry. Keep local composition for offline work and quick experiments.

Why this is a full-stack feature

The people who feel this the most are not the ones who only own a subgraph. They are the ones who change a subgraph and the client that consumes it in the same afternoon.

With the dev source, the frontend talks to a local gateway serving your modified graph. Code generation can run against the composed schema, so the new field shows up in your generated types. The query your UI actually sends goes through the real query planner, hits your local subgraph for the replaced service, and hits the rest of the graph as published. When you’re done, nothing about your workflow changes: you open the pull request, hive schema:check runs against the same registry, and the same composition engine gives the same answer it gave your gateway all afternoon.

Governance does not stop at the laptop

In Hive, the schema registry is the single source of truth for a graph. Schema checks with usage-based breaking change detection, contracts, versioned history, promotions and rollbacks all build on it. A local development tool that composes possibly stale graphs would contradict that.

The dev source in remote mode means the registry does the composing, using the schema versions it holds and the same engine it will use for your pull request. The gateway contributes only the subgraphs running on your machine. The loop gets shorter, and the guarantees stay in place.

Try it

The dev supergraph source is available in Hive Gateway today. The documentation covers the configuration options, the CLI flags and environment variables, and how each service source resolves its schema.