Skip to content

Beautiful Open-Source Form Builder

7.7 KB
Raw Blame
---
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()`