Graffle
Graffle is a work in progress. Learn more.

Appearance

GraffleSimple GraphQL Client for JavaScript

Minimal. Extensible. Type Safe. Runs everywhere.

Guides
Examples
Extensions
Graffle
🧰

Extensible

Powerful type-safe extension system. Intercept and manipulate inputs, outputs, and core with hooks; Add new methods; And more.

📦

Ecosystem

Meet real-world project needs with extensions for common and niche needs like OpenTelemetry, file uploads, schema errors, and more.

🚛

Multi-Transport

Not just a great way to query GraphQL APIs. Execute documents against in-memory schemas just as easily with the same interface.

🧙

Custom Scalars

Easily add client-side codecs for custom scalars in the schema to enable automatic encoding of arguments and decoding of data on every request.

🪵

Document Builder

Optional TypeScript alternative to GQL syntax for building type-safe documents including tailored methods for root fields, batch method for multiple root fields, and a document method for 1:1 with GraphQL.

⛑️

Type Safe Results
( Document Builder )

Automatically inferred type safe results based on your document's structure including selection sets, aliases, directives, inline fragments, unions, and more.

🎲

Schema Errors
( Extension )

First class support for schemas that have modelled errors into their design. Result Fields can be made to throw on errors or automatically map to error classes.

📄

Static Document Builder

Generate typed GraphQL documents statically without a client instance. Perfect for passing to other GraphQL clients or building tools. Zero runtime overhead.

📮

Output Modes

Control error handling patterns with envelope mode (wrap results), return-error mode (errors as values), or throw mode. Configure globally or per-request.

🎭

Type-Safe Native GraphQL Syntax

Full type inference for GraphQL documents using standard GraphQL syntax. Write queries and mutations with complete IDE autocomplete and type safety alongside the document builder.

Sponsors ❤️

Pre-Release Software

Graffle is still in development. Install with npm install graffle@next graphql to use the latest pre-release version.

Quick Start ​

ts
import { Graffle } from 'graffle'  const graffle = Graffle  .create()  .transport({ url: 'https://countries.trevorblades.com/graphql' })  const data = await graffle.gql`  query {  countries(filter: { name: { in: ["Canada", "Germany", "Japan"] } }) {  name  capital  emoji  }  } `.send()  console.log(data) // ^?

Why Choose Graffle? ​

Reasons to use ​

  • Full Type Safety — Inference for GraphQL syntax, optional generation for Document Builder
  • Flexibility — Start simple, progressively adopt type-safe features
  • Extensibility — Powerful extension system (OpenTelemetry, schema errors, custom scalars)
  • Multi-Transport — Execute against HTTP or in-memory schemas

Reasons to not use ​

Read the detailed comparison →

Document Builder

Optional generated TypeScript API for building type-safe queries. Get full IntelliSense and static type safety with a native TypeScript interface instead of GraphQL strings.

Learn moreFull example
ts
const pokemons = await graffle.query.pokemons({  $: { filter: { name: { in: ['Pikachu', 'Charizard'] } } },  name: true,  hp: true, })

GraphQL Strings with Type Inference

Use standard GraphQL syntax with full type inference. Write queries as strings and get complete type safety for variables and results without any code generation.

Learn moreFull example
ts
const data = await graffle.gql(`  query pokemonByName($name: String!) {  pokemonByName(name: $name) {  name  hp  }  } `).pokemonByName({ name: 'Pikachu' })

Powerful Extensions

Compose middleware to add observability, file uploads, schema errors, and more. Build your own extensions with a clean, type-safe API.

Learn more
ts
const graffle = Graffle  .create()  .use(OpenTelemetry())  .use(SchemaErrors)  const data = await graffle.query.pokemons({ name: true })

Custom Scalars

Register codecs for custom scalars and Graffle automatically encodes arguments and decodes results. Works seamlessly with dates, big integers, or any custom type.

Learn moreFull example
ts
const graffle = Graffle.create().scalar('Date', {  decode: (value: string) => new Date(value),  encode: (value: Date) => value.toISOString(), })  const pokemons = await graffle.query.pokemons({  $: { filter: { birthday: { lte: new Date('1987-01-13') } } },  birthday: true, // JavaScript Date })
Jason Kuhrt

Jason Kuhrt

Creator

Creator of Graffle, Molt, Paka, and Nexus. Former @prisma. Building tools for GraphQL and TypeScript ecosystems.

Sponsor