Config

All configuration for your houdini application is defined in a single file that is imported by both the runtime and the command-line tool (called houdini.config.js). Because of this, you must make sure that any imports and logic are resolvable in both environments. This means that if you rely on process.env or other node-specifics you will have to use a plugin to replace the expression with something that can run in the browser.

houdini.config.js
/** @type {import('houdini').ConfigFile} */
export default {
    watchSchema: {
        url: 'http://localhost:4000/graphql',
    },
    scalars: {
        DateTime: {
            type: 'Date',
            unmarshal(val) {
                return val ? new Date(val) : null
            },
            marshal(date) {
                return date && date.getTime()
            }
        }
    }
}

Fields

By default, your config file can contain the following values:

  • include (optional, default: "src/**/*.{svelte,graphql,gql,ts,js}"): a pattern (or list of patterns) to identify source code files.
  • exclude (optional): a pattern (or list of patterns) that filters out files that match the include pattern
  • schemaPath (optional, default: "./schema.graphql"): the path to the static representation of your schema, can be a glob pointing to multiple files
  • watchSchema (optional, an object): configure the development server to poll a remote url for changes in the schema. When a change is detected, the dev server will automatically regenerate your runtime. For more information see Schema Polling.
  • persistedQueriesPath (optional, default: <rootDir>/persisted_queries.json): Configure the path of the persisted queries file.
  • module (optional, default: "esm"): One of "esm" or "commonjs". Used to tell the artifact generator what kind of modules to create.
  • definitionsPath (optional, default: "<rootDir>/graphql"): a path that the generator will use to write schema.graphql and documents.gql files containing all of the internal fragment and directive definitions used in the project.
  • scalars (optional): An object describing custom scalars for your project (see below).
  • cacheBufferSize (optional, default: 10): The number of queries that must occur before a value is removed from the cache. For more information, see the Caching Guide.
  • defaultCachePolicy (optional, default: "CacheOrNetwork"): The default cache policy to use for queries. For a list of the policies or other information see the Caching Guide.
  • defaultPartial (optional, default: false): specifies whether or not the cache should always use partial data. For more information, check out the Partial Data guide.
  • defaultLifetime (optional, default: undefined): Specifies after how long a data goes stale in miliseconds. Cache stale.
  • defaultKeys (optional, default: ["id"]): A list of fields to use when computing a record’s id. The default value is ['id']. For more information see the Caching Guide.
  • types (optional): an object that customizes the resolution behavior for a specific type. For more information see the Caching Guide.
  • logLevel (optional, default: "summary"): Specifies the style of logging houdini will use when generating your file. One of “quiet”, “full”, “summary”, or “short-summary”.
  • defaultFragmentMasking (optional, default: "enable"): "enable" to mask fragment and use collocated data requirement as best or "disable" to access fragment data directly in operation. Can be overridden individually at fragment level.
  • defaultListTarget (optional): Can be set to "all" for all list operations to ignore parent ID and affect all lists with the name.
  • defaultPaginateMode (optional, default: "Infinite"): The default mode for pagination. One of "Infinite" or "SinglePage".
  • defaultListPosition (optional, default: “first”): One of "first" or "last" to indicate the default location for list operations.
  • plugins (optional): An object containing the set of plugins you want to add to your houdini application. The keys are plugin names, the values are plugin-specific configuration. The actual plugin API is undocumented and considered unstable while we try out various things internally. For an overview of your framework plugin’s specific configuration, see below.
  • supressPaginationDeduplication (optional, default `false): Prevents the runtime from deduplicating pagination requests

Svelte Plugin

Configuring the svelte plugin is done inside of the plugins key in your config file:

houdini.config.js
/// <references types="houdini-svelte">

/** @type {import('houdini').ConfigFile} */
export default {
    // ...
    plugins: {
        'houdini-svelte': { }
    }
}

Here is a summary of the possible configuration values:

  • client (optional, default: "./src/client"): a relative path (from houdini.config.js) to a file that exports your houdini client as its default.
  • defaultRouteBlocking (optional, default: false): Specifies the default blocking behavior for client-side navigation. For more information, please visit this section of the docs.
  • projectDir (optional, default: process.cwd()): an absolute path pointing to your SvelteKit project (useful for monorepos)
  • runtimeDir (optional, default: '$houdini): The name of the directory used to output the generated Houdini runtime, relative to projectDir.
  • pageQueryFilename (optional, default: "+page.gql"): The name of the file used to define page queries.
  • layoutQueryFilename (optional, default: "+layout.gql"): The name of the file used to define layout queries.
  • quietQueryErrors (optional, default: false): With this enabled, errors in your query will not be thrown as exceptions. You will have to handle error state in your route components or by hand in your load (or the onError hook)
  • static (optional, default: false): A flag to remove the session infrastructure from your application
  • framework (optional, default: undefined): It should be automatically detected but you can override it here with kit or svelte

Client Location

Your client must be discoverable by the svelte code generation logic. By default, it looks at src/client.{js,ts} but if your client is defined elsewhere, you will need to configure the houdini-svelte plugin to point to the correct location:

houdini.config.js
export default {
    // ...
    plugins: {
        'houdini-svelte': {
            client: "./src/lib/graphql/client",
        }
    }

}

Custom Scalars

Configuring your runtime to handle custom scalars is done under the scalars key in your config:

houdini.config.js
export default {
    // ...
    scalars: {
        // the name of the scalar we are configuring
        DateTime: {
            // the corresponding typescript type
            type: 'Date',
            // turn the api's response into that type
            unmarshal(val) {
                return val ? new Date(val) : null
            },
            // turn the value into something the API can use
            marshal(date) {
                return date && date.getTime()
            }
        }
    }
}

Please note that your marshal/unmarshal functions are also called with null values, and these must be handled appropriately.

Schema Polling

You can configure your development server to poll a remote URL for changes in your schema using the watchSchema argument:

export default {
	watchSchema: {
		url: 'http://localhost:4000/graphql',
		headers: {
			Authentication(env) {
				return `Bearer ${env.AUTH_TOKEN}`
			}
		}
	}
}

You can pass the following parameters to watchSchema:

  • url (a string or function): Configures the url to use to pull the schema. If you don’t pass an apiUrl, the kit plugin will not poll for schema changes. If you want to access an environment variable, you can either prefix your string with env: or set it to a function that takes the current environment and returns a string. For more information see the section below.
  • headers (optional): An object specifying the headers to use when pulling your schema. Keys of the object are header names and its values can be either a strings or a function that takes the current process.env and returns the the value to use. If you want to access an environment variable, prefix your string with env:, ie env:API_KEY. For more information see the section below.
  • interval (optional, default: 2000): Configures the schema polling behavior for the kit plugin. If its value is greater than 0, the plugin will poll the set number of milliseconds. If set to 0, the plugin will only pull the schema when you first run dev. If you set to null, the plugin will never look for schema changes. You can see use the pull-schema command to get updates.
  • timeout (optional, default: 30000): Sets a custom timeout in milliseconds which is used to cancel fetching the schema. If the timeout is reached before the remote API has responded, the request is cancelled and an error is displayed. The default is 30 seconds.

Environment Variables

There are a few different options for using environment variables in your url and headers config values. Keep in mind that Houdini will look for .env and .env.local files for environment variables. For simple cases, you can just prepend env: to the value:

export default {
	watchSchema: {
		url: '...',
		headers: {
			Authentication: 'env:AUTH_TOKEN'
		}
	}
}

In other situations, the environment variable can’t be used directly. For example to prepend Bearer to the value. For these situations, the values of the object should get set to a function that will receive the current environment variables:

export default {
	watchSchema: {
		url: '...',
		headers: {
			Authentication(env) {
				return `Bearer ${env.AUTH_TOKEN}`
			}
		}
	}
}

Adding Plugins

If you are adding a third-party plugin, you can just use the package name instead of a relative path:

houdini.config.js
export default {
    plugins: {
        'houdini-svelte': {
            // any configuration values go here
        }
    }
}

If you defined plugin locally, you can just reference the file in your houdini.config.js file to add it to your project. For the time being, local plugins need to be written in javascript since the build environment imports it directly.

houdini.config.js
export default {
    plugins: {
        './src/plugins/myPlugin.js': {}
    }
}

Keep in mind: your config file will be bundled into your application so you shouldn’t use path or any packages you don’t want to include.