Setting Up Your Project

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

What we’ll cover:

  • Where to get Houdini from
  • How to add the necessary configuration files for each supported platform (SvelteKit, Sapper, and Svelte)

Installation

houdini is available on npm:

yarn add -D houdini
# or
npm 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 --pull-header flag (abbreviated -ph). For example, npx houdini init -ph Authorization="Bearer MyToken". You will also need to provide the same flag to generate when using the --pull-schema flag.

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

We need to define an alias so that your codebase can import the generated runtime. Add the following values to vite.config.js:

export default {
    server: {
        fs: {
            allow: ['.']
        }
    }
}

Then, update your svelte.config.js to look like:

import houdini from 'houdini/preprocess'

export default {
    preprocess: [houdini()],

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

And finally, we need to configure our application to use the generated network layer. To do this, add the following block of code to src/routes/__layout.svelte and any __layout.reset.svelte files:

<script context="module">
    import houdiniClient from '../houdiniClient'

    houdiniClient.init()
</script>

Note: If you are building your application with adapter-static (or any other adapter that turns your application into a static site), you will need to set the static value in your config file to true.

Sapper

You’ll need to add the preprocessor to both your client and your server configuration:

import houdini from 'houdini/preprocess'

// add to both server and client configurations
export default {
    plugins: [
        svelte({
            preprocess: [houdini()]
        })
    ]
}

With that in place, the only thing left to configure your Sapper application is to connect your client and server to the generate network layer:

// in both src/client.js and src/server.js
import { setEnvironment } from '$houdini'
import env from './environment'

setEnvironment(env)

Svelte

If you are working on an application that isn’t using SvelteKit or Sapper, you have to configure the compiler and preprocessor to generate the correct logic by setting the framework field in your config file to "svelte".

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

If you are in a SvelteKit project, this step is done automatically.

The only thing required to configure when setting up a project with typescript is to teach the compiler how to resolve the $houdini import:

{
    // ...
    "compilerOptions": {
        "paths": {
            // ...
            "$houdini": [
                "./$houdini/"
            ]
        }
    }
}