Autumn '25 🍂 Status Update

[jasonkuhrt]

Here is my seasonal update on Graffle, the Autumn '25 edition 🍂. The previous one was the Winter '25 update.

Winter/Spring/Summer Retrospective

Since the last update, I was busy with Polen while collaborating at The Guild. That said, the past few months (especially October-November) saw a burst of significant improvements.

What Got Done

Static Builder Story - Major Improvements

The document builder experience has been seriously leveled up:

• Static Document Builder API - Fully static/compile-time document building without runtime overhead
• Type-Safe Native Documents - Integration with gql-tada for full TypeScript introspection
• Multi-Operation String Docs - Support for multiple operations in string-based documentation
• Document Builder Independence - Document builders now work independently of schema definitions
• Deferred Execution - Smart defer execution when variables are present
• Default Unknown Scalars - Better handling of custom scalars without explicit definitions
• Simplified Alias Syntax - Cleaner syntax for scalar field aliases

Website & Documentation - Serious Overhaul

• Comprehensive documentation of the document builder feature
• JSDoc improvements across the codebase
• New guides: TypeScript Type Diagnostics, TypeScript Variance
• Fixed misleading terminology ("compile-time" → accurate terms)
• Simplified README installation instructions

Long Tail of Fixes & Improvements

• Windows CLI Support - Full cross-platform support
• TypedDocumentString Support - Compatibility with graphql-codegen
• TypeScript Reserved Keywords - Proper handling in enum generation
• LSP Support - Fixed language server support for string docs
• Generator Improvements - SDL file force emission, auto-detect import format
• Browser Compatibility - Kit updates for broader environment support
• Extensive refactoring consolidating utilities into graphql-kit
• Migration from Zod to Effect Schema in CLI

Sponsorship

LambdaTest came on as a sponsor with a token contribution, every bit helps!

Looking Forward

Kit Monorepo

My utility library @wollybeard/kit has grown substantially and its footprint in Graffle is significant. The priority is getting kit into a monorepo structure so Graffle can depend on smaller, focused packages rather than the whole thing.

Graffle Monorepo

This is the key architectural change ahead (#1420). The plan is to split Graffle into focused packages:

• @graffle/core - Shared infrastructure
• @graffle/client - The GraphQL client
• @graffle/generator - Code generation & CLI
• Individual extension packages (document-builder, introspection, throws, etc.)
• graffle - Convenience package with batteries included

@graffle/client as graphql-request Successor

Once the monorepo lands, my vision is that @graffle/client becomes a near drop-in replacement for graphql-request - just vastly better. Approximately same simplicity, but with type safety, extensions, custom scalars, and all the goodness Graffle has built up.

Timeline Reality Check

No ETAs. This is a personal project and the last few months I took time off for personal work. I'm starting a new job at Heartbeat next week, so my time going forward will be more limited again.

As always, Graffle remains a labour of love. Progress will continue at whatever pace life allows.

If you read all this, thank you! Let me know your thoughts.

[samalisam-novu]

First off, thank you so much for your work. We really appreciate the love and dedication you’re putting into graffle. We’re already using it heavily across several projects.

We originally migrated from graphql-request@7 to an early graffle next build (164, to be exact), and I can see you’ve shipped a lot since then. Do you think now is a good time for us to migrate to the latest next version so we can stay closer to where you are, and also help by reporting anything odd we run into?

Of course I’m hoping for an 8.0 release eventually, but until then I’m wondering if it makes sense to move forward now?

Thanks again and wishing you happy holidays and a warm start at Heartbeat!

[jasonkuhrt]

Hey @samalisam-novu I do think it makes sense, especially if you're open to providing feedback that I can iterate on quickly. While I have my prioritization when a user shares their real world experience that generally jumps to the top of my stack at this point. E.g. prioritize a bug fix or address a blocking feature issue.