[graphql] Add @typespec/graphql emitter

[FionaBronwen]

Summary

This PR introduces @typespec/graphql, a new emitter that generates GraphQL SDL (Schema Definition Language) from TypeSpec definitions.

Features

• Schema generation: Emit complete GraphQL schemas from TypeSpec models and operations
• Operation types: Support for @query, @mutation, and @subscription decorators
• Interface composition: Use @graphqlInterface and @compose for GraphQL interface inheritance
  patterns
• Visibility filtering: Automatic input/output type generation based on @visibility decorators
• Custom scalars: @specifiedBy decorator for custom scalar URL specifications
• Schema customization: @schema decorator for multi-schema scenarios

Architecture

The emitter uses a two-phase approach:

1. Mutation phase: Transforms TypeSpec types into GraphQL-compatible structures using the mutator framework, handling visibility filtering, naming conventions, and type deduplication
2. Render phase: Uses @pinterest/alloy-graphql components to emit the final SDL output

Example

import "@typespec/graphql";

using TypeSpec.GraphQL;

@query
op getUser(id: string): User;

@mutation
op createUser(user: User): User;

model User {
  name: string;
  email: string;
}

Generates:

  type Query {
    getUser(id: String!): User!
  }

  type Mutation {
    createUser(user: UserInput!): User!
  }

  type User {
    name: String!
    email: String!
  }

  input UserInput {
    name: String!
    email: String!
  }

Test plan

• Unit tests for all decorators and components
• E2E tests covering schema generation scenarios
• Mutation engine tests for type transformation logic

Notes

• This emitter depends on @pinterest/alloy-graphql
• Tracked in GitHub issue GraphQL Emitter Design #4933

[timotheeguerin]

/azp run typespec - pr tools

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[Copilot]

Pull request overview

Introduces a new first-party TypeSpec emitter package, @typespec/graphql, that generates GraphQL SDL from TypeSpec programs, including a mutation-engine phase (naming, visibility filtering, input/output splitting) and an Alloy-based render phase. The PR also wires the emitter into the website documentation and the playground.

Changes:

• Add packages/graphql implementing the GraphQL emitter, decorators, validation, mutation engine, and Alloy SDL rendering.
• Add extensive unit/integration tests for decorators, mutation engine behavior, and component-level SDL rendering.
• Add docs + playground integration, and register new workspace dependencies (@pinterest/alloy-graphql, graphql).

Reviewed changes

