Houdini is a GraphQL client that tries to compile away

The framework is a compiler with a small runtime attached

The tagline is the disappearing GraphQL framework, and the README explains the idea in a sentence: Houdini shifts what is traditionally handled by a bloated runtime into a compile step, producing a lean GraphQL abstraction for the application. That claim has a visible consequence in the repository, which is that the project is not a single JavaScript package. The `go.mod` file declares the module `code.houdinigraphql.com` and requires Go 1.25.0, and its dependencies give away what the Go side does. The GraphQL parser is `github.com/vektah/gqlparser/v2`, so the schema and the documents are parsed in Go, and the other dependencies are a WebSocket library for subscriptions, a filesystem abstraction, two SQLite drivers, a dotenv loader, a test framework and a synchronisation package. The Go program is the compiler, and the TypeScript side is what ends up in the browser.

The monorepo holds packages, plugins and the test harness

The tree is a pnpm workspace with a `packages/` directory, a `plugins/` directory, a `docs/` folder, an `e2e/` folder, a `perf/` folder and a `netlify.toml`. The root `package.json` is private and named `houdini-monorepo`, and it declares the toolchain: turbo for task orchestration, vitest for tests, Playwright for end to end work, biome for linting and formatting, TypeScript, and the changesets toolchain for versioning and changelogs. There is also a `.graphqlrc.yaml`, which is the conventional place for GraphQL tooling configuration, and a `CLAUDE.md` in the root, which suggests the project keeps agent instructions in the repository. The package layout is why the README refers to a framework rather than a library: the client for SvelteKit, the React client, the Svelte client and the router integrations are separate packages, and the published release list shows adapter packages with their own version numbers, including `houdini-adapter-cloudflare` and `houdini-adapter-auto`.

Building and testing the workspace

The scripts in the root manifest show how the pieces are driven, and they are ordinary workspace commands once you know them. The build and the test entry points are:

pnpm run build
pnpm run tests

The build script filters turbo to the packages directory, so a full build compiles the published packages rather than the examples, and the test script simply runs vitest. There are also targeted commands, since `turbo run build --filter="./packages/*"` and `turbo run typedefs --filter="./packages/*"` can be narrowed to a single package, and a `compile` script exists separately from `build`, which matches the split between generating artefacts and packaging them. Formatting and linting are handled by biome rather than by prettier and eslint, with `biome lint` and `biome format --write` as the two entry points. For releases there is a script that builds and then runs the release helper in `packages/_scripts/release.js`, and a snapshot variant of the same, plus a separate version script, all of which sit on top of changesets for the changelog.

Data requirements live next to the component that needs them

The first feature on the list is composable and colocated data requirements, and that phrase carries the main design idea. In a typical setup the query and the variables are declared in the same file as the component, so the component owns the data it renders and the requirement can be composed into a parent rather than duplicated. The second feature is a normalized cache with declarative updates, which is the part that changes how an application feels. A normalized cache stores entities by identifier rather than as nested response trees, so the same record fetched in two places is one entry, and an update that comes back from a subscription or a mutation can be written into the cache and every component that shows that record sees it. The third feature is generated types, which follows from the compile step: the types for a query's result and its variables can be produced from the schema and the document rather than hand written, and the repository has a `typedefs` task for exactly that.

Pagination and subscriptions come with the cache

The last two features on the list are the ones that usually require extra machinery in a hand rolled client. Pagination is supported in both cursor and offset form, which matters because the two need different cache handling: a cursor based page has a natural place in the cache and a stable key, while an offset page has to be invalidated when an item is inserted ahead of it. A normalized cache with declarative updates is what makes that manageable, since the update can be applied to the record itself rather than rewriting the page. Subscriptions are also listed, and the Go side of the repository carries a WebSocket dependency, which is where the transport lives when the subscription is handled by the compiler rather than by the browser. Together these three, colocated requirements, a normalized cache and subscriptions, are the reason to pick this client over a thin fetch wrapper, and also the reason the compile step exists at all.

The benchmark harness is checked in, with a comparison script

Performance claims in a GraphQL client are usually asserted in a blog post, so it is worth noting that this repository has the measurement apparatus in the tree. There is a `perf/` directory with benchmark files, a watch script at `perf/watch-bench.sh`, and scripts that run vitest bench over the cache benchmarks directory and write JSON output. The interesting part is the `bench:check` script, which runs the benchmarks, writes a second JSON file named `benchmark.current.json`, and then runs a node script called `perf/compare.js` to compare it against the stored baseline. That is a regression check on the cache implementation, not a marketing number, and it means a change to the cache that slows it down can be caught in CI. There is also a quick mode that sets an environment variable to shorten the run, which is what you would use on a pull request, and the whole thing runs through vitest, so the benchmarks share the test runner rather than needing a separate tool.

Version state, licensing and where the work is

The release list is the thing to look at carefully. The newest package tag shown is `[email protected]` from 2025-10-10, and the Cloudflare and auto adapters are on `1.3.8-next.10` tags from 2025-09-17. So the framework is on a 2.0 line in preview and the adapters are still on the 1.3 line, which is the kind of skew you see when a rewrite of the core is in progress. The repository is not archived and the last push was on 2026-09-28, so work is continuing between releases rather than having stopped. The licence is MIT, and the repository also carries a code of conduct, a contributing guide on the website, and a Discord where the maintainers say they are online almost around the clock. The README points at two worked examples for reading the code in context: an example SvelteKit todo application and the final version of the Pokedex application from the getting started guide.

Editorial conclusion

Houdini suits a team that has already decided to use GraphQL and wants a client that does not add a large runtime, particularly a SvelteKit shop where the framework plugins do the wiring, and it suits anyone who wants generated types to come from the same place as the queries. It is a poor fit if you want a library you can add to any project with one import, because the compile step and the plugin are part of the deal, and it is a poor fit if you need a stable release line today, since the newest listed package tag is a 2.0.0 next build from 2025-10-10. Before you adopt it, check three things: which framework plugin you will use and whether that adapter is on the same release cadence, since the Cloudflare and auto adapters carry their own next tags, how the generated cache behaves with the pagination and subscription features you need, and the state of the repository, where the last push was on 2026-09-28 under the MIT licence.

Frequently asked questions

Official sources

1. HoudiniGraphql/houdini on GitHub
2. License: MIT
3. Project website
4. README
5. Releases