Extensions

Graffle's extension system allows you to customize and enhance your GraphQL client with powerful, composable features. All extensions listed below are first-party and ship with the graffle package.

Document Building

Document Builder

Build type-safe GraphQL documents using TypeScript instead of GQL syntax. Includes tailored methods for root fields, batch operations, and static document generation for use with other GraphQL clients.

Key Features:

• Type-safe document construction
• Automatic result type inference
• Static document builder (compile-time, no runtime client needed)
• Variable extraction with $var markers
• Full support for aliases, arguments, and nested selections

Schema Design Patterns

Schema Errors

First-class support for schemas that encode errors into their design using union types. Result fields can be made to throw on errors or automatically map to error classes.

Key Features:

• Automatic __typename injection
• Type-safe error handling with isError helper
• Configurable error object detection
• Automatic message field querying from error interfaces

Transport

Transport HTTP

HTTP transport implementing the GraphQL Over HTTP specification. Included in minimal and basic presets.

Key Features:

• GET and POST method modes
• Relative URL support (browser and frameworks)
• Configurable headers and fetch options
• Anyware hooks for request/response manipulation

Transport Memory

In-memory transport for executing documents against local GraphQL schemas. Invokes execute from the graphql package directly.

Key Features:

• Zero network overhead
• Perfect for testing and development
• Works with any GraphQLSchema instance

Developer Experience

Introspection

Adds an introspect method to conveniently introspect the schema programmatically.

Key Features:

• Simple schema introspection
• Returns standard GraphQL introspection query result

Throws

Decorates the client with a .throws() method for adjusting output to throw on any error encountered. Convenient for specific use cases without changing your base configuration.

Key Features:

• Chain .throws() on any query or mutation
• Automatically configures error handling to throw mode
• Cleaner alternative to verbose with({ output: ... }) calls

File Operations

Upload

Adds support for the GraphQL Multipart Request specification, enabling file uploads via GraphQL.

Key Features:

• Spec-compliant file upload implementation
• Works with any GraphQL server supporting multipart requests

Observability

OpenTelemetry

Instruments GraphQL requests with OpenTelemetry tracing. Creates spans for the entire request lifecycle and each hook.

Key Features:

• Request-level spans
• Per-hook span tracking (encode, pack, exchange, unpack, decode)
• Configurable tracer name
• Works with standard OpenTelemetry ecosystem

Note: Use this extension before all others to ensure complete span coverage.

Planned Features

The following extensions and features are under consideration or in development:

Feature	Description	Tracking
Incremental Delivery (@defer/@stream)	Support for the experimental @defer and @stream directives to enable incremental delivery of GraphQL responses.	#1134
gql.tada Integration	Automatic integration with gql.tada for type-safe GraphQL documents using standard GQL syntax alongside Graffle's document builder.	#1273
Logger Extension	Built-in logging extension for debugging and monitoring GraphQL operations.	#1123
Request Batching	Automatic batching of multiple GraphQL requests into a single network call.	#1017

Creating Extensions

To learn how to create your own extensions, see the Extension Development Guide.