OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

GraphQL Libraries

This suite of libraries enables seamless GraphQL integration, transforming your ContractSpecs into a type-safe Pothos schema, connecting with Prisma, and enabling Apollo Federation.

Libraries

@contractspec/lib.graphql-core

The foundation. Provides a configured Pothos builder, common scalars (JSON, DateTime), and utilities for mapping ContractSpec I/O to Pothos types.

@contractspec/lib.graphql-prisma

Connects Pothos to Prisma. Automatically generates GraphQL types from your Prisma schema and optimizes queries to prevent N+1 issues.

@contractspec/lib.graphql-federation

Adds Apollo Federation V2 support. Allows your subgraph to define keys and entities, making it ready for a supergraph.

Installation

bun add @contractspec/lib.graphql-core @contractspec/lib.graphql-prisma @contractspec/lib.graphql-federation

Usage: Building a Schema

Here's how to assemble a federated GraphQL schema from your specs:

import { builder } from '@contractspec/lib.graphql-core';
import { registerContractsOnBuilder } from '@contractspec/lib.contracts-runtime-server-graphql/graphql-pothos';
import { OperationSpecRegistry } from '@contractspec/lib.contracts-spec';
import { MySpecs } from './specs';

// 1. Register contracts
const registry = new OperationSpecRegistry();
registry.register(MySpecs);

// 2. Mount specs onto Pothos builder
registerContractsOnBuilder(builder, registry);

// 3. Build and print schema
const schema = builder.toSchema();
console.log(printSchema(schema));

Features

  • Code-First: Define schema in TypeScript (Pothos), get SDL as artifact.
  • Spec Integration: `registerContractsOnBuilder` automatically converts Command/Query specs into Mutations/Queries.
  • Federation Ready: Just add `provider: 'federation'` to your config.
Next: Data & Backend Back to Libraries