Setting Up Your Project

This guide should walk you through all of the steps necessary to add Houdini to an existing project.

Installation

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

Starting a New Project

Adding houdini to an existing project can easily be done with the provided command-line tool. If you don’t already have an existing app, visit this link for help setting one up.

Once you have a project and want to add houdini, execute the following command which will create a few necessary files, as well as pull down a json representation of your API’s schema:

npx houdini 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, here are the framework and technology specific steps you need to take:

SvelteKit

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

// vite.config.js

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

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

export default config

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

// svelte.config.js

export default {
	kit: {
		alias: {
			$houdini: path.resolve('.', '$houdini')
		}
	}
}

Svelte

If you are using vite, you should use the houdini/vite plugin even if you aren’t using kit. Update your vite.config.js file to look like this:

// vite.config.js

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

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

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. You will also need to make sure that the $houdini alias resolves to the directory in the root of your project.

// svelte.config.js
import houdini from 'houdini-svelte/preprocess'

export default {
	preprocess: [houdini()]
}

Please keep in mind that returning the response from a query, you should not rely on this.redirect to handle the redirect as it will update your browsers location attribute, causing a hard transition to that url. Instead, you should use this.error to return an error and handle the redirect in a way that’s appropriate for your application.

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"]
    }
}