File Conventions
Every file Houdini treats as special starts with +. Everything else (utility functions, shared components, stylesheets) is ignored by the router and can live wherever makes sense for your project. The + prefix might look a little odd at first, but it serves two purposes: it makes Houdini files instantly recognizable in any directory listing, and it lets Houdini add new reserved filenames in the future without any risk of colliding with files you’ve already created.
Route Files
These files go inside src/routes/ and can appear in any route directory.
| File | Purpose |
|---|---|
+page.tsx+page.jsx | The component rendered at this route. Receives query results as props when a +page.gql is present. |
+layout.tsx+layout.jsx | Wraps all child routes. Receives a children prop for the nested content, plus query results from +layout.gql if defined. |
+error.tsx+error.jsx | Renders an error boundary for this route and everything nested below it. Receives an errors prop plus any layout query results in scope. |
+page.gql | GraphQL query (or queries) for this page. Each query’s result is passed as a prop named after the query. |
+layout.gql | GraphQL query for this layout. Results are available to the layout component and all of its descendants. |
A +page.tsx+page.jsx or +layout.tsx+layout.jsx can also export a headers() function to set response headers for the route.
Server Files
These files go in src/server/. Houdini compiles this directory into the server bundle and never imports it from the client, so it is the one place that is safe to read environment variables, embed secrets, or hold credentials (session signing keys, OAuth client secrets, database URLs) with no risk of any of it reaching the browser.
| File | Purpose |
|---|---|
+config.ts+config.js | Server-only configuration (typed ServerConfigFile): the session signing keys, the session and GraphQL endpoints, OAuth providers and onSignIn, and the form CSRF settings. See authentication. |
+schema.ts+schema.js | Exports an executable GraphQL schema. Houdini wraps it in a Yoga instance automatically. Only relevant with a local GraphQL server. |
+yoga.ts+yoga.js | Exports a custom Yoga instance. Use this to inject context, add plugins, or customize behavior. Requires +schema.ts+schema.js to also be present. |
App-Level Files
These go directly in src/, not inside routes/.
| File | Purpose |
|---|---|
+index.tsx+index.jsx | The root HTML document. Controls the <html>, <head>, and <body> shells that wrap every page. |
+client.ts+client.js | Exports the HoudiniClient instance used throughout the app. |
Path Aliases
Houdini configures a ~ alias that resolves to your project’s src/ directory. Use it anywhere to avoid brittle relative import paths:
import { Button } from '~/components'import { formatDate } from '~/lib/utils'Both lines above resolve relative to src/, regardless of how deeply nested the importing file is.