Skip to content

Commit 2cd92ef

Browse files
lachlancollinsTkDodo
lachlancollins
and
TkDodo
authored
docs(svelte-query): Rework SvelteKit setup (#4811)
* Add some default options * Rewrite hydration example * Run prettier * Rename example to SSR * Add recommended SvelteKit setup * Rework infinite scroll in sveltekit * Add SvelteKit note to overview * Switch basic example to sveltekit Co-authored-by: Dominik Dorfmeister <office@dorfmeister.cc>
1 parent 3a3d871 commit 2cd92ef

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

86 files changed

+498
-514
lines changed

‎docs/config.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -720,6 +720,10 @@
720720
"label": "Auto Refetching / Polling / Realtime",
721721
"to": "svelte/examples/svelte/auto-refetching"
722722
},
723+
{
724+
"label": "SSR",
725+
"to": "svelte/examples/svelte/ssr"
726+
},
723727
{
724728
"label": "Optimistic Updates in TypeScript",
725729
"to": "svelte/examples/svelte/optimistic-updates-typescript"
@@ -735,10 +739,6 @@
735739
{
736740
"label": "Infinite Queries",
737741
"to": "svelte/examples/svelte/load-more-infinite-scroll"
738-
},
739-
{
740-
"label": "Hydration",
741-
"to": "svelte/examples/svelte/hydration"
742742
}
743743
]
744744
}

‎docs/svelte/overview.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@ Then call any function (e.g. createQuery) from any component:
4747
</div>
4848
```
4949

50+
## SvelteKit
51+
52+
If you are using SvelteKit, please have a look at [SSR & SvelteKit](./ssr).
53+
5054
## Available Functions
5155

5256
Svelte Query offers useful functions and components that will make managing server state in Svelte apps easier.
@@ -67,3 +71,4 @@ Svelte Query offers useful functions and components that will make managing serv
6771
Svelte Query offers an API similar to React Query, but there are some key differences to be mindful of.
6872

6973
- Many of the functions in Svelte Query return a Svelte store. To access values on these stores reactively, you need to prefix the store with a `$`. You can learn more about Svelte stores [here](https://svelte.dev/tutorial/writable-stores).
74+
- If your query or mutation depends on variables, you must assign it reactively. You can read more about this [here](./reactivity).

‎docs/svelte/ssr.md‎

Lines changed: 34 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,39 @@ id: overview
33
title: SSR and SvelteKit
44
---
55

6-
Svelte Query supports two ways of prefetching data on the server and passing that to the client with SvelteKit.
6+
## Setup
77

8-
## Caveat
8+
SvelteKit defaults to rendering routes with SSR. Because of this, you need to disable the query on the server. Otherwise, your query will continue executing on the server asynchronously, even after the HTML has been sent to the client.
99

10-
SvelteKit defaults to rendering routes with SSR. Unless you are using one of the below solutions, you need to disable the query on the server. Otherwise, your query will continue executing on the server asynchronously, even after the HTML has been sent to the client.
10+
The recommended way to achieve this is to use the `browser` module from SvelteKit in your `QueryClient` object. This will not disable `queryClient.prefetchQuery()`, which is used in one of the solutions below.
1111

12-
One way to achieve this is to `import { browser } from '$app/environment'` and add `enabled: browser` to the options of `createQuery`. This will set the query to disabled on the server, but enabled on the client.
12+
```markdown
13+
<script lang="ts">
14+
import { browser } from '$app/environment'
15+
import { QueryClient } from '@tanstack/svelte-query'
16+
17+
const queryClient = new QueryClient({
18+
defaultOptions: {
19+
queries: {
20+
enabled: browser,
21+
},
22+
},
23+
})
24+
</script>
1325

