@wisemen/vue-core-api-utils
Version:
197 lines (152 loc) • 5.2 kB
Markdown
name: getting-started
description: >
Install @wisemen/vue-core-api-utils, initialize apiUtilsPlugin with QueryClient config, register typed query keys via module augmentation, set up a typed QueryClient wrapper.
type: lifecycle
library: vue-core-api-utils
# @wisemen/vue-core-api-utils — Getting Started
Get `@wisemen/vue-core-api-utils` installed, your Vue Query plugin initialized, query keys registered, and a typed QueryClient created.
## Setup
### 1. Install the package
```bash
pnpm install @wisemen/vue-core-api-utils @tanstack/vue-query neverthrow vue
```
### 2. Register your query keys via module augmentation
Augment the `Register` interface to define your query keys and error codes:
```typescript
// src/types/queryKey.type.ts
import type { Contact } from '@/models'
declare module '@wisemen/vue-core-api-utils' {
interface Register {
queryKeys: {
contactDetail: {
entity: Contact
params: { contactUuid: string }
}
contactList: {
entity: Contact[]
params: { search?: string }
}
contactListKeyset: {
entity: Contact[]
params: { search?: string }
}
}
errorCodes: 'NOT_FOUND' | 'UNAUTHORIZED' | 'VALIDATION_ERROR'
}
}
```
Every key must have `entity` (response type) and `params` (filter/identifier parameters). Do not include pagination fields in params — those are handled by the infinite query composables.
### 3. Initialize the plugin in your main.ts
```typescript
// main.ts
import { createApp } from 'vue'
import { apiUtilsPlugin } from '@wisemen/vue-core-api-utils'
import App from './App.vue'
const app = createApp(App)
app.use(apiUtilsPlugin({
defaultOptions: {
queries: {
staleTime: 1000 * 60 * 5, // 5 minutes
retry: 1,
},
},
}))
app.mount('#app')
```
The `apiUtilsPlugin` creates a QueryClient with your config and handles @tanstack/vue-query setup internally.
### 4. Create your API module
```typescript
// src/api/index.ts
import type {
ApiResult as ApiUtilsApiResult,
KeysetPaginationResult as ApiUtilsKeysetPaginationResult,
OffsetPaginationResult as ApiUtilsOffsetPaginationResult,
} from '@wisemen/vue-core-api-utils'
import {
QueryClient,
getTanstackQueryClient,
useQuery,
useMutation,
useOffsetInfiniteQuery,
useKeysetInfiniteQuery,
} from '@wisemen/vue-core-api-utils'
// Re-export composables for convenience
export {
useQuery,
useMutation,
useOffsetInfiniteQuery,
useKeysetInfiniteQuery,
}
// Create a typed QueryClient helper
export function useQueryClient() {
return new QueryClient(getTanstackQueryClient())
}
// Export typed result types
export type ApiResult<T> = ApiUtilsApiResult<T>
export type OffsetPaginationResult<T> = ApiUtilsOffsetPaginationResult<T>
export type KeysetPaginationResult<T> = ApiUtilsKeysetPaginationResult<T>
```
Composables are imported directly from the package. The `QueryClient` is a type-safe wrapper around the Tanstack QueryClient — its types are inferred from your `Register` augmentation.
## Core Patterns
### Create a detail query composable
```typescript
// src/composables/useContactDetail.ts
import { computed } from 'vue'
import { useQuery } from '@/api'
import { ContactService } from '@/services'
export function useContactDetail(contactUuid: string) {
return useQuery('contactDetail', {
params: { contactUuid: computed(() => contactUuid) },
queryFn: () => ContactService.getByUuid(contactUuid),
staleTime: 1000 * 60 * 5,
})
}
```
Parameters must be computed refs so the query watches changes and refetches automatically.
### Create a mutation composable
```typescript
// src/composables/useCreateContact.ts
import { useMutation } from '@/api'
import { ContactService } from '@/services'
export function useCreateContact() {
return useMutation({
queryFn: async ({ body }: { body: ContactCreateForm }) => {
return await ContactService.create(body)
},
queryKeysToInvalidate: {
contactList: {},
},
})
}
```
Every mutation should list which queries to invalidate via `queryKeysToInvalidate`. An empty object `{}` invalidates all queries with that key.
### Use composables in components
```vue
<script setup lang="ts">
import { useContactDetail } from '@/composables'
const props = defineProps<{ contactUuid: string }>()
const { result, refetch } = useContactDetail(props.contactUuid)
</script>
<template>
<div>
<div v-if="result.isLoading()">Loading...</div>
<div v-else-if="result.isOk()">
Name: {{ result.getValue().name }}
</div>
<div v-else-if="result.isErr()">
Error occurred
</div>
<button @click="refetch">Retry</button>
</div>
</template>
```
All queries and mutations return `AsyncResult` with three states: loading, ok, and err.
## You're all set!
You now have:
- ✅ Plugin initialized with Vue Query
- ✅ Query keys registered via module augmentation
- ✅ Typed QueryClient wrapper created
- ✅ Error codes enumerated
Head to [writing-queries](../writing-queries/SKILL.md) to fetch your first resource, or [asyncresult-handling](../asyncresult-handling/SKILL.md) to understand the three-state AsyncResult type.