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
- microsoft/Copilot-Managed-Runtimetheir own version, first seen Nov 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 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.
- CLAUDE.mdCLAUDE.md
- add-componentSkill
- rebrandSkill
- scaffold-dashboardSkill
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
- Very specific: line 12
Routing rule: use add-backend whenever a screen needs its own data (a new entity/table, or a different backend).
- Very specific: line 54
Read references/<preset>.md (Add it / Foundation / Invariants / Verify).
- Distinctive: line 59
Verify end-to-end (the reference's Verify block).
- Very specific: line 81
Keep numeric form fields non-coercing in *FormSchema (input must match the form value type).
- Very specific: line 96
Every server-fn handler calls requireUser() first and validates input via .validator((data) => zodSchema.parse(data)) (an arrow wrapper, …
- Very specific: line 114
Every page archetype is written against Repository<T, TInput> (src/infra/data/repository.ts), so swapping a resource's backend touches only …
- Very specific: line 152
Always provide a unit test mocking the transport (fetch / db) — see rest-repository.test.ts, graphql-repository.test.ts, …
- Very specific: line 259
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, …
≈ “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.
Files
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.
| Concern | Seam | Default preset | Swap point |
| Business data (resources) | Repository<T, TInput> (@/infra/data/repository) | Postgres via drizzleRepository; in-memory when no DB | each resource's server.ts binding |
| Auth (server) | AuthProvider (@/lib/auth-provider) | better-auth (betterAuthProvider) | the authProvider binding |
| Auth (browser) | @/lib/auth-client | better-auth React client | reimplement 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.
| Preset | Stack | Frontend wiring | Reference |
tanstack-drizzle-betterauth | TanStack Start server fns + Drizzle + better-auth (in-process — the default) | none — it is the scaffold | references/tanstack-drizzle-betterauth.md |
hono-drizzle-betterauth | Hono + Drizzle + better-auth (standalone TS service) | restRepository + remoteBetterAuthProvider | references/hono-drizzle-betterauth.md |
hono-prisma-betterauth | Hono + Prisma + better-auth (standalone TS service) | restRepository + remoteBetterAuthProvider (same as Drizzle) | references/hono-prisma-betterauth.md |
hono-drizzle-authjs | Hono + Drizzle + Auth.js / NextAuth v5 (standalone TS service) | restRepository + remoteAuthjsProvider + authjs client | references/hono-drizzle-authjs.md |
fastapi-sqlalchemy-jwt | FastAPI + SQLAlchemy + JWT (standalone Python service) | restRepository + externalJwtAuthProvider | references/fastapi-sqlalchemy-jwt.md |
supabase | Supabase 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:
- Read
references/<preset>.md(Add it / Foundation / Invariants / Verify). - 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). - Wire the frontend: bind the resource's
server.tsto the preset'sRepositoryadapter (§2) and pointauthProviderat the preset'sAuthProvider(§3). - 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.
- Generate the vertical (table + feature + route + sidebar entry, auto-formatted):
This createsbun run create-resource <plural-name> # e.g. customerssrc/features/<name>/{schema,server,demo-data,queries,columns,config}.ts(x)and the routesrc/routes/_app/<name>.tsx, appends a Drizzle table tosrc/db/schema.ts, and inserts a sidebar item. Likeproducts, the generatedserver.tsbindsdrizzleRepositorywhenDATABASE_URLis set and falls back tomemoryRepositoryoverdemo-data.tsotherwise — so the new resource runs under zero-configbun dev(no database) before you ever migrate. - Customise the fields in
src/db/schema.ts(the appendedpgTable) and insrc/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*InputSchemamay coerce. Filter params that can be numeric must usez.coerce.string()(the router JSON-parses search params). - Adjust
columns.tsx(cells, sortable columns),config.ts(filters, search placeholder), theserver.tsrepository config (searchColumns/sortColumns/filterColumnson the drizzle branch, and the matchingsearchFields/sortFields/filterFieldson the memory branch), and the seed rows indemo-data.ts. - Migrate (only on Postgres — zero-config dev needs no DB):
bun run db:generate && bun run db:migrate. - Verify:
bun run typecheck && bun run check && bun run test, then open/<name>(it lists thedemo-data.tsrows 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 barezodSchema.parsemethod reference). - List state lives in the URL (
validateSearch+useTableSearch); never localuseState. - Mutations show a toast and invalidate the resource's query keys; deletes go
through
useConfirm(). - The repository binding lives in
server.ts(server-only):drizzleRepositoryfrom@/infra/data/drizzle-repositorybehindhasDatabase, with amemoryRepositoryfallback for zero-config dev — never imported from a client component. - The page wraps
DataTablein a full-height flex column —<div className="flex h-full flex-col gap-6">with the header asshrink-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). Backsproducts/orders. - In-memory —
memoryRepository(seed, config). The zero-config default; backs every demo whenDATABASE_URLis unset. - REST —
restRepository({ baseUrl, path, map, … })from@/infra/data. Backsposts(jsonplaceholder). Defaults target json-server (_page/_limit/_sort/_order/q+x-total-count); overrideparams/totalHeaderfor 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):
- Define the resource's type + zod schemas.
- In
server.ts, build the repository with the right adapter and amapfrom the raw API record to your type; wrap each op in acreateServerFnhandler that callsrequireUser()(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 }), }); - 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/databarrel 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
Repositoryadapter inserver.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) andsrc/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 intemplates/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. getSessionreturns the normalizedAuthSession({ user: { id, email, name } }) sorequireUser, the_appguard, and the route context are backend-neutral.- Keep the server seam server-only:
auth-provider.tsmay import DB/SDK clients, so it must only be reached fromrequire-user, the api route, and the dynamic import inauth-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.
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
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.

