From 5845cb8e6eecfcdb75afcf6f14ce46422b18cd36 Mon Sep 17 00:00:00 2001 From: Alec Aivazis Date: Fri, 21 Oct 2022 12:18:14 -0700 Subject: [PATCH] Document plugin config (#626) --- site/src/routes/api/config.svx | 48 +++++++++++++++---- site/src/routes/guides/caching-data.svx | 2 +- .../routes/guides/working-with-graphql.svx | 7 ++- 3 files changed, 44 insertions(+), 13 deletions(-) diff --git a/site/src/routes/api/config.svx b/site/src/routes/api/config.svx index 4c9a1d1623..cbdd8379bb 100644 --- a/site/src/routes/api/config.svx +++ b/site/src/routes/api/config.svx @@ -8,17 +8,24 @@ description: A description of every valid configuration value for Houdini. 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. +```javascript +/// houdini.config.js +export default { + apiUrl: 'http://localhost:4000/graphql' + schemaPollHeaders: { + Authentication: "Bearer XYZ", + } +} +``` + ## Fields -It can contain the following values: +By default, your config file 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 +- `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 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](/api/cli#pull-schema). -- `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). @@ -30,20 +37,45 @@ It can contain the following values: - `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. +- `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](/api/cli#pull-schema) to get updates. +- `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: + +```javascript +/// houdini.config.js + +export default { + // ... + plugins: { + 'houdini-svelte': { + client: './src/client.ts' + } + } +} +``` + +Here is a summary of the possible configuration values: + +- `client` (required): 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. - `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) +- `static` (optional, default: `false`): A flag to treat every component as a non-route. ## Custom Scalars Configuring your runtime to handle custom scalars is done under the `scalars` key in your config: ```javascript -// houdini.config.js +/// houdini.config.js export default { // ... - scalars: { // the name of the scalar we are configuring DateTime: { diff --git a/site/src/routes/guides/caching-data.svx b/site/src/routes/guides/caching-data.svx index 3c6d84cc3c..2a430dfcea 100644 --- a/site/src/routes/guides/caching-data.svx +++ b/site/src/routes/guides/caching-data.svx @@ -17,7 +17,7 @@ query AllItems @cache(policy: CacheAndNetwork) { } ``` -There are 3 different policies that can be specified: +There are a few different policies that can be specified: - `CacheOrNetwork` will first check if a query can be resolved from the cache. If it can, it will return the cached value and only send a network request if data was missing. If you have opted into partial data with `@cache(partial: true)` and the result contains partial data (some but not all of the data is available in the cache), you will get the partial data first and then a network request will trigger - almost like it behaves like `CacheAndNetwork`. - `CacheAndNetwork` will use cached data if it exists and always send a network request after the component has mounted to retrieve the latest data from the server. The cached portion of this might contain partial data if you opt-in. diff --git a/site/src/routes/guides/working-with-graphql.svx b/site/src/routes/guides/working-with-graphql.svx index 6061dba4ab..15079f3aa2 100644 --- a/site/src/routes/guides/working-with-graphql.svx +++ b/site/src/routes/guides/working-with-graphql.svx @@ -7,8 +7,7 @@ description: An overview of the various ways Houdini applications can leverage G