Skip to main content

:::warning AUTO-GENERATED — do not edit This page is generated from the MCP server snapshot content/guide-mcp.json. Edit the source MCP server (not this file), then run npm run generate. :::

Add a data table backed by a real API

When to use: You want to display a list/collection of records from a backend service in a sortable table.

Prerequisites​

  • Completed discover-api for the target endpoint.

Steps​

Step 1: Confirm the endpoint and capture its response schema.​

Tools: get_endpoint_details, validate_endpoint

Step 2: Create types that mirror the response schema exactly (only real fields).​

Step 3: Create a service function using request<T>() and toast.promise().​

Step 4: Get the approved table template and install its shadcn dependency.​

Tools: get_component_template, get_shadcn_components

Step 5: Create the route and load data with TanStack Query (no useEffect).​

Step 6: ALWAYS render a <Skeleton> loading state (table row skeletons) while the query is pending.​

Tools: get_shadcn_components

Step 7: Create a co-located .test.tsx next to the table component covering loading, empty, and populated states.​

Step 8: Append this component to the checklist so unchecked items are tracked.​

Step 9: Run the quality gate.​

Full recipe definition​

The complete machine-readable recipe as returned by the MCP server:

{
  "id": "add-data-table",
  "title": "Add a data table backed by a real API",
  "when": "You want to display a list/collection of records from a backend service in a sortable table.",
  "prerequisites": [
    "Completed `discover-api` for the target endpoint."
  ],
  "steps": [
    {
      "action": "Confirm the endpoint and capture its response schema.",
      "tools": [
        "get_endpoint_details",
        "validate_endpoint"
      ]
    },
    {
      "action": "Create types that mirror the response schema exactly (only real fields).",
      "files": [
        "src/types/{domain}.ts"
      ],
      "note": "Use `type`, not `interface`. Do NOT add fields that were not in the schema."
    },
    {
      "action": "Create a service function using `request<T>()` and `toast.promise()`.",
      "files": [
        "src/lib/{domain}.ts"
      ],
      "note": "BASE = gateway path from `get_gateway_pattern`. Never raw fetch/axios."
    },
    {
      "action": "Get the approved table template and install its shadcn dependency.",
      "tools": [
        "get_component_template",
        "get_shadcn_components"
      ],
      "note": "get_component_template name='DataTable'. Then run `npx shadcn@latest add table`."
    },
    {
      "action": "Create the route and load data with TanStack Query (no useEffect).",
      "files": [
        "src/routes/_authenticated/{domain}.tsx"
      ],
      "note": "createFileRoute + useQuery({ queryKey, queryFn: () => fetch{Domain}() }). Columns come from the real schema fields."
    },
    {
      "action": "ALWAYS render a `<Skeleton>` loading state (table row skeletons) while the query is pending.",
      "tools": [
        "get_shadcn_components"
      ],
      "files": [
        "src/components/{feature}/{domain}Table.tsx"
      ],
      "note": "npx shadcn@latest add skeleton. Show <Skeleton> rows for isLoading, and an error boundary/empty state otherwise."
    },
    {
      "action": "Create a co-located `.test.tsx` next to the table component covering loading, empty, and populated states.",
      "files": [
        "src/components/{feature}/{domain}Table.test.tsx"
      ],
      "note": "Same folder as the component. Assert the Skeleton renders while loading and real rows render once data resolves."
    },
    {
      "action": "Append this component to the checklist so unchecked items are tracked.",
      "files": [
        "COMPONENT_CHECKLIST.md"
      ],
      "note": "Add a `- [ ] {domain}Table — Skeleton + test` line; check items off only once the Skeleton and test exist."
    },
    {
      "action": "Run the quality gate.",
      "note": "npm run verify — see recipe `run-verify-gate`."
    }
  ],
  "filesToCreate": [
    "src/types/{domain}.ts",
    "src/lib/{domain}.ts",
    "src/routes/_authenticated/{domain}.tsx",
    "src/components/{feature}/{domain}Table.test.tsx",
    "COMPONENT_CHECKLIST.md"
  ],
  "validation": [
    "`npm run verify` passes.",
    "Table columns correspond 1:1 to real response fields (no invented columns).",
    "Loading and error states are handled (skeleton + error boundary).",
    "A `<Skeleton>` loading state and a co-located `.test.tsx` exist for the table."
  ],
  "doneCriteria": [
    "verify green",
    "Rows render from the live service (or a typed empty state) — no hardcoded rows.",
    "The table ships with a `<Skeleton>` loading state and a co-located `.test.tsx`, and is listed in COMPONENT_CHECKLIST.md."
  ],
  "commonMistakes": [
    "Inventing columns/fields not present in the schema.",
    "Fetching in useEffect instead of TanStack Query.",
    "Hardcoding sample rows to fake completeness.",
    "Using axios or raw fetch instead of `request<T>()`.",
    "Shipping a table with no Skeleton loading state or no co-located test."
  ],
  "relatedRecipes": [
    "discover-api",
    "add-filters",
    "run-verify-gate"
  ]
}