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.

houdini.config.js
export default {
    apiUrl: 'http://localhost:4000/graphql',
    schemaPollHeaders: {
        Authentication(env) {
            return `Bearer ${env.AUTH_TOKEN}`
        }
    }
}

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
  • apiUrl (optional, 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.
  • 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”.
  • 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.
  • 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. For more information see the section below.
  • 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.
  • defaultListTarget (optional): Can be set to all for all list operations to ignore parent ID and affect all lists with the name.
  • 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.

Svelte Plugin

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

houdini.config.js
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.
  • projectDir (optional, default: process.cwd()): an absolute path pointing to your SvelteKit project (useful for monorepos)
  • 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

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()
            }
        }
    }
}

Environment Variables

There are a few different options for using environment variables in your apiUrl and schemaPollHeaders 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 {
	schemaPollHeaders: {
		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 {
	schemaPollHeaders: {
		Authentication: function(env) {
			return `Bearer ${env.AUTH_TOKEN}`
		},
	}
}