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 run the following command to add Houdini to your project. Just follow questions and the tool will configure everything for you (setup url, get schema, prepare project files, etc).

npx houdini@latest init

This will send a request to your API to download your schema definition. 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.js file to configure your project. This file should be like:

/** @type {import('houdini').ConfigFile} */
const config = {
    "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.js to be used by houdini. This file should be like:

import { HoudiniClient } from '$houdini';

export default new HoudiniClient({
    url: 'https://[YOUR_URL_HERE]/graphql'
})

More information about the client file can be found here.

Step 4: gitignore

Optional: You can add $houdini to your .gitignore as it will be only 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.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.js. Make sure that houdini comes before sveltekit:

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

/** @type {import('vite').UserConfig} */
const config = {
    plugins: [houdini(), sveltekit()]
}

export default config

Finally, update your svelte.config.js to support the $houdini alias:

import path from 'path'

export default {
    kit: {
        alias: {
            $houdini: path.resolve('.', '$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.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.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

We recommend the following extensions for your editor to take full advantage of GraphQL:

• IntelliJ - GraphQL
• Vim - vim-graphql
• VSCode - GraphQL: Language Feature Support

To take the full advantage of these extensions, you should add a file in the root like:

projects:
  default:
    schema:
      - ./schema.graphql
      - ./$houdini/graphql/schema.graphql
    documents:
      - '**/*.gql'
      - '**/*.svelte'
      - ./$houdini/graphql/documents.gql

If you want to add another suggestion, please open a PR or contact us.