Skip to content

Commit c0cbc15

Browse files
CopilotCopilot
authored
docs: Enhance documentation for vike-vue-pinia and vike-vue-query (#213)
1 parent 649292a commit c0cbc15

File tree

4 files changed

+109
-82
lines changed

4 files changed

+109
-82
lines changed

‎examples/vue-pinia/pages/index/+Page.vue‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import TodoList from './TodoList.vue'
2020
2121
const { increment } = useCounterStore()
2222
onServerPrefetch(() => {
23-
// Show that hydration works - the counter should start at 1
23+
// Let the counter start at 1 (and hydration still works)
2424
increment()
2525
})
2626
</script>

‎examples/vue-pinia/pages/index/+onData.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,6 @@ function onData(pageContext: PageContext & { data?: Data }) {
1111

1212
// Saving KBs: we don't need pageContext.data (we use the store instead)
1313
// - If we don't delete pageContext.data then Vike sends pageContext.data to the client-side
14-
// - This optimization only works if the page is SSR'd: if the page is pre-rendered then don't do this
14+
// - This optimization only works with SSR: if the page is pre-rendered then don't do this
1515
if (!pageContext.isPrerendering) delete pageContext.data
1616
}

‎packages/vike-vue-pinia/README.md‎

Lines changed: 44 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,14 @@
77
Integrates [Pinia](https://pinia.vuejs.org) into your [`vike-vue`](https://vike.dev/vike-vue) app.
88

99
[Installation](#installation)
10+
[Basic usage](#basic-usage)
1011
[Example](#example)
1112
[Populate store with `+data`](#populate-store-with-data)
1213
[Version history](#version-history)
1314
[See also](#see-also)
1415

1516
<br/>
1617

17-
## Example
18-
19-
See [examples/vue-pinia](https://github.com/vikejs/vike-vue/tree/main/examples/vue-pinia).
20-
21-
<br/>
22-
2318
## Installation
2419

2520
1. `npm install vike-vue-pinia pinia`
@@ -35,40 +30,58 @@ See [examples/vue-pinia](https://github.com/vikejs/vike-vue/tree/main/examples/v
3530
extends: [vikeVue, vikeVuePinia]
3631
}
3732
```
38-
3. You can now use Pinia in any of your components.
39-
```vue
40-
<template>
41-
<button type="button" @click="counterStore.increment">Counter {{ counterStore.count }}</button>
42-
</template>
43-
44-
<script setup>
45-
import { useCounterStore } from './useCounterStore'
46-
const counterStore = useCounterStore()
47-
</script>
48-
```
49-
```js
50-
import { defineStore } from 'pinia'
51-
import { ref } from 'vue'
52-
53-
export const useCounterStore = defineStore('counter', () => {
54-
const count = ref(0)
55-
const increment = () => count.value++
56-
return { count, increment }
57-
})
58-
```
5933

6034
> [!NOTE]
6135
> The `vike-vue-pinia` extension requires [`vike-vue`](https://vike.dev/vike-vue).
6236
6337
<br/>
6438

39+
# Basic usage
40+
41+
```js
42+
// stores/useCounterStore.ts
43+
44+
import { defineStore } from 'pinia'
45+
import { ref } from 'vue'
46+
47+
export const useCounterStore = defineStore('counter', () => {
48+
const count = ref(0)
49+
const increment = () => count.value++
50+
return { count, increment }
51+
})
52+
```
53+
54+
```vue
55+
<!-- components/Counter.vue -->
56+
57+
<template>
58+
<button type="button" @click="counterStore.increment">
59+
Counter {{ counterStore.count }}
60+
</button>
61+
</template>
62+
63+
<script setup>
64+
import { useCounterStore } from '../stores/useCounterStore'
65+
const counterStore = useCounterStore()
66+
</script>
67+
```
68+
69+
<br/>
70+
71+
## Example
72+
73+
See [examples/vue-pinia/](https://github.com/vikejs/vike-vue/tree/main/examples/vue-pinia).
74+
75+
<br/>
76+
6577
## Populate store with `+data`
6678

6779
To populate your store with data fetched via the [`+data`](https://vike.dev/data) hook, use [`+onData`](https://vike.dev/onData) and [`pageContext.data`](https://vike.dev/pageContext#data).
6880

6981
```ts
7082
// pages/todos/+onData.ts
7183
// Environment: server, client
84+
7285
export { onData }
7386

7487
import type { PageContext } from 'vike/types'
@@ -81,17 +94,17 @@ function onData(pageContext: PageContext & { data?: Data }) {
8194

8295
// Saving KBs: we don't need pageContext.data (we use the store instead)
8396
// - If we don't delete pageContext.data then Vike sends pageContext.data to the client-side
84-
// - This optimization only works if the page is SSR'd: if the page is pre-rendered then don't do this
97+
// - This optimization only works with SSR: if the page is pre-rendered then don't do this
8598
delete pageContext.data
8699
}
87100
```
88101

89-
See To-Do List example at [examples/vue-pinia](https://github.com/vikejs/vike-vue/tree/main/examples/vue-pinia).
102+
See complete To-Do List example at [examples/vue-pinia](https://github.com/vikejs/vike-vue/tree/main/examples/vue-pinia).
90103

91104
> [!NOTE]
92-
> During [SSR](https://vike.dev/ssr), `+onData` is called only on the server. That's because the store state is sent to the client, so that when the page hydrates, the client has the exact same state as the server — preventing [hydration mismatches](https://vike.dev/hydration-mismatch).
105+
> During [SSR](https://vike.dev/ssr), `+onData` is called only on the server — the store's initial state (set by `initTodos()`) is automatically sent to the client, so you don't need to populate the store again on the client.
93106
>
94-
> As a result, the store doesn't need to be populated on the client: it's already populated on the server and then sent to the client.
107+
> This approach prevents [hydration mismatches](https://vike.dev/hydration-mismatch), as it ensures the client has the exact same initial state as the server during SSR.
95108
96109
<br/>
97110

‎packages/vike-vue-query/README.md‎

Lines changed: 63 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,9 @@
77
Integrates [TanStack Query](https://tanstack.com/query) into your [`vike-vue`](https://vike.dev/vike-vue) app.
88

99
[Installation](#installation)
10+
[Basic usage](#basic-usage)
11+
[Example](#example)
1012
[Settings](#settings)
11-
[Example](https://github.com/vikejs/vike-vue/tree/main/examples/vue-query)
1213
[Version history](https://github.com/vikejs/vike-vue/blob/main/packages/vike-vue-query/CHANGELOG.md)
1314
[See also](#see-also)
1415

@@ -30,63 +31,72 @@ Integrates [TanStack Query](https://tanstack.com/query) into your [`vike-vue`](h
3031
extends: [vikeVue, vikeVueQuery]
3132
}
3233
```
33-
3. You can now use TanStack Query in any of your components.
34-
```vue
35-
<template>
36-
<h1>Star Wars Movies</h1>
37-
<ol>
38-
<template v-if="isPending">
39-
<li>Loading...</li>
40-
</template>
41-
<template v-else-if="isError">
42-
<li>Error: {{ error }}</li>
43-
</template>
44-
<template v-else>
45-
<li v-for="item in data!" :key="item.id">
46-
{{ item.title }} ({{ item.release_date }})
47-
</li>
48-
</template>
49-
</ol>
50-
</template>
51-
52-
<script setup>
53-
import { onServerPrefetch } from 'vue'
54-
import { useQuery } from '@tanstack/vue-query'
5534

56-
const { isError, isPending, isFetching, data, error, suspense } = useQuery({
57-
queryKey: ['movies'],
58-
queryFn: fetchMovies,
59-
staleTime: 1000 * 60 * 5,
60-
select: (data) => minimize(data),
61-
})
35+
> [!NOTE]
36+
> The `vike-vue-query` extension requires [`vike-vue`](https://vike.dev/vike-vue).
6237
63-
// This will be called on the server to prefetch the data
64-
onServerPrefetch(suspense)
38+
<br/>
6539

66-
async function fetchMovies() {
67-
const response = await fetch('https://brillout.github.io/star-wars/api/films.json')
68-
const moviesData = (await response.json())
69-
return moviesData
70-
}
40+
# Basic usage
7141

72-
function minimize(movies) {
73-
return movies.map((movie) => {
74-
const { title, release_date, id } = movie
75-
return { title, release_date, id }
76-
})
77-
}
78-
</script>
79-
```
42+
```vue
43+
<template>
44+
<h1>Star Wars Movies</h1>
45+
<ol>
46+
<template v-if="isPending">
47+
<li>Loading...</li>
48+
</template>
49+
<template v-else-if="isError">
50+
<li>Error: {{ error }}</li>
51+
</template>
52+
<template v-else>
53+
<li v-for="item in data!" :key="item.id">
54+
{{ item.title }} ({{ item.release_date }})
55+
</li>
56+
</template>
57+
</ol>
58+
</template>
59+
60+
<script setup>
61+
import { onServerPrefetch } from 'vue'
62+
import { useQuery } from '@tanstack/vue-query'
63+
64+
const { isError, isPending, isFetching, data, error, suspense } = useQuery({
65+
queryKey: ['movies'],
66+
queryFn: fetchMovies,
67+
staleTime: 1000 * 60 * 5,
68+
select: (data) => minimize(data),
69+
})
70+
71+
// This will be called on the server to prefetch the data
72+
onServerPrefetch(suspense)
73+
74+
async function fetchMovies() {
75+
const response = await fetch('https://brillout.github.io/star-wars/api/films.json')
76+
const moviesData = (await response.json())
77+
return moviesData
78+
}
8079
81-
> [!NOTE]
82-
> The `vike-vue-query` extension requires [`vike-vue`](https://vike.dev/vike-vue).
80+
function minimize(movies) {
81+
return movies.map((movie) => {
82+
const { title, release_date, id } = movie
83+
return { title, release_date, id }
84+
})
85+
}
86+
</script>
87+
```
8388

8489
<br/>
8590

91+
## Example
92+
93+
See [examples/vue-query/](https://github.com/vikejs/vike-vue/tree/main/examples/vue-query).
94+
95+
<br/>
8696

8797
## Settings
8898

89-
The query client can receive custom options either by adding `queryClientConfig` to your `+config.ts` or adding a separate `+queryClientConfig.ts` file in your `pages` directory.
99+
You can set TanStack Query client options:
90100

91101
```ts
92102
// pages/+queryClientConfig.ts
@@ -95,19 +105,23 @@ export { queryClientConfig }
95105

96106
import type { QueryClientConfig } from '@tanstack/vue-query'
97107

98-
// Query client options
99108
const queryClientConfig: QueryClientConfig = {
100109
defaultOptions: {
101110
queries: {
111+
// Retry failed requests once
112+
retry: 1,
113+
// Consider data stale after 2 minutes
114+
staleTime: 1000 * 60 * 2,
102115
// Don't refetch when window loses or gains focus during development
103116
refetchOnWindowFocus: import.meta.env.PROD,
104-
staleTime: 1000 * 60 * 2
105117
// ... more options ...
106118
}
107119
}
108120
}
109121
```
110122

123+
For all available options, see [TanStack Query > API reference > useQuery](https://tanstack.com/query/latest/docs/framework/vue/reference/useQuery).
124+
111125
<br/>
112126

113127

0 commit comments

Comments
 (0)