agentleFS
ahpxexahpxex/open-dashboard/.claude/skills/add-backend/SKILL.md

add-backend

Skill136 starsChanged 5 months agoMITView on GitHub

Everything about the data layer — pick one of six ready-to-run backend templates (TanStack Start + Drizzle + better-auth, Hono + Drizzle + better-auth, Hono + Prisma + better-auth, Hono + Drizzle + Auth.js/NextAuth, FastAPI + SQLAlchemy + JWT, Supabase) and wire the frontend to it through the Repository + AuthProvider seams; scaffold a CRUD resource (Postgres table + server fns + query hooks + DataTable page + create/edit dialog + sidebar entry); bind or swap one resource's data source (Drizzle / REST / GraphQL / in-memory); or re-point the whole app's data + auth at a different backend. Use when adding a data entity or pointing the app at a backend other than the default Postgres + better-auth.

  • Reads credentials

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. microsoft/Copilot-Managed-Runtime★ 10same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository4 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 1 is distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Routing rule: use add-backend whenever a screen needs its own data (a new entity/table, or a different backend).

    line 12
  2. Very specific:

    Read references/<preset>.md (Add it / Foundation / Invariants / Verify).

    line 54
  3. Distinctive:

    Verify end-to-end (the reference's Verify block).

    line 59
  4. Very specific:

    Keep numeric form fields non-coercing in *FormSchema (input must match the form value type).

    line 81
  5. Very specific:

    Every server-fn handler calls requireUser() first and validates input via .validator((data) => zodSchema.parse(data)) (an arrow wrapper, …

    line 96
  6. Very specific:

    Every page archetype is written against Repository<T, TInput> (src/infra/data/repository.ts), so swapping a resource's backend touches only …

    line 114
  7. Very specific:

    Always provide a unit test mocking the transport (fetch / db) — see rest-repository.test.ts, graphql-repository.test.ts, …

    line 152
  8. Very specific:

    Keep the server seam server-only: auth-provider.ts may import DB/SDK clients, so it must only be reached from require-user, the api route, …

    line 259

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Add a backend (resources, data sources & presets)

The app is backend-agnostic by design: it reaches data and auth only through two seams, so adding a resource, swapping one resource's data source, or re-pointing the whole app at a different backend are all localized operations.

Routing rule: use add-backend whenever a screen needs its own data (a new entity/table, or a different backend); use add-component when composing UI on top of data that already exists.

ConcernSeamDefault presetSwap point
Business data (resources)Repository<T, TInput> (@/infra/data/repository)Postgres via drizzleRepository; in-memory when no DBeach resource's server.ts binding
Auth (server)AuthProvider (@/lib/auth-provider)better-auth (betterAuthProvider)the authProvider binding
Auth (browser)@/lib/auth-clientbetter-auth React clientreimplement that one file

Zero-config (bun dev, no DATABASE_URL) already runs on in-memory presets, so you can build UI before wiring a real backend. Full guides: docs/data-adapters.md, docs/backends.md.

Backend presets — ready-to-run templates

Six runnable backend templates ship in this skill's templates/<preset>/ (generated from the repo's backends/ source and contract-tested — templates/<preset>/README.md

  • a shared CONTRACT.md). Pick one as the project's backend; each connects to the dashboard frontend through the two seams above — no page, query, table, or form changes — and each is independently verified.
PresetStackFrontend wiringReference
tanstack-drizzle-betterauthTanStack Start server fns + Drizzle + better-auth (in-process — the default)none — it is the scaffoldreferences/tanstack-drizzle-betterauth.md
hono-drizzle-betterauthHono + Drizzle + better-auth (standalone TS service)restRepository + remoteBetterAuthProviderreferences/hono-drizzle-betterauth.md
hono-prisma-betterauthHono + Prisma + better-auth (standalone TS service)restRepository + remoteBetterAuthProvider (same as Drizzle)references/hono-prisma-betterauth.md
hono-drizzle-authjsHono + Drizzle + Auth.js / NextAuth v5 (standalone TS service)restRepository + remoteAuthjsProvider + authjs clientreferences/hono-drizzle-authjs.md
fastapi-sqlalchemy-jwtFastAPI + SQLAlchemy + JWT (standalone Python service)restRepository + externalJwtAuthProviderreferences/fastapi-sqlalchemy-jwt.md
supabaseSupabase Postgres + Auth (BaaS — SQL + config)supabaseRepository + Supabase AuthProvider (copy-ready)references/supabase.md

The HTTP-API presets (the hono-* services + fastapi) all speak one shared wire contract, so their frontend auth providers ship pre-wired and typechecked in the base under src/lib/auth-providers/ (externalJwtAuthProvider, remoteBetterAuthProvider, remoteAuthjsProvider) — activating is a one-line swap. Supabase needs the Supabase SDKs, so its wiring ships as copy-ready files in templates/supabase/frontend-wiring/.

Stack matrix: framework (TanStack / Hono / FastAPI / Supabase) × ORM (Drizzle / Prisma / SQLAlchemy) × auth (better-auth / Auth.js / custom-JWT / Supabase). The presets are the idiomatic, verified combinations — not a blind cartesian product.

To stand up a preset:

  1. Read references/<preset>.md (Add it / Foundation / Invariants / Verify).
  2. Copy the template out as the service (cp -R templates/<preset> <dest>); follow its README to run it (zero-config: SQLite + a dev secret, one install + one run command).
  3. Wire the frontend: bind the resource's server.ts to the preset's Repository adapter (§2) and point authProvider at the preset's AuthProvider (§3).
  4. Verify end-to-end (the reference's Verify block).

The numbered sections below are the building blocks these presets compose: add a resource (§1), bind/swap a data source (§2), swap the auth preset (§3).

1. Add a CRUD resource

The CRUD table is the base archetype. products is the canonical reference; orders is a generated example.

  1. Generate the vertical (table + feature + route + sidebar entry, auto-formatted):
    bun run create-resource <plural-name>   # e.g. customers
    This creates src/features/<name>/{schema,server,demo-data,queries,columns,config}.ts(x) and the route src/routes/_app/<name>.tsx, appends a Drizzle table to src/db/schema.ts, and inserts a sidebar item. Like products, the generated server.ts binds drizzleRepository when DATABASE_URL is set and falls back to memoryRepository over demo-data.ts otherwise — so the new resource runs under zero-config bun dev (no database) before you ever migrate.
  2. Customise the fields in src/db/schema.ts (the appended pgTable) and in src/features/<name>/schema.ts (the zod input / form / list-params schemas). Keep numeric form fields non-coercing in *FormSchema (input must match the form value type); the server *InputSchema may coerce. Filter params that can be numeric must use z.coerce.string() (the router JSON-parses search params).
  3. Adjust columns.tsx (cells, sortable columns), config.ts (filters, search placeholder), the server.ts repository config (searchColumns / sortColumns / filterColumns on the drizzle branch, and the matching searchFields / sortFields / filterFields on the memory branch), and the seed rows in demo-data.ts.
  4. Migrate (only on Postgres — zero-config dev needs no DB): bun run db:generate && bun run db:migrate.
  5. Verify: bun run typecheck && bun run check && bun run test, then open /<name> (it lists the demo-data.ts rows with no DB).

Resource invariants (must hold)

  • Every server-fn handler calls requireUser() first and validates input via .validator((data) => zodSchema.parse(data)) (an arrow wrapper, not a bare zodSchema.parse method reference).
  • List state lives in the URL (validateSearch + useTableSearch); never local useState.
  • Mutations show a toast and invalidate the resource's query keys; deletes go through useConfirm().
  • The repository binding lives in server.ts (server-only): drizzleRepository from @/infra/data/drizzle-repository behind hasDatabase, with a memoryRepository fallback for zero-config dev — never imported from a client component.
  • The page wraps DataTable in a full-height flex column — <div className="flex h-full flex-col gap-6"> with the header as shrink-0 — so the pagination bar pins to the bottom (the shell sizes each page to the viewport). The generator emits this; keep it.

2. Bind / swap a resource's data source

Every page archetype is written against Repository<T, TInput> (src/infra/data/repository.ts), so swapping a resource's backend touches only its server.ts binding — queries.ts, columns.tsx, the table/detail/form, and the route do not change.

Adapters:

  • Drizzle (Postgres) — drizzleRepository(table, config) from @/infra/data/drizzle-repository (import directly; server-only). Backs products/orders.
  • In-memory — memoryRepository(seed, config). The zero-config default; backs every demo when DATABASE_URL is unset.
  • REST — restRepository({ baseUrl, path, map, … }) from @/infra/data. Backs posts (jsonplaceholder). Defaults target json-server (_page/_limit/_sort/_order/q + x-total-count); override params / totalHeader for other shapes.
  • GraphQL — graphqlRepository({ endpoint, map, operations }) from @/infra/data. Each op supplies a document + variable builder + extractor.

To back a resource with REST/GraphQL (no DB table needed):

  1. Define the resource's type + zod schemas.
  2. In server.ts, build the repository with the right adapter and a map from the raw API record to your type; wrap each op in a createServerFn handler that calls requireUser() (the fetch stays server-side, so API keys never reach the client):
    export const widgetsRepository = restRepository<Widget, WidgetInput>({
      baseUrl: process.env.WIDGETS_API_URL!,
      path: "/widgets",
      map: (raw) => ({ ...raw }),
    });
  3. Map the resource's flat list params to the repository's filters (toListParams). Numeric filter params → z.coerce.string().

Data-source invariants

  • Adapters run only inside server fns. The @/infra/data barrel is isomorphic-safe (no @/db); the Drizzle adapter is imported from its own path.
  • Always provide a unit test mocking the transport (fetch / db) — see rest-repository.test.ts, graphql-repository.test.ts, drizzle-repository.test.ts.

3. Swap the whole-app backend + auth preset

Two classes of data, two different rules:

  • Business data (your resources) — swap per resource via the Repository adapter in server.ts (section 2).
  • Platform data (users/sessions, later RBAC) — owned by the auth preset; swap it via AuthProvider (server) + @/lib/auth-client (browser).

Implement AuthProvider and point authProvider at it. The contract:

export interface AuthProvider {
  getSession(headers: Headers): Promise<AuthSession | null>; // AuthSession = { user: { id; email; name; image? } }
  handler(request: Request): Promise<Response>;              // serves /api/auth/*
}

For the bundled presets these now ship as real files — activate, don't hand-write. src/lib/auth-providers/external-jwt.ts (externalJwtAuthProvider, custom-JWT like the FastAPI preset) and src/lib/auth-providers/remote-better-auth.ts (remoteBetterAuthProvider, remote better-auth like the Hono preset) are pre-wired and typechecked; the Supabase provider is copy-ready in templates/supabase/frontend-wiring/auth-provider.ts. The examples below show the shape behind those files.

Example: Supabase auth provider

// src/lib/auth-provider.ts (replace betterAuthProvider). bun add @supabase/ssr
import { createServerClient, parseCookieHeader } from "@supabase/ssr";

export const supabaseAuthProvider: AuthProvider = {
  async getSession(headers) {
    const cookies = parseCookieHeader(headers.get("cookie") ?? "");
    const supabase = createServerClient(
      process.env.SUPABASE_URL!,
      process.env.SUPABASE_ANON_KEY!,
      { cookies: { getAll: () => cookies } },
    );
    const { data } = await supabase.auth.getUser();
    if (!data.user) return null;
    return {
      user: {
        id: data.user.id,
        email: data.user.email ?? "",
        name: data.user.user_metadata?.name ?? data.user.email ?? "",
      },
    };
  },
  // Supabase auth runs client-side; no /api/auth/* routes to serve.
  handler: async () => new Response("Not found", { status: 404 }),
};

export const authProvider: AuthProvider = supabaseAuthProvider;

Then reimplement @/lib/auth-client with Supabase's browser client, exporting the same signIn / signUp / signOut / useSession surface the auth pages use.

Example: external-API (JWT) auth provider

// src/lib/auth-provider.ts (replace betterAuthProvider)
export const externalApiAuthProvider: AuthProvider = {
  async getSession(headers) {
    const cookie = headers.get("cookie") ?? "";
    const token = /(?:^|;\s*)session=([^;]+)/.exec(cookie)?.[1];
    if (!token) return null;
    const res = await fetch(`${process.env.AUTH_API_URL}/me`, {
      headers: { authorization: `Bearer ${token}` },
    });
    if (!res.ok) return null;
    const u = await res.json();
    return { user: { id: String(u.id), email: u.email, name: u.name } };
  },
  // Proxy login/logout to the upstream API (set the session cookie on success).
  handler: async (request) => {
    const hasBody = request.method !== "GET" && request.method !== "HEAD";
    return fetch(
      `${process.env.AUTH_API_URL}/auth${new URL(request.url).pathname.replace("/api/auth", "")}`,
      {
        method: request.method,
        headers: request.headers,
        // Buffer the body before forwarding. Passing the raw `request.body`
        // ReadableStream to Node/undici's fetch requires `duplex: "half"` and
        // still can't be retried; reading it to a string sidesteps both.
        body: hasBody ? await request.text() : undefined,
      },
    );
  },
};

export const authProvider: AuthProvider = externalApiAuthProvider;

A different SQL engine (MySQL/SQLite/Turso) needs no preset swap — Drizzle supports them; see docs/backends.md for the files to touch.

Preset invariants

  • The app reaches auth ONLY via authProvider (server) and @/lib/auth-client (browser). Never call a specific auth SDK from a route or component.
  • getSession returns the normalized AuthSession ({ user: { id, email, name } }) so requireUser, the _app guard, and the route context are backend-neutral.
  • Keep the server seam server-only: auth-provider.ts may import DB/SDK clients, so it must only be reached from require-user, the api route, and the dynamic import in auth-server — never statically from a client-reachable module.

Verify

bun run typecheck && bun run check && bun run test (and bun run build for an auth-preset swap), then bun run dev: open /<name> and confirm list/paginate/filter/search work; for an auth swap, an unauthenticated request to / redirects to /login, sign-in works, and a protected page loads its data.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.