GraphQL Fusion

Overview

Suite Framework uses Hot Chocolate Fusion as its standard for GraphQL federation.

Hot Chocolate Fusion is a GraphQL federation system that allows multiple independent GraphQL services (subgraphs) to be composed into a single unified GraphQL gateway.

Each service exposes its own schema, which is packaged and combined during build time to produce a single gateway schema that clients can query as if it were one API.

Why Fusion?

Suite Framework previously used schema stitching to aggregate multiple GraphQL services into a single gateway. While functional, schema stitching is a manual approach — gateways need explicit knowledge of each downstream service's schema, and keeping them in sync as services evolve adds ongoing maintenance overhead.

Hot Chocolate Fusion is the successor to schema stitching and the standard federation approach going forward in the Hot Chocolate ecosystem. The key improvements over stitching are:

Build-time composition instead of runtime stitching
With schema stitching, the gateway fetches and merges schemas from downstream services at startup. This means any schema incompatibility or misconfiguration is only discovered when the gateway boots — or worse, when a query hits it in production. Fusion moves composition entirely to build time: schemas are packaged, composed, and validated as part of the CI/CD pipeline via the Suite CLI, before anything is deployed.

Schema errors caught before deployment
Because composition happens at build time, conflicts between subgraph schemas — such as type mismatches, naming collisions, or missing fields — are surfaced as CLI errors during the build. This shifts schema validation left, making issues visible to developers immediately rather than as runtime failures.

Stateless gateway
A Fusion gateway does not need to fetch schemas from downstream services at runtime to build its schema. The composed gateway package is self-contained, which simplifies deployment, improves startup time, and removes a class of runtime dependencies that could cause the gateway to fail independently of the underlying services being healthy.

Stitching is no longer actively maintained
The Hot Chocolate team has shifted focus to Fusion as the long-term federation solution. Schema stitching remains available but receives no new features and will eventually be removed. Adopting Fusion ensures Suite stays aligned with the supported path of the ecosystem.

Migrating an existing stitched gateway to Fusion? See Migrating from Schema Stitching.

Key Concepts

Term	Description
Subgraph	A backend service that exposes a GraphQL schema and is published to one or more BFFs.
BFF (Gateway)	A composed gateway that aggregates multiple subgraph schemas into a single endpoint.
Fusion Package (.fsp)	A binary artifact generated per subgraph, consumed during BFF composition.
Schema Composition	The build-time process of merging all subgraph packages into a BFF gateway package.

Fusion Architecture

graph TD
    A[Subgraph A]
    B[Subgraph B]
    C[Subgraph C]

    A --> D[Fusion Composition]
    B --> D
    C --> D

    D --> E[BFF Gateway]
    E --> F[Clients]

Suite CLI Commands

In Suite Framework, Fusion workflows are managed through the Suite CLI, which provides commands for configuring services, packaging subgraphs, and composing gateways.

The following suite graphql commands drive the Fusion workflow:

Command	Description
suite graphql config	Configures subgraph metadata (name, HTTP endpoint) for a backend service.
suite graphql schema	Generates the GraphQL schema and packages it for each target BFF.
suite graphql compose	Composes the BFF gateway package from all its subgraph packages.

For a full end-to-end walkthrough, see How It Works.
For CLI reference, see CLI Usage.