Getting Started

Houdini is a full-stack React framework built around GraphQL. It handles routing, server-side rendering, and data fetching. Because it’s built for GraphQL specifically, it can make some assumptions that general-purpose frameworks can’t, which means a lot less wiring for you.

The fastest way to start a project is:

npm create houdini@latest

Answer the prompts, then:

cd <project-name>
npm install
npm run dev

That’s enough to have a working app running locally.

Project Structure

A freshly generated project looks like this:

src/
  routes/
    +layout.tsx       # root layout, wraps every page
    +page.tsx         # the root page (renders at /)
  +index.tsx          # the root HTML document
  +client.ts          # your HoudiniClient definition
vite.config.ts        # Vite config with the Houdini plugin
houdini.config.ts     # Houdini configuration

src/
  routes/
    +layout.jsx       # root layout, wraps every page
    +page.jsx         # the root page (renders at /)
  +index.tsx          # the root HTML document
  +client.ts          # your HoudiniClient definition
vite.config.js        # Vite config with the Houdini plugin
houdini.config.js     # Houdini configuration

Routes live in src/routes. The filesystem is the router: new routes are new files. We’ll cover how that works in detail in Routing.

IDE Setup

Houdini integrates with the community-standard GraphQL LSP, which gives you autocomplete and validation for your GraphQL documents directly in your editor. Install the VS Code extension and it will pick up Houdini’s configuration automatically.