appflare
Build and modify Appflare backends, the generate-first framework for Cloudflare Workers that compiles a schema DSL plus query/mutation/scheduler/cron/storageManager handlers into a Hono Worker (D1 + D
SKILL.mdskills/appflare/SKILL.md
GitHubAppflare
Recognize the project
An Appflare backend package has:
appflare.config.ts, which setsscanDir(handlers, usually./src),outDir(usually./_generated) andschemaDsl.entry(usually./schema.ts)schema.ts, which exportsschema({...})built fromtable()andv.*- handler files under
scanDirthat import from a relative_generated/handlers _generated/, which is generated output. Never edit it
Frontends import Appflare from the backend's _generated/client and hooks from appflare/react.
Mental model
- You write the schema and handlers.
bun appflare devgenerates the server, handler runtime, typed client, auth schema andwrangler.json.bun appflare migrate --localdiffs the schema into SQL and applies it to D1.wrangler devservesGET /queries/...,POST /mutations/...,/api/auth/*,/storage/*,/realtime/*and/admin.
Default workflow for any change
- Read
appflare.config.tsto findscanDir,outDirand the schema entry - Schema change: edit
schema.ts(load appflare-schema) - Backend logic: add or edit handlers under
scanDir(load appflare-handlers, plus appflare-querying forctx.db) - Regenerate:
bun appflare devfrom the backend package. It must finish without errors - Schema changed:
bun appflare migrate --local - Frontend: call the new route through the generated client (load appflare-client)
- Config, bindings or deploy work: load appflare-cli-deploy
Which skill to load
| Task | Skill |
|---|---|
| Tables, columns, enums, JSON columns, indexes, checks, relations, migrations | appflare-schema |
| query / mutation / scheduler / cron / storageManager, auth checks, errors | appflare-handlers |
ctx.db reads, writes, batch/transaction, aggregates, filters, pagination |
appflare-querying |
new Appflare(), .run(), useQuery/useMutation, realtime, sign-in, uploads |
appflare-client |
appflare.config.ts, CLI commands, wrangler bindings, CORS, deploy |
appflare-cli-deploy |
Gotchas that apply everywhere
- The CLI only runs under Bun. Use
bun appflare <cmd>and nevernode/npx. - Generated code is stale until you regenerate. Missing routes or types usually mean "run
bun appflare dev". - Handlers are discovered only as
export const name = query({...})(or mutation/scheduler/cron/storageManager). Default exports, function declarations and re-exports are ignored. - Route and client names come from file paths:
src/posts.ts#listPostsbecomesappflare.queries.posts.listPosts. A leadingqueries/ormutations/folder is dropped. - Relations create FK fields named
<relation>Id. Filter and insert withownerId, and read the related row withwith: { owner: true }. - Query args arrive as URL strings and are converted to what the zod schema expects, so plain
z.boolean(),z.number()andz.array()work in aquery. ctx.dbis strict:findManydefaults to 100 rows, unknownwherekeys throw, andupdate/deleteneed a filter (orallowAll: true).ctx.dbwrites are atomic, andctx.db.batch/ctx.db.transactionextend that across tables.ctx.$dbremains the raw Drizzle escape hatch.- Unhandled errors return a sanitized 500. Use
ctx.error(status, message)for anything the client should read. ctx.useris typed non-null but isnullfor anonymous requests unlessauthRequired: true, and alwaysnullin scheduler/cron.- JSON responses turn
Dateinto ISO strings on the client.