Support SvelteKit's new API

[AlecAivazis]

This PR updates houdini's APIs to be compatible with the updates to SvelteKit as described here: sveltejs/kit#5774.

Update 8/24

It's been released and is now available on npm as houdini@next 🥳.

We have a few super small things to do before we can release it for real but if you start to migrate your app and run into any problems (or even if you don't) we'd love to hear from you. Also feel free to let us know if there are things you think should be done a different. The whole point of this pre-release is to collect feedback and tweak things before we're locked into something.

Here's the place to leave feedback: https://github.com/HoudiniGraphql/houdini/discussions/475. Please use this discussion instead of issues until we release the new version

Update 8/21

Almost there! 🎉

All of the integration tests are passing locally but there seems to be something going on with GitHub Actions. Hopefully it doesn't take us too long to figure out what's going on.

For an up-to-date overview of what's changed, you can check out the release notes section of the doc's preview link. The content below is all still valid but I'm not going to nitpick small changes in this PR description so it's best to just go to the updated docs directly.

Thanks for the patience!

Upcoming Changes

Just to get some points out of the way for people worried about major breaking changes:

• SvelteKit projects will now need to use the vite plugin defined at houdini/vite which replaces the old preprocessor (and the ugly server.fs.allow config). But don't worry, there are lots of really cool things that we're getting with this move.
• The external document store api for SvelteKit routes is changing. This means that if you rely heavily on the document stores, you will have to update your load functions but as a result you can delete a lot of the code in your components and the overall mental model is a lot simpler (no more passing around context)
• inline queries have to change too (since kit just made data a keyword in a route). At a high level, you'll now use the result of query directly instead of destructuring data. Also, everything that used to be defined in context="module" is now defined in +page.js/ts.

For additional breaking changes and notes, check out the section at the bottom of this. We know this is a lot of changes but we have been thinking about some of these for awhile and since SvelteKit has forced us to change the API, it seemed like a good time to shift some things around.

Vite Plugin

For kit projects, the preprocessor has moved to houdini/vite and should be included as a plugin in your vite.config.js. You should also remove the the fs.server.allow config since its baked into the plugin. This plugin not only processes our components and javascript files, but it also integrates into vite's dev script to bring some huge improvements:

• automatically generates your artifacts and stores whenever it detects a change in your source code. if you have configured your own watcher, it might not be necessary anymore.
• poll your api for changes in your schema and regenerate when they are detected. This behavior is customizable between 3 modes: a duration in milliseconds, only pull when the project first starts, and never pull.

Ideally, you shouldn't need to run generate ever again! It'll even get run when you build your application with vite build so feel free to delete that generate script from your package.json if you have it.

New Store API

The core of this change is that instead of using stores that you import, your component will now get the store from its props. This is the full example for the component-side of a store-driven route:

<script>
  /** @type {import('./$types').PageData */
  export let data: PageData ;

  $: ({ UserInfo } = data);
</script>

{$UserInfo.data.firstName}

Notice there's no more need to thread variables around or that ugly $: browser && store.fetch.

In order to make this work, your load functions need to now return instances of the store embedded in the correct key. This can be easily done with the new load_StoreName functions. The load_ prefix is to make it easy to autocomplete when you are working in your editor:

import { load_UserInfo } from '$houdini'

export async function load(event) {
    return { 
        ...await load_UserInfo({ event })
    }
}

This means that when adding a query to a route, tasks like adding a store to a load, pulling that store out of data in your component, etc can be auto completed from just starting with load_ in your route's load function. It does make the manual logic that uses a fetch result kind of messy since they have to pull out UserInfo but I think that’s a rare situation so I’m in favor of supporting the most people with the clean API and letting the advanced users deal with the complexity.

Also, on a slightly unrelated note: you don't need to pass context everywhere anymore! that all happens behind the scenes now.

Page Queries

You can now define a +page.gql file inside of a route directory to automatically opt-into a generated load without having to do anything else:

# src/routes/myProfile/+page.gql

query MyQuery { 
	viewer { 
		id
	}
}

With that file in place, you can just import and use the MyQuery store passed to your route and the view will be SSR'd automatically.

Generating Loads For Stores

You can now tell the houdini plugin to generate loads for your stores. To do this, you need to export a houdini_load variable from your +page.js/ts file:

// src/routes/myProfile/+page.ts
import { GQL_MyQuery, GQL_Query1, GQL_Query2 } from '$houdini'

export const houdini_load = GQL_MyQuery 
// or 
export const houdini_load = [ GQL_Query1, GQL_Query2 ]

This can be mixed with the new graphql tag api to define your queries inside of your javascript files:

import { GQL_MyQuery, graphql. } from '$houdini'

const otherQuery = graphql`
	query ViewerInfo { 
		viewer { 
			id
		}
	}
`

export const houdini_load = [ GQL_MyQuery, otherQuery ]

or

// src/routes/myProfile/+page.ts

export const houdini_load = graphql`
	query ViewerInfo { 
		viewer { 
			id
		}
	}
`

Generated type definitions for route functions

Instead of duplicating the documentation that's already written, you can visit the new typescript guide here: https://docs-git-directory-routes-houdinigraphql.vercel.app/guides/typescript

Breaking Changes / Notes

• configuration for inline queries (variable functions, hooks, etc.) go in +page.js
• inline fragments have a reversed order for arguments
• config.sourceGlob is no longer required and has been deprecated in favor of config.include which has a default value that covers most projects
• added config.exclude to filter out files that match the include pattern
• generate --pull-header is now generate --header (abbreviated -h)
• generate --persist-output is now generate --output (abbreviated -o)
• added schemaPullHeaders config value to specify the headers sent when pulling the schema

fixes #398, fixes #428, fixes #325, fixes #242, fixes #395, fixes #353, fixes #460
closes #348, closes #452

[changeset-bot]

🦋 Changeset detected

Latest commit: 5575eae

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[fehnomenal]

Really nice that you start working on it parallel to their development. Keep up the great work 👍

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
docs	✅ Ready (Inspect)	Visit Preview	Aug 25, 2022 at 3:09AM (UTC)
docs-next	✅ Ready (Inspect)	Visit Preview	Aug 25, 2022 at 3:09AM (UTC)

[jycouet]

Looks great to me 🎉

[AlecAivazis]

Okay, i finally got everything building and think this is finally ready to merge. Really appreciate everyone's patience. I think you're really gonna like what we've put together 🎉