Houdini API Reference

Every GraphQL document in your Houdini application has two different ways of interacting with it. You can either define your document inside of your svelte components or in an external file. While the approaches are equivalent, their APIs do vary slightly for the situation. In order to accommodate this, each document page has a toggle in the top right to flip between the store and inline APIs. For more information about the differences in the APIs, checkout out the Working With GraphQL guide.

GraphQL Documents

query

Fetch data from the server

const { data } = query(graphql`
    query AllTodoItems {
        items {
            text
        }
    }
`)

const { data } = query(graphql`
    query AllTodoItems {
        items {
            text
        }
    }
`)

fragment

Reuse part of a query

const data = fragment(graphql`
    fragment UserAvatar on User {
        firstName
        lastName
        email
    }
`)

const data = fragment(graphql`
    fragment UserAvatar on User {
        firstName
        lastName
        email
    }
`)

mutation

Send updates to the server and keep the local cache up to date

const addFriend = mutation(graphql`
    mutation FollowFriend {
        followFriend(id: 1) {
            friend {
                followed_by_viewer
            }
        }
    }
`)

const addFriend = mutation(graphql`
    mutation FollowFriend {
        followFriend(id: 1) {
            friend {
                followed_by_viewer
            }
        }
    }
`)

subscription

Real-time updates

subscription(graphql`
    subscription PostLiked {
        postLiked {
            post {
                like_count
            }
        }
    }
`)

subscription(graphql`
    subscription PostLiked {
        postLiked {
            post {
                like_count
            }
        }
    }
`)

Extra Bits

A summary of the custom things houdini lets you do in your graphql documents

const addFriend = mutation(graphql`
    mutation SetFavorite {
        setFavoriteRecipe(id: 1) {
            recipe {
                ...Favorites_insert
            }
        }
    }
`)

const addFriend = mutation(graphql`
    mutation SetFavorite {
        setFavoriteRecipe(id: 1) {
            recipe {
                ...Favorites_insert
            }
        }
    }
`)

Setup

Config

The config file format

export default {
    schemaPath: './schema.graphql',
    sourceGlob: 'src/**/*.svelte',
    module: 'esm',
    framework: 'kit',
    apiUrl: 'http://localhost:4000'
}

export default {
    schemaPath: './schema.graphql',
    sourceGlob: 'src/**/*.svelte',
    module: 'esm',
    framework: 'kit',
    apiUrl: 'http://localhost:4000'
}

Command Line

Command line tool commands and arguments

houdini generate --pull-schema

houdini generate --pull-schema

Preprocessor

A powerful tool to enable Houdini's declarative API

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

export default {
    preprocess: [houdini()],
}

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

export default {
    preprocess: [houdini()],
}