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

Install the Houdini GraphQL extension for VS Code to get live diagnostics, completions, hover documentation, and go-to-definition, powered by the same compiler that builds your app. See IDE Setup for details and other editors.