14-
Another way to achieve this is using page options. For that page or layout, you should set `export const ssr = false` in either `+page.ts` or `+layout.ts`. You can read more about using this option [here](https://kit.svelte.dev/docs/page-options#ssr).
26+
<QueryClientProvider client={queryClient}>
27+
<slot />
28+
</QueryClientProvider>
29+
```
1530

16-
## Using `initialData`
31+
## Prefetching data
32+
33+
Svelte Query supports two ways of prefetching data on the server and passing that to the client with SvelteKit.
34+
35+
If you wish to view the ideal SSR setup, please have a look at the [SSR example](../examples/svelte/ssr).
36+
37+
38+
### Using `initialData`
1739

1840
Together with SvelteKit's [`load`](https://kit.svelte.dev/docs/load), you can pass the data loaded server-side into `createQuery`'s' `initialData` option:
1941

@@ -54,11 +76,12 @@ Cons:
5476
- If you are calling `createQuery` with the same query in multiple locations, you need to pass `initialData` to all of them
5577
- There is no way to know at what time the query was fetched on the server, so `dataUpdatedAt` and determining if the query needs refetching is based on when the page loaded instead
5678

57-
## Using `prefetchQuery`
79+
### Using `prefetchQuery`
5880

5981
Svelte Query supports prefetching queries on the server. Using this setup below, you can fetch data and pass it into QueryClientProvider before it is sent to the user's browser. Therefore, this data is already available in the cache, and no initial fetch occurs client-side.
6082

6183
**src/routes/+layout.ts**
84+
6285
```ts
6386
import { QueryClient } from '@tanstack/svelte-query'
6487
import type { LayoutLoad } from './$types'
@@ -70,6 +93,7 @@ export const load: LayoutLoad = async () => {
7093
```
7194

7295
**src/routes/+layout.svelte**
96+
7397
```markdown
7498
<script lang="ts">
7599
import { QueryClientProvider } from '@tanstack/svelte-query'
@@ -84,6 +108,7 @@ export const load: LayoutLoad = async () => {
84108
```
85109

86110
**src/routes/+page.ts**
111+
87112
```ts
88113
import type { PageLoad } from './$types'
89114

@@ -97,6 +122,7 @@ export const load: PageLoad = async ({ parent }) => {
97122
```
98123

99124
**src/routes/+page.svelte**
125+
100126
```markdown
101127
<script lang="ts">
102128
import { createQuery } from '@tanstack/svelte-query'
@@ -117,4 +143,4 @@ Pros:
117143
Cons:
118144

119145
- Requires more files for initial setup
120-
- Works with only `+page.ts`/`+layout.ts` load functions
146+
- Will not work with `+page.server.ts`/`+layout.server.ts` load functions (however, APIs which are used with TanStack Query need to be fully exposed to the browser anyway)

‎examples/svelte/auto-refetching/package.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,16 @@
11
{
22
"name": "@tanstack/query-example-svelte-auto-refetching",
3-
"version": "0.0.1",
43
"private": true,
4+
"version": "0.0.1",
5+
"type": "module",
56
"scripts": {
67
"dev": "vite dev",
78
"build": "vite build",
89
"preview": "vite preview",
910
"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json"
1011
},
1112
"dependencies": {
12-
"@tanstack/svelte-query": "^4.12.0"
13+
"@tanstack/svelte-query": "^4.20.0"
1314
},
1415
"devDependencies": {
1516
"@sveltejs/adapter-auto": "^1.0.0",
@@ -19,6 +20,5 @@
1920
"tslib": "^2.4.1",
2021
"typescript": "^4.7.4",
2122
"vite": "^4.0.0"
22-
},
23-
"type": "module"
23+
}
2424
}

‎examples/svelte/auto-refetching/src/routes/+layout.svelte‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,15 @@
11
<script lang="ts">
22
import '../app.css'
3+
import { browser } from '$app/environment'
34
import { QueryClientProvider, QueryClient } from '@tanstack/svelte-query'
45
5-
const queryClient = new QueryClient()
6+
const queryClient = new QueryClient({
7+
defaultOptions: {
8+
queries: {
9+
enabled: browser,
10+
},
11+
},
12+
})
613
</script>
714

815
<QueryClientProvider client={queryClient}>

‎examples/svelte/auto-refetching/src/routes/+layout.ts‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎examples/svelte/basic/.gitignore‎

Lines changed: 7 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,9 @@
1-
# Logs
2-
logs
3-
*.log
4-
npm-debug.log*
5-
yarn-debug.log*
6-
yarn-error.log*
7-
pnpm-debug.log*
8-
lerna-debug.log*
9-
1+
.DS_Store
102
node_modules
11-
dist
12-
dist-ssr
13-
*.local
3+
/build
4+
/.svelte-kit
5+
/package
6+
.env
7+
.env.*
8+
!.env.example
149
!lib/
15-
16-
# Editor directories and files
17-
.vscode
18-
.idea
19-
.DS_Store
20-
*.suo
21-
*.ntvs*
22-
*.njsproj
23-
*.sln
24-
*.sw?

‎examples/svelte/basic/README.md‎

Lines changed: 24 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,38 @@
1-
# Svelte + TS + Vite
1+
# create-svelte
22

3-
This template should help get you started developing with Svelte and TypeScript in Vite.
3+
Everything you need to build a Svelte project, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/master/packages/create-svelte).
44

5-
## Recommended IDE Setup
5+
## Creating a project
66

7-
[VS Code](https://code.visualstudio.com/) + [Svelte](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode).
7+
If you're seeing this, you've probably already done this step. Congrats!
88

9-
## Need an official Svelte framework?
9+
```bash
10+
# create a new project in the current directory
11+
npm create svelte@latest
1012

11-
Check out [SvelteKit](https://github.com/sveltejs/kit#readme), which is also powered by Vite. Deploy anywhere with its serverless-first approach and adapt to various platforms, with out of the box support for TypeScript, SCSS, and Less, and easily-added support for mdsvex, GraphQL, PostCSS, Tailwind CSS, and more.
12-
13-
## Technical considerations
14-
15-
**Why use this over SvelteKit?**
16-
17-
- It brings its own routing solution which might not be preferable for some users.
18-
- It is first and foremost a framework that just happens to use Vite under the hood, not a Vite app.
19-
`vite dev` and `vite build` wouldn't work in a SvelteKit environment, for example.
20-
21-
This template contains as little as possible to get started with Vite + TypeScript + Svelte, while taking into account the developer experience with regards to HMR and intellisense. It demonstrates capabilities on par with the other `create-vite` templates and is a good starting point for beginners dipping their toes into a Vite + Svelte project.
22-
23-
Should you later need the extended capabilities and extensibility provided by SvelteKit, the template has been structured similarly to SvelteKit so that it is easy to migrate.
24-
25-
**Why `global.d.ts` instead of `compilerOptions.types` inside `jsconfig.json` or `tsconfig.json`?**
13+
# create a new project in my-app
14+
npm create svelte@latest my-app
15+
```
2616

27-
Setting `compilerOptions.types` shuts out all other types not explicitly listed in the configuration. Using triple-slash references keeps the default TypeScript setting of accepting type information from the entire workspace, while also adding `svelte` and `vite/client` type information.
17+
## Developing
2818

29-
**Why include `.vscode/extensions.json`?**
19+
Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
3020

31-
Other templates indirectly recommend extensions via the README, but this file allows VS Code to prompt the user to install the recommended extension upon opening the project.
21+
```bash
22+
npm run dev
3223

33-
**Why enable `allowJs` in the TS template?**
24+
# or start the server and open the app in a new browser tab
25+
npm run dev -- --open
26+
```
3427

35-
While `allowJs: false` would indeed prevent the use of `.js` files in the project, it does not prevent the use of JavaScript syntax in `.svelte` files. In addition, it would force `checkJs: false`, bringing the worst of both worlds: not being able to guarantee the entire codebase is TypeScript, and also having worse typechecking for the existing JavaScript. In addition, there are valid use cases in which a mixed codebase may be relevant.
28+
## Building
3629

37-
**Why is HMR not preserving my local component state?**
30+
To create a production version of your app:
3831

39-
HMR state preservation comes with a number of gotchas! It has been disabled by default in both `svelte-hmr` and `@sveltejs/vite-plugin-svelte` due to its often surprising behavior. You can read the details [here](https://github.com/rixo/svelte-hmr#svelte-hmr).
32+
```bash
33+
npm run build
34+
```
4035

41-
If you have state that's important to retain within a component, consider creating an external store which would not be replaced by HMR.
36+
You can preview the production build with `npm run preview`.
4237

43-
```ts
44-
// store.ts
45-
// An extremely simple external store
46-
import { writable } from 'svelte/store'
47-
export default writable(0)
48-
```
38+
> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.

‎examples/svelte/basic/index.html‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎examples/svelte/basic/package.json‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11
{
22
"name": "@tanstack/query-example-svelte-basic",
33
"private": true,
4-
"version": "0.0.0",
4+
"version": "0.0.1",
55
"type": "module",
66
"scripts": {
7-
"dev": "vite",
7+
"dev": "vite dev",
88
"build": "vite build",
99
"preview": "vite preview",
10-
"check": "svelte-check --tsconfig ./tsconfig.json"
10+
"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json"
1111
},
1212
"dependencies": {
13-
"@tanstack/svelte-query": "^4.12.0"
13+
"@tanstack/svelte-query": "^4.20.0"
1414
},
1515
"devDependencies": {
16-
"@sveltejs/vite-plugin-svelte": "^2.0.2",
17-
"@tsconfig/svelte": "^3.0.0",
16+
"@sveltejs/adapter-auto": "^1.0.0",
17+
"@sveltejs/kit": "^1.0.0",
1818
"svelte": "^3.54.0",
1919
"svelte-check": "^2.9.2",
2020
"tslib": "^2.4.1",

0 commit comments

Comments
 (0)