Config File

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.


It can contain the following values:

  • client: a relative path (from houdini.config.js) to a file that exports your houdini client as its default.
  • 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
  • projectDir (optional, default: process.cwd()): an absolute path pointing to your SvelteKit project (useful for monorepos)
  • schemaPath (optional, default: "./schema.graphql"): the path to the static representation of your schema, can be a glob pointing to multiple files. One of schema or schemaPath is required
  • apiUrl (optional): A url to use to pull the schema. If you don’t pass an apiUrl, the kit plugin will not poll for schema changes. For more information see the pull-schema command docs.
  • framework (optional, default: "kit"): Either "kit" or "svelte". Used to tell the preprocessor what kind of loading paradigm to generate for you. (default: kit)
  • module (optional, default: "esm"): One of "esm" or "commonjs". Used to tell the artifact generator what kind of modules to create. (default: esm)
  • definitionsPath (optional, default: "$houdini/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.
  • 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”.
  • disableMasking (optional, default: false): A boolean indicating whether fields from referenced fragments should be included in a document’s selection set (can be overridden individually)
  • schemaPollHeaders (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.
  • schemaPollInterval (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.
  • globalStorePrefix (optional, default: GQL_): The default prefix of your global stores. This lets your editor provide autocompletion with just a few characters.
  • 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)

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 new Date(val)
			// turn the value into something the API can use
			marshal(date) {
				return date.getTime()