Copilot reviewed 113 out of 115 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
website/src/content/docs/docs/emitters/graphql/reference/index.mdx	New GraphQL emitter reference landing page.
website/src/content/docs/docs/emitters/graphql/reference/emitter.md	Documents CLI/config usage and emitter options.
website/src/content/docs/docs/emitters/graphql/reference/data-types.md	Documents exported GraphQL-related TypeSpec types.
website/src/content/docs/docs/emitters/graphql/guide.md	New end-to-end usage guide and mapping examples.
website/src/content/current-sidebar.ts	Adds GraphQL docs entry to website sidebar.
pnpm-workspace.yaml	Adds catalog deps for alloy-graphql and graphql; minReleaseAge exclusion.
pnpm-lock.yaml	Locks new dependencies and adds packages/graphql importer.
packages/playground-website/tsconfig.json	Adds project reference to packages/graphql.
packages/playground-website/src/config.ts	Enables @typespec/graphql in playground libraries list.
packages/playground-website/samples/graphql.tsp	Adds a GraphQL sample TypeSpec program.
packages/playground-website/samples/build.js	Registers GraphQL sample in playground sample builder.
packages/playground-website/package.json	Adds @typespec/graphql dependency for playground.
packages/graphql/vitest.config.ts	Vitest config for JSX/alloy plugin + dependency dedupe.
packages/graphql/tsconfig.json	TypeScript project config for the new package.
packages/graphql/test/test-host.ts	Test harness for compiling/emitting GraphQL and parsing SDL.
packages/graphql/test/schema.test.ts	Unit tests for @schema decorator behavior.
packages/graphql/test/operation-kind.test.ts	Unit tests for @query/@mutation/@subscription operation kind.
packages/graphql/test/operation-fields.test.ts	Tests for @operationFields behavior and conflict diagnostics.
packages/graphql/test/mutation-engine/type-graph.test.ts	Tests for TypeGraph construction and navigation compatibility.
packages/graphql/test/mutation-engine/scalars.test.ts	Scalar mapping/sanitization + @specifiedBy tests.
packages/graphql/test/mutation-engine/print-type.test.ts	Tests GraphQL type string printing (nullability/list handling).
packages/graphql/test/mutation-engine/operations.test.ts	Operation naming + return-type nullability propagation tests.
packages/graphql/test/mutation-engine/naming-integration.test.ts	Integration tests for naming pipelines across kinds.
packages/graphql/test/mutation-engine/enums.test.ts	Enum + enum member mutation behavior tests.
packages/graphql/test/mutation-engine/context.test.ts	Tests for input/output context caching and propagation.
packages/graphql/test/main.tsp	Sample library schema TypeSpec used for testing/manual runs.
packages/graphql/test/lib/type-utils.test.ts	Unit tests for type/name utility helpers.
packages/graphql/test/lib/template-composition.test.ts	Unit tests for template-instance naming composition.
packages/graphql/test/lib/naming.test.ts	Unit tests for naming pipeline functions.
packages/graphql/test/interface.test.ts	Tests for interface markers and @compose validation.
packages/graphql/test/emitter.test.ts	E2E-ish tests for full SDL emission for common scenarios.
packages/graphql/test/e2e-manual/output/.gitignore	Ignores manual E2E output artifacts.
packages/graphql/test/crash-repro.test.ts	Regression tests for previously-crashing patterns (records, generics, unions).
packages/graphql/test/components/union-type.test.tsx	Component-level SDL rendering tests for unions.
packages/graphql/test/components/test-utils.tsx	Shared component test renderer to SDL string.
packages/graphql/test/components/scalar-type.test.tsx	Component-level SDL rendering tests for scalars.
packages/graphql/test/components/object-type.test.tsx	Component-level SDL rendering tests for object types.
packages/graphql/test/components/interface-type.test.tsx	Component-level SDL rendering tests for interface types.
packages/graphql/test/components/input-type.test.tsx	Component-level SDL rendering tests for input objects / @OneOf.
packages/graphql/test/components/enum-type.test.tsx	Component-level SDL rendering tests for enums.
packages/graphql/src/validate.ts	Adds GraphQL-specific validation hook for schemas/names/empties.
packages/graphql/src/type-usage.ts	Tracks type usage (input/output/query/mutation) + reachability.
packages/graphql/src/tsp-index.ts	Exposes decorators and validate hook for TypeSpec runtime.
packages/graphql/src/mutation-engine/type-graph.ts	Builds a self-contained namespace of mutated types for rendering.
packages/graphql/src/mutation-engine/schema-mutator.ts	Walks schema namespace, mutates types, builds TypeGraph, checks collisions.
packages/graphql/src/mutation-engine/print-type.ts	Converts mutated types into GraphQL type strings (nullability/list rules).
packages/graphql/src/mutation-engine/options.ts	Mutation options carrying GraphQL context, visibility, cache keys.
packages/graphql/src/mutation-engine/mutations/scalar.ts	Scalar mutation: mapping, sanitization, builtin collision warnings, @specifiedBy.
packages/graphql/src/mutation-engine/mutations/operation.ts	Operation mutation: naming + visibility + nullability propagation.
packages/graphql/src/mutation-engine/mutations/model.ts	Model mutation: naming, visibility filtering, record→scalar replacement, decorator arg remutation.
packages/graphql/src/mutation-engine/mutations/model-property.ts	Property mutation: naming + nullability/nullable-elements tagging.
packages/graphql/src/mutation-engine/mutations/index.ts	Barrel exports for mutation classes.
packages/graphql/src/mutation-engine/mutations/enum.ts	Enum mutation with member-edge handling + naming pipeline.
packages/graphql/src/mutation-engine/mutations/enum-member.ts	Enum member naming pipeline mutation.
packages/graphql/src/mutation-engine/mutations/union.ts	Union mutation: flattening/dedup, scalar wrapper models, input @oneOf conversion.
packages/graphql/src/mutation-engine/index.ts	Mutation-engine public entrypoints.
packages/graphql/src/mutation-engine/engine.ts	MutationEngine wiring + convenience mutation APIs.
packages/graphql/src/lib/visibility.ts	Defines visibility filters for query/mutation/output contexts.
packages/graphql/src/lib/utils.ts	Structural equality helpers for conflict detection (ops/models/props).
packages/graphql/src/lib/template-composition.ts	Template-instance name composition logic.
packages/graphql/src/lib/specified-by.ts	@specifiedBy decorator state + decorator implementation.
packages/graphql/src/lib/schema.ts	@schema decorator state + schema list helpers.
packages/graphql/src/lib/operation-kind.ts	@query/@mutation/@subscription decorator state + duplicate detection.
packages/graphql/src/lib/operation-fields.ts	@operationFields implementation + conflict/duplicate diagnostics.
packages/graphql/src/lib/one-of.ts	@oneOf marker decorator implementation/helpers.
packages/graphql/src/lib/nullable.ts	@nullable/@nullableElements marker decorators + helpers.
packages/graphql/src/lib/naming.ts	GraphQL naming pipelines (sanitize + casing + suffixes).
packages/graphql/src/lib/interface.ts	@graphqlInterface and @compose state + validation.
packages/graphql/src/lib/input-type.ts	Internal marker for identifying input types during render.
packages/graphql/src/lib/graphql-type-name.ts	Maps std scalars to GraphQL builtins and resolves type names.
packages/graphql/src/lib.ts	Library definition: diagnostics + emitter option schema.
packages/graphql/src/index.ts	Package exports (emitter, lib, decorators, mutation engine).
packages/graphql/src/emitter.tsx	Core emitter: schema selection, mutation, SDL render, emit files.
packages/graphql/src/context/index.ts	Context barrel exports for renderer.
packages/graphql/src/context/graphql-schema-context.tsx	Renderer context for passing TypeGraph into Alloy components.
packages/graphql/src/components/types/union-type.tsx	Alloy component for GraphQL unions.
packages/graphql/src/components/types/scalar-type.tsx	Alloy component for GraphQL scalars (+ specifiedBy).
packages/graphql/src/components/types/object-type.tsx	Alloy component for object types (+ interfaces, operation fields).
packages/graphql/src/components/types/interface-type.tsx	Alloy component for interface types.
packages/graphql/src/components/types/input-type.tsx	Alloy component for input object types (+ @OneOf).
packages/graphql/src/components/types/index.ts	Barrel exports for type components.
packages/graphql/src/components/types/enum-type.tsx	Alloy component for enums (+ descriptions/deprecation).
packages/graphql/src/components/schema.tsx	Top-level schema composition component (types + root ops).
packages/graphql/src/components/fields/operation-field.tsx	Alloy component for operation-as-field rendering incl. args/nullability/lists.
packages/graphql/src/components/fields/index.ts	Barrel exports for field components.
packages/graphql/src/components/fields/field.tsx	Alloy component for model property fields (input/output).
packages/graphql/package.json	New package manifest + scripts + deps/peers.
packages/graphql/lib/specified-by.tsp	TypeSpec extern decorator declaration for @specifiedBy.
packages/graphql/lib/schema.tsp	TypeSpec extern decorator declaration for @schema + SchemaOptions model.
packages/graphql/lib/scalars.tsp	Declares TypeSpec.GraphQL.ID scalar.
packages/graphql/lib/operation-kind.tsp	TypeSpec extern decorator declarations for query/mutation/subscription.
packages/graphql/lib/operation-fields.tsp	TypeSpec extern decorator declaration for @operationFields.
packages/graphql/lib/one-of.tsp	TypeSpec extern decorator declaration for @oneOf.
packages/graphql/lib/nullable.tsp	TypeSpec extern decorator declarations for nullability markers.
packages/graphql/lib/main.tsp	TypeSpec library entrypoint importing JS + decorator declarations.
packages/graphql/lib/interface.tsp	TypeSpec extern decorator declarations for @graphqlInterface and @compose.
packages/graphql/CHANGELOG.md	New changelog for initial release.
packages/graphql/api-extractor.json	Enables API extractor config for the new package.
cspell.yaml	Adds new words and ignores .claude/**.
.gitignore	Ignores local Claude settings file.
.github/CODEOWNERS	Adds CODEOWNERS entry for packages/graphql.
.chronus/changes/feature-graphql-2026-6-9-12-47-10.md	Adds Chronus changelog entry for the new emitter.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[timotheeguerin]

test @typespec-graphql-reviewers

[timotheeguerin]

test1 @typespec-graphql-reviewers/core
test @typespec-graphql-reviewers