Setting Up Your Project

This guide contains two different approaches to add Houdini to your project. The first one uses a script that will configure everything for you. The second is more manual, explaining all of the necessary steps.

Init Script

Once you have a SvelteKit Project (either an existing one or by following these instructions, you can add Houdini with the Svelte CLI. Just follow questions and the tool will configure everything for you (setup url, get schema, prepare project files, etc).

npx sv add @houdinigraphql

This will scaffold all the required files for Houdini to work with SvelteKit. When using a remote schema, don’t forget to run npx houdini pull-schema to download your schema definition from your API. If you need headers to authenticate this request, you can pass them in with the --headers flag (abbreviated -h). For example, npx houdini init -h Authorization="Bearer MyToken".

And that’s it! You should be all set with everything you need to work with Houdini.

If something went wrong, or you need to update your project by hand for some reason, check the next chapter that describes each framework and technology specificities.

Manual Installation

Project Setup

Step 1: Install the Package

The base package houdini is available on npm and should be installed as a dev dependency:

yarn add -D houdini
## or
npm install --save-dev houdini
## or
pnpm install --save-dev houdini

Step 2: Create houdini.config

You need a houdini.config.tshoudini.config.js file to configure your project. This file should be like:

/** @type {import('houdini').ConfigFile} */
const config = {
    "url": 'https://[YOUR_URL_HERE]/graphql',
    "plugins": {
        // add your plugins here
    }
}

export default config

More information about the config file can be found here.

Step 3: create HoudiniClient

You need a /src/client.ts/src/client.js to be used by houdini. This file should be like:

import { HoudiniClient } from '$houdini';

export default new HoudiniClient()

More information about the client file can be found here.

Step 4: gitignore

When using a VCS, we recommend adding the .houdini directory to the list of ignored files, as it will only contain generated content

SvelteKit

First, we need to add the dedicated houdini package for svelte & sveltekit:

yarn add -D houdini-svelte
## or
npm install --save-dev houdini-svelte
## or
pnpm install --save-dev houdini-svelte

Then, we need to add houdini-svelte plugin to the houdini.config.tshoudini.config.js file

/** @type {import('houdini').ConfigFile} */
const config = {
    "plugins": {
        "houdini-svelte": {}
    }
}

export default config

Then, we need to add houdini’s plugin to your vite.config.tsvite.config.js. Make sure that houdini comes before sveltekit:

import { sveltekit } from '@sveltejs/kit/vite'
import { defineConfig } from '@sveltejs/kit/vite'
import houdini from 'houdini/vite'

export default defineConfig({
  plugins: [houdini(), sveltekit({ /* ... */ })]
})

Finally, update the sveltekit({ ... }) config in vite.config.tsvite.config.js to add support for the $houdini alias:

import { sveltekit } from '@sveltejs/kit/vite'
import { defineConfig } from '@sveltejs/kit/vite'
import houdini from 'houdini/vite'

export default defineConfig({
  plugins: [
    houdini(),
    sveltekit({
      // ... other options set for SvelteKit to work

      alias: {
        $houdini: '.houdini/'
      }
    })
  ]
})

Older projects or projects set up with the Svelte CLI version < 0.16 will have the sveltekit config in a separate svelte.config.tssvelte.config.js file. In that case, add the same alias config object in the kit property of the config:

import path from 'path'

export default {
    kit: {
        alias: {
            $houdini: '.houdini/'
        }
    }
}

Svelte

First, we need to add the dedicated houdini package for svelte:

yarn add -D houdini-svelte
## or
npm install --save-dev houdini-svelte
## or
pnpm install --save-dev houdini-svelte

Then, we need to add houdini-svelte plugin to the houdini.config.tshoudini.config.js file

/** @type {import('houdini').ConfigFile} */
const config = {
    "plugins": {
        "houdini-svelte": {}
    }
}

export default config

If you are using vite, you should use the houdini/vite plugin even if you aren’t using kit. You will also need to make sure that the $houdini alias resolves to the directory in the root of your project. Update your vite.config.tsvite.config.js file to look like this:

import { svelte } from '@sveltejs/vite-plugin-svelte'
import houdini from 'houdini/vite'
import { defineConfig } from 'vite'

export default defineConfig({
    plugins: [houdini(), svelte()],

    resolve: {
        alias: {
            $houdini: '.houdini/',
        },
    },
})

If you aren’t using vite, it’s a lot harder to give an exact recommendation but somehow you should import houdini’s preprocessor and pass it to your svelte config.

import houdini from 'houdini-svelte/preprocess'

export default {
    preprocess: [houdini()]
}

Typescript

When using Typescript and SvelteKit, you will need to add houdini to your rootDir value so that you can use the generated variable and hooks types in your routes:

{
    "compilerOptions": {
        "rootDirs": [".", "./.svelte-kit/types", "./.houdini/types"]
    }
}

Setup your IDE

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.