angelocolocado/clcd-agent-skills / skills/rrv7-api-mutation-handler
rrv7-api-mutation-handler
VerifiedUse this skill whenever creating, updating, deleting (data mutations), or integrating non-GET HTTP API requests (POST, PUT, PATCH, DELETE) between a React Router v7 (RRv7) Framework Mode (NO-SSR) frontend and a Laravel backend.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.4 KB |
SKILL.md
View on GitHub---
name: rrv7-api-mutation-handler
description: Use this skill whenever creating, updating, deleting (data mutations), or integrating non-GET HTTP API requests (POST, PUT, PATCH, DELETE) between a React Router v7 (RRv7) Framework Mode (NO-SSR) frontend and a Laravel backend.
---
# RRv7 + Laravel Safe HTTP Mutation Pattern
Follow this strict architecture whenever wiring up backend API mutations so unhandled errors never trigger React Router v7's `ErrorBoundary` or expose sensitive stack traces to the user.
## Strict Implementation Rules
1. **Location:** Always define the handler function inside the **parent route file** of the current view/page.
2. **Naming Convention:** Name the async function `handle<TaskName>(data: any)` in camelCase accepting `data: any` (e.g., `handleCreateOrderIntent(data: any)`, `handleArchiveOrder(data: any)`).
3. **Axios Client & Error Guard:**
- Locate and import the project's pre-configured Axios instance (`api`)—typically found under `~/lib/`, `~/utils/`, or `~/app/util/` (match the project's `tsconfig.json` path alias such as `~/` or `@/`).
- Never use native `fetch` or raw `axios.post()` / `axios.put()` / `axios.delete()` calls.
- Import `axios` from `"axios"` **solely** for the `axios.isAxiosError(err)` type guard.
4. **Toaster (`sonner`):**
- Check if `sonner` / shadcn/ui `Toaster` is installed in the project and import `toast` from `"sonner"`.
- Use `toast.promise()` for async mutations with clear, context-specific `loading`, `success`, and `error` messages.
5. **Try-Catch & Safe Response Contract:**
- Wrap the mutation inside a `try-catch` block. **Never re-throw** errors out of the handler.
- **Inside `try`:** Store the un-awaited Axios call in `const requestPromise = api.<method>(...)`, pass it to `toast.promise()`, and strictly return `{ success: true, data: (await requestPromise).data }`.
- **Inside `catch`:** Use the type-safe guard `if (axios.isAxiosError(err))` to strictly return `{ success: false, code: err.response?.status, data: err.response?.data }`. For non-Axios errors, strictly return `{ success: false }`.
6. **Wiring Up in `clientAction`:**
- In RRv7 Framework Mode (NO-SSR), wire the handler inside `export async function clientAction({ request }: Route.ClientActionArgs)`.
- Extract `formData` via `Object.fromEntries(await request.formData())` and route actions using `switch (data.intent)`.
7. **UI Behavior & State Rendering:** Before modifying or generating the view/component UI that triggers this mutation, load and follow the **`rrv7-mutation-ui-behavior`** skill . This strictly controls functional UI behavior and state-driven rendering (e.g., wiring `useFetcher` or `useActionData`, disabling buttons during pending states, resetting forms/closing dialogs on `success: true`, and rendering Laravel `422` field errors from `data.errors`)—excluding final visual styling or layout design.
## Reference Boilerplate
```typescript
import axios from "axios";
import { toast } from "sonner";
import api from "~/lib/axios"; // Adjust to the project's configured Axios client path
import type { Route } from "./+types/<route-name>"; // Match the current route's generated types
export async function clientAction({ request }: Route.ClientActionArgs) {
if (!["POST", "PUT", "PATCH", "DELETE"].includes(request.method)) {
return null;
}
const formData = await request.formData();
const data = Object.fromEntries(formData);
switch (data.intent) {
case "process-order":
return await handleCreateOrderIntent(data);
default:
return { success: false };
}
}
async function handleCreateOrderIntent(data: any) {
try {
const requestPromise = api.post("/api/v1/order", data);
toast.promise(requestPromise, {
loading: "Processing your order...", // Customize based on task context
success: data?.name
? data.name + " has been successfully processed."
: "Success!", // Customize based on task context
error: (err) =>
(axios.isAxiosError(err) && err.response?.data?.message) ||
"Something went wrong. Please try again later.", // Customize based on task context
});
return {
success: true,
data: (await requestPromise).data,
};
} catch (err) {
if (axios.isAxiosError(err)) {
return {
success: false,
code: err.response?.status,
data: err.response?.data,
};
}
return { success: false };
}
}
```Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |