Beautiful Open-Source Form Builder
---
description: Nuxt client side, API and TanStack Query patterns for data fetching, caching, and state management. Use when needed to change how data is fetched from back-end, or when working with @/api modules, @/composables/query files, cache invalidation, SSR data fetching, or TanStack Query implementation.
globs:
alwaysApply: false
---
# API & TanStack Query Guidelines
> **Scope** – These rules cover _front-end server-state management_ in the Nuxt client. They do **not** address UI-only state (handled by Pinia) nor back-end Laravel endpoints.
---
## 1. Two-Layer Approach
| Layer | Folder | Responsibility |
| --------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------ |
| **API functions** | `client/api/*` | Thin wrappers around `$fetch` that talk to the REST API. No caching, no Vue code. |
| **Query composables** | `client/composables/query/*` | Wrap API calls with TanStack Query for caching, mutations, optimistic updates, and invalidation. |
> Example mapping – `client/api/workspace.js` ↔︎ `client/composables/query/useWorkspaces.js`
---
## 2. Query Composable Conventions
1. **Expose factories, not results** – Each composable returns methods (`list()`, `detail(id)`, `create()`, …). The caller decides _when_ to register the query/mutation.
2. **Query keys** – Use predictable, hierarchical keys:
- List: `["workspaces", "list"]`
- Item: `["workspaces", id]`
3. **Cache writes after mutations** – Inside `onSuccess` use `queryClient.setQueryData` to update affected caches, then call `invalidate()` only when a true refetch is needed.
4. **URL parameters in mutations** – Pass URL parameters (like IDs) when creating the mutation, not when executing it. Use `toValue()` to handle reactive values.
5. **Utilities** – Provide at minimum `invalidate()` (call `queryClient.invalidateQueries({ queryKey: [domain] })`).
### Handling Reactive Parameters
Use `toValue()` when working with reactive values (refs, computed) in mutations and queries:
```js
const update = (workspaceId, options = {}) => {
return useMutation({
mutationFn: (data) => workspaceApi.update(toValue(workspaceId), data),
onSuccess: (response) => {
const id = toValue(workspaceId);
// Update caches using the resolved ID...
},
...options,
});
};
// Usage in component:
const { current: workspace } = useCurrentWorkspace();
const updateMutation = update(workspace.value.id); // ID passed at creation
```
---
## 3. Usage in Components
```vue
<script setup>
// Queries
const { list } = useWorkspaces();
const { data: workspaces, isLoading, isError } = list();
// Mutations (Promise-based)
const { create } = useWorkspaces();
const createWorkspace = create();
const onSubmit = (form) => {
createWorkspace
.mutateAsync(form)
.then(() => useAlert().success("Created"))
.catch((err) => useAlert().error(err.message));
};
</script>
<template>
<div v-if="isLoading">Loading…</div>
<div v-else-if="isError">Failed to load</div>
<ul v-else>
<li v-for="ws in workspaces" :key="ws.id">{{ ws.name }}</li>
</ul>
<UButton :loading="createWorkspace.isPending" @click="onSubmit(form)"
>Create</UButton
>
</template>
```
### Why `.mutateAsync().then().catch()`?
It keeps control flow explicit, works with native Promises, and avoids `try/catch` inside template methods.
---
## 4. SSR & Suspense
During SSR we sometimes need the data _before_ HTML is streamed. TanStack Query offers `.suspense()` on every query:
```js
// middleware/client/middleware/01.check-auth.global.js (excerpt)
await Promise.all([
useAuth().user().suspense(),
useWorkspaces().list().suspense(),
]);
```
`<Suspense>` blocks in Vue templates are discouraged – prefer awaiting in middleware or `serverPrefetch`.
---
## 5. Authentication Plumbing
`client/composables/useOpnApi.js` injects `Authorization: Bearer <token>` automatically (token is stored in cookies). The `01.check-auth.global.js` middleware initializes the store and pre-loads user + workspace data on navigation.
You normally **don’t** need to add headers manually.
---
## 6. Common Pitfalls
| ❌ Anti-pattern | ✅ Fix |
| -------------------------------------------- | -------------------------------------------------------- |
| Creating queries inside `watch` / `computed` | Call composables at top level; use `enabled` when needed |
| Mixing UI state in TanStack cache | Keep UI state in Pinia |
| Broad `queryClient.invalidateQueries()` | Use domain-level `invalidate()` |
---
## 7. Form Integration with TanStack Query
Forms in OpnForm (`@/composables/lib/vForm/Form.js`) provide a higher-level abstraction for handling form state, validation, and submission. They integrate seamlessly with TanStack Query mutations:
### When to Use Forms
**Use `Form` class when:**
- You need comprehensive form state management (busy, successful, recentlySuccessful)
- Form has client-side or server-side validation
- You need built-in error extraction and display
- User needs visual feedback during submission (loading states, success messages)
**Use direct TanStack Query when:**
- Simple data operations without validation
- No complex form state management needed
- Direct server-state management is sufficient
### Form + Mutation Integration
Pass a TanStack Query mutation to `form.mutate()` or `form.mutateAsync()`:
```js
// Create mutation from a query composable
const { update } = useWorkspaces();
const updateMutation = update(workspaceId);
// Use it with form
const form = useForm({ name: "My Workspace" });
const handleSubmit = () => {
form.mutate(updateMutation)
.then((response) => {
useAlert().success("Updated!");
// Handle success (redirect, cache invalidation, etc.)
})
.catch((error) => {
// Form automatically handles validation errors
// error.data contains extracted validation failures
if (error.response?.status !== 422) {
useAlert().error("Something went wrong");
}
});
};
```
### Form State Lifecycle
1. **`form.busy`** – True while mutation is pending
2. **`form.successful`** – True after successful mutation
3. **`form.recentlySuccessful`** – Auto-reverts to false after 2s (for UI feedback like "Saved!" messages)
4. **`form.errors`** – Populated automatically from validation responses
### Key Benefits of Form Class
| Feature | Form Class | Direct Mutation |
| ------------------ | ----------------------------------- | ------------------ |
| Loading state | ✅ Automatic `form.busy` | Manual `isPending` |
| Error extraction | ✅ Auto-extracts from response | Manual parsing |
| Validation support | ✅ Built-in precognition | Via TanStack Query |
| Success feedback | ✅ `form.recentlySuccessful` | Manual state |
| File uploads | ✅ Automatic FormData serialization | Manual handling |
---
## 8. Checklist for New Composables
- [ ] Map 1-to-1 with an API module
- [ ] Provide `list`, `detail`, and the necessary mutations
- [ ] Use consistent query keys
- [ ] Pass URL parameters at mutation creation time, not execution time
- [ ] Use `toValue()` for reactive parameters (refs, computed)
- [ ] Handle optimistic cache updates in `onSuccess`
- [ ] Expose `invalidate()`