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.
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
- Location: Always define the handler function inside the parent route file of the current view/page.
- Naming Convention: Name the async function
handle<TaskName>(data: any)in camelCase acceptingdata: any(e.g.,handleCreateOrderIntent(data: any),handleArchiveOrder(data: any)). - 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'stsconfig.jsonpath alias such as~/or@/). - Never use native
fetchor rawaxios.post()/axios.put()/axios.delete()calls. - Import
axiosfrom"axios"solely for theaxios.isAxiosError(err)type guard.
- Locate and import the project's pre-configured Axios instance (
- Toaster (
sonner):- Check if
sonner/ shadcn/uiToasteris installed in the project and importtoastfrom"sonner". - Use
toast.promise()for async mutations with clear, context-specificloading,success, anderrormessages.
- Check if
- Try-Catch & Safe Response Contract:
- Wrap the mutation inside a
try-catchblock. Never re-throw errors out of the handler. - Inside
try: Store the un-awaited Axios call inconst requestPromise = api.<method>(...), pass it totoast.promise(), and strictly return{ success: true, data: (await requestPromise).data }. - Inside
catch: Use the type-safe guardif (axios.isAxiosError(err))to strictly return{ success: false, code: err.response?.status, data: err.response?.data }. For non-Axios errors, strictly return{ success: false }.
- Wrap the mutation inside a
- Wiring Up in
clientAction:- In RRv7 Framework Mode (NO-SSR), wire the handler inside
export async function clientAction({ request }: Route.ClientActionArgs). - Extract
formDataviaObject.fromEntries(await request.formData())and route actions usingswitch (data.intent).
- In RRv7 Framework Mode (NO-SSR), wire the handler inside
- UI Behavior & State Rendering: Before modifying or generating the view/component UI that triggers this mutation, load and follow the
rrv7-mutation-ui-behaviorskill . This strictly controls functional UI behavior and state-driven rendering (e.g., wiringuseFetcheroruseActionData, disabling buttons during pending states, resetting forms/closing dialogs onsuccess: true, and rendering Laravel422field errors fromdata.errors)—excluding final visual styling or layout design.
Reference Boilerplate
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: 319k | 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: 196k | 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: 196k | 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: 196k | Updated | Claude CodeCodex | Verified | Install |