create-aron-app 0.1.6 → 0.1.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-aron-app",
-  "version": "0.1.6",
-  "description": "Scaffold a new Convex + Next.js + Clerk full-stack project",
+  "version": "0.1.8",
+  "description": "Scaffold a new Convex + React Router + Clerk full-stack project",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -12,8 +12,11 @@
     "templates"
   ],
   "scripts": {
-    "build": "bun build src/index.ts --target=node --outfile=dist/index.js --minify && echo '#!/usr/bin/env node' | cat - dist/index.js > /tmp/create-tmp.js && mv /tmp/create-tmp.js dist/index.js && chmod +x dist/index.js",
+    "build": "bun build src/index.ts --target=node --outfile=dist/index.js --minify --external giget && echo '#!/usr/bin/env node' | cat - dist/index.js > /tmp/create-tmp.js && mv /tmp/create-tmp.js dist/index.js && chmod +x dist/index.js",
     "start": "bun run src/index.ts",
+    "start:local": "bun run src/index.ts --local",
+    "template": "bun run build && bun run start",
+    "template:local": "bun run build && bun run start:local",
     "release": "npm version patch && npm publish --access public",
     "prepublishOnly": "bun run build"
   },
@@ -33,7 +36,7 @@
     "create",
     "template",
     "convex",
-    "nextjs",
+    "react-router",
     "clerk",
     "nx",
     "monorepo"

package/templates/.cursor/rules/backend.mdc

@@ -0,0 +1,112 @@
+---
+description: Convex backend in apps/api — ents, zQuery/zMutation, CRUD layout, auth, and platform conventions that apply alongside project wrappers.
+globs: templates/apps/api/**/*.ts,apps/api/**/*.ts
+alwaysApply: false
+---
+
+# Backend API (`apps/api`)
+
+Convex backend using **convex-ents**, **`zQuery` / `zMutation`** from `@/api/functions`, and **Zod** (`z.*`, `zid()`) for public function args — not raw `v.*` validators on public handlers.
+
+---
+
+## Layout
+
+```
+apps/api/
+├── <entity>/
+│   ├── schema.ts    # ent definition (table + edges + indexes)
+│   ├── types.ts     # Zod schemas + TS types
+│   └── crud.ts      # queries/mutations (GET → UPDATE → CREATE → DELETE)
+├── schema.ts        # spreads all entity ents
+├── types.ts         # shared context types
+├── functions.ts     # zQuery / zMutation wrappers
+└── auth.config.ts   # JWT providers (required for ctx.auth)
+```
+
+Example entity (`todos/`): `schema.ts`, `types.ts`, `crud.ts`.
+
+### New entity checklist
+
+1. Add `apps/api/<entity>/schema.ts` → export `<entity>Ents`
+2. Add `types.ts` — Zod input/output shapes
+3. Add `crud.ts` — `zQuery` / `zMutation` handlers
+4. Spread ents in `apps/api/schema.ts` via `defineEntSchema`
+
+---
+
+## Schema (`schema.ts` per entity)
+
+- Export `{ tableName: defineEnt({...}).edge(...).index(...) }`
+- Index names include all indexed fields, e.g. `by_user_id`
+- Prefer **indexes** for lookups; avoid unbounded `filter` scans in production code
+
+---
+
+## Types (`types.ts`)
+
+- Zod schemas and inferred types live here, not in ent schema files
+- Use `zodToConvex` from convex-helpers when bridging Zod → Convex validators
+
+---
+
+## CRUD (`crud.ts`)
+
+Order functions: **GET → UPDATE → CREATE → DELETE**.
+
+- Authenticate with `ctx.auth.getUserIdentity()`; resolve the app user as your schema requires
+- **Never** take `userId` from the client for authorization — derive from auth context
+- Prefer **`identity.tokenIdentifier`** for stable auth-linked lookups (not `subject` alone)
+- Use **`ConvexError`** for business errors; messages stay concise
+- For expected present/missing entity semantics: **`getX` / `get`**, **`uniqueX` / `unique`** — no redundant null checks after `getX`
+
+### Ent helpers
+
+| API | Use when |
+|-----|----------|
+| `getX(id)` | Row must exist |
+| `get(id)` | Row may be missing |
+| `uniqueX` / `firstX` | Index query must yield exactly one / at least one |
+
+### Edge patterns
+
+```typescript
+const related = await entity.edge("relatedEntity");
+return { ...entity, related };
+```
+
+Standard update:
+
+```typescript
+const { entityId, ...updates } = args;
+const entity = await ctx.table("entities").getX(entityId);
+return entity.patch(updates);
+```
+
+---
+
+## Documentation style
+
+- **No** JSDoc on every exported function — names should read clearly
+- **Only** inline comments for non-obvious business rules
+
+---
+
+## Convex platform notes (template-wide)
+
+These apply to any `query`/`mutation`/`action` code; **this repo’s public API should still use `zQuery`/`zMutation`** per above.
+
+- Register **internal** functions with `internalQuery` / `internalMutation` / `internalAction` — never expose sensitive ops as public `query`/`mutation`
+- **Actions**: add `"use node"` only in files that need Node builtins; **never** mix `"use node"` with queries/mutations in the same file
+- **Pagination**: use `paginationOptsValidator` and `.paginate()` for large lists — avoid unbounded `.collect()` on big tables
+- **Scheduling**: only schedule **internal** function references
+- **Queries**: do not use `Date.now()` in query logic if it should be reactive/cached predictably
+- **DB**: no `.collect().length` for counts at scale — denormalize or bound reads
+
+For HTTP routes in Convex, use `httpRouter` + `httpAction` and register exact paths.
+
+---
+
+## Client imports
+
+Frontend code imports **`Doc` / `Id`** only through per-entity **`types.ts` aliases** (e.g. `Todo`, `TodoId`). Do not use `Ent<T>` outside the backend.

package/templates/.cursor/rules/coding_standards.mdc

@@ -0,0 +1,145 @@
+---
+description: Project-wide coding standards covering import ordering, naming conventions, code style, and testing policy. Apply across all TypeScript/TSX files.
+globs: **/*.ts,**/*.tsx
+---
+
+# Coding Standards
+
+## Naming Conventions
+
+### Functions
+- Use verb + noun: `getEntity`, `updateEntity`, `createEntity`, `deleteEntity`
+- Be specific when needed: `getEntityByEmail`, `updateEntityField`
+- Avoid abbreviations unless widely understood
+- Avoid verbose qualifiers: prefer `updateEntity` over `updateEntityCoreDetails`
+
+### Fields
+- `camelCase` for all field names
+- Use `userId` — not `clerkId` or other provider-specific names
+
+### Variables
+- Keep names concise and descriptive
+- Use singular for single items (`todo`, `entity`) and plural for collections (`todos`, `entities`)
+- Destructure to extract IDs: `const { entityId, ...updates } = args;`
+
+### Zod Schemas
+
+The inferred type and the schema constant must share the same PascalCase name. Declare the type **above** the const. This applies to both API and web code:
+
+```typescript
+// Good
+export type CreateConversationInput = z.infer<typeof CreateConversationInput>;
+export const CreateConversationInput = z.object({
+  title: z.string().min(1).max(120),
+});
+
+// Bad — mismatched names, type below const
+export const createConversationSchema = z.object({ title: z.string() });
+export type CreateConversationInput = z.infer<typeof createConversationSchema>;
+```
+
+## Code Style
+
+### Formatting
+- Single blank line between functions
+- No blank lines at the start or end of a function body
+- 2-space indentation
+- Trailing commas in multi-line arrays and objects
+
+### Class Spacing
+
+Each member of a class (property, accessor, or method) must be separated by a blank line. Decorators go on their own line above the member. Never inline a method body — always expand to a full block:
+
+```typescript
+// Good
+export class FooController {
+  @observable.ref
+  accessor isOpen = false;
+
+  @observable.ref
+  accessor selectedId: string | undefined = undefined;
+
+  @computed
+  get label() {
+    return this.isOpen ? "Close" : "Open";
+  }
+
+  @action
+  open(id: string) {
+    this.selectedId = id;
+    this.isOpen = true;
+  }
+}
+
+// Bad — inlined bodies, missing blank lines, stacked decorator
+export class FooController {
+  @observable.ref accessor isOpen = false;
+  @observable.ref accessor selectedId: string | undefined = undefined;
+  @computed get label() { return this.isOpen ? "Close" : "Open"; }
+  @action open(id: string) { this.selectedId = id; this.isOpen = true; }
+}
+```
+
+### No Expression Nesting
+
+Never pass an awaited call or a complex expression directly as an argument. Extract to a named variable first:
+
+```typescript
+// Good
+const user = await getUser(userId);
+await sendWelcomeEmail(user);
+
+// Bad
+await sendWelcomeEmail(await getUser(userId));
+```
+
+### Block Statements
+
+Always use block bodies (`{ }`). This is enforced by Biome (`useBlockStatements`). No single-line `if`/`throw`, no expression-body arrow callbacks:
+
+```typescript
+// Good
+if (!conversation) {
+  throw new Error("Not found");
+}
+
+onSubmit={() => {
+  controller.submit({ id: bootstrap.id });
+}}
+
+// Bad
+if (!conversation) throw new Error("Not found");
+
+onSubmit={() => controller.submit({ id: bootstrap.id })}
+```
+
+### Conditional Logic
+
+Prefer concise conditionals — avoid unnecessary intermediate variables:
+
+```typescript
+// Good
+const count = entity.limit ?? 0;
+if (count <= 0) {
+  throw new Error("Limit reached");
+}
+
+// Bad
+const remaining = entity.limit ?? 0;
+if (!entity.limit || entity.limit <= 0) {
+  throw new Error("Limit reached");
+}
+```
+
+### Async / Await
+- Always `await` async operations — never fire-and-forget unless intentional
+- Use `Promise.all()` for independent parallel operations
+
+### Validation
+- Validate business rules before any database operation
+- Centralise reusable validation in `@/utils/`
+- Keep CRUD files thin — validation logic belongs in utils
+
+## Testing
+
+Test files **should not** be created unless explicitly requested. Focus on implementation quality over test coverage.

package/templates/.cursor/rules/frontend_architecture.mdc

@@ -0,0 +1,334 @@
+---
+description: Web frontend — surface architecture (MobX + React Router + Convex + Clerk SSR). Layers, routing, data loading, Convex/React Query wiring, and component conventions.
+globs: templates/apps/web/**/*.tsx,templates/apps/web/**/*.ts,apps/web/**/*.tsx,apps/web/**/*.ts
+alwaysApply: false
+---
+
+# Frontend architecture — React Router + Convex
+
+Audience: engineers working on `apps/web` (or `templates/apps/web` in this repo).
+
+This stack uses **surfaces** (vertical slices), **MobX** for UI state, **Convex** for data, and **SSR loaders** with `ConvexHttpClient` + Clerk. An older **v2** ruleset documented a Hono BFF + `api` client; this project does **not** use that pattern — use Convex queries/mutations and the paths below instead.
+
+---
+
+## Philosophy
+
+1. **Display components are dumb** — props in, JSX out. No data fetching, no surface state, no controller imports.
+2. **`create.tsx` factories are smart closures** — they close over controller/bootstrap at wiring time and return an `observer()` component. This is the only layer that bridges MobX and React hooks.
+3. **Controllers are the brain** — a MobX class owns cross-section UI state (dialogs, selection). No React imports.
+
+**Why explicit wiring instead of React Context?** Context hides the dependency graph. Here, access is traceable: surface → `install` → `create` → display. No surprise re-renders or ambiguous state ownership.
+
+**Why not add Zustand?** MobX plus optional `GlobalProvider` already cover reactive UI state; Convex plus TanStack Query cover server state — avoid a third paradigm.
+
+---
+
+## Layer stack
+
+```
+routes/.../[page].tsx     →  server loader + clientLoader; passes loaderData as bootstrap
+bootstrap.ts              →  ConvexHttpClient query only (SSR); no browser APIs
+[feature].tsx             →  surface entry: useRef install guard, useMemo(createLayout)
+install.tsx               →  instantiate controller; dynamic import() of section creates
+layout.tsx                →  LayoutController + observer shell + skeleton slots
+[feature]_controller.ts   →  MobX — shared UI state; may call convex.mutation
+[section]_presenter.ts    →  MobX — section-scoped logic (optional)
+[section]/create.tsx      →  factory → observer; useQuery + convexQuery + initialData
+[section]/[section].tsx   →  pure display (`useFormContext` exception for forms)
+ui/                       →  dumb components scoped to this surface
+```
+
+---
+
+## Folder and naming
+
+```
+src/surfaces/todos/
+  all_todos/                 # list surface
+  single_todo/               # id-scoped surface
+```
+
+- File names: **snake_case**
+- Factory/install args: `Opts` suffix — `InstallSingleTodoOpts`
+- Component props: `Props` suffix — `MainProps`
+- List surfaces: **`All`** prefix — `AllTodos`
+- Id surfaces: **`Single`** prefix — `SingleTodo`
+- CRUD UI folders: `new_`, `edit_`, `delete_` — never `create_` (conflicts with `create.tsx` pattern)
+- Display component names must **not** repeat the parent path — inside `single_todo/header/`, export `Header`, not `SingleTodoHeader`
+- Imports: **`@/...` only** — no relative imports within features
+
+---
+
+## Setup — MobX (Stage 3)
+
+Requires TypeScript 5+ with `experimentalDecorators: false` and Babel decorators in Vite:
+
+```json
+{ "compilerOptions": { "experimentalDecorators": false } }
+```
+
+```typescript
+react({ babel: { plugins: [["@babel/plugin-proposal-decorators", { version: "2023-05" }]] } })
+```
+
+- Use `accessor` on `@observable` fields
+- Prefer `@action` methods — mutations after `await` inside an `@action async` are safe without `runInAction`
+- Use `@observable.ref` for component slot fields on layout controllers
+
+---
+
+## Setup — Convex and React Query
+
+**Convex React client** (browser, `expectAuth: true`) and **ConvexQueryClient** live in `@/web/libs/convex_query_client`:
+
+```typescript
+import { convex, convexQueryClient } from "@/web/libs/convex_query_client";
+```
+
+**TanStack Query client** is `@/web/libs/react_query_client` — it connects `convexQueryClient` and sets default `queryFn`. Use this singleton anywhere you need a `QueryClient` on the client.
+
+**Presenters and controllers** call mutations outside React via the same `convex` singleton:
+
+```typescript
+import { convex } from "@/web/libs/convex_query_client";
+import { api } from "@/api/_generated/api";
+
+await convex.mutation(api.todos.crud.updateTodo, args);
+```
+
+**Creates** use `useQuery` with `convexQuery` from `@convex-dev/react-query` and **`initialData` from bootstrap** so the first paint matches SSR.
+
+---
+
+## Global state (three tiers)
+
+| Tier | Mechanism | When |
+|------|-----------|------|
+| Module `stores/` | Plain module variable | One-shot, non-reactive handoff across navigation |
+| `GlobalProvider` | React context + `useGlobal()` | Reactive state across `<Outlet />` (use sparingly) |
+| MobX controller | `[feature]_controller.ts` | All UI state inside a surface |
+
+Module store rules: consume-once helpers, one concern per file, document lifetime at top, never for persistence alone.
+
+---
+
+## Routing and auth
+
+**Route config** (`src/routes.ts`) uses route groups `(auth)` and `(dashboard)`. URLs come from `layout`/`prefix`/`route`, not folder names.
+
+Example shape (adjust files to match your app):
+
+```typescript
+import { index, layout, prefix, type RouteConfig, route } from "@react-router/dev/routes";
+
+export default [
+  layout("./routes/(auth)/layout.tsx", [route("/sign-in/*", "./routes/(auth)/sign-in/index.tsx")]),
+  layout("./routes/(dashboard)/layout.tsx", [
+    index("./routes/(dashboard)/index.tsx"),
+    ...prefix("todos", [
+      layout("./routes/(dashboard)/(todos)/layout.tsx", [
+        index("./routes/(dashboard)/(todos)/index.tsx"),
+        route(":id", "./routes/(dashboard)/(todos)/[id].tsx"),
+      ]),
+    ]),
+  ]),
+] satisfies RouteConfig;
+```
+
+**Middleware** (`root.tsx`): Clerk + a protected-route middleware enforce auth for non-public paths before loaders run.
+
+**`root.tsx`**: providers (`ApiAuthProvider`, `GlobalProvider`, …) + `<Outlet />` — no feature sidebar here.
+
+**Dashboard layout**: shell only (e.g. `SidebarProvider`, `Sidebar`, `Outlet`).
+
+**Router types**: import `Route` from `./+types/...` adjacent to the route file (or the generated types path your tsconfig uses).
+
+---
+
+## SSR data loading (loaders + bootstrap)
+
+Flow:
+
+1. **Server** — route `loader` builds an authenticated `ConvexHttpClient` and runs bootstrap.
+2. **Client** — `clientLoader` returns `serverLoader()` only — no second fetch.
+3. **Hydration** — `useQuery({ ...convexQuery(...), initialData: bootstrap.* })` so the live subscription takes over.
+
+### Auth helper — `src/libs/server/auth.ts`
+
+Single place for loader-time Convex HTTP client + redirect if unauthenticated:
+
+```typescript
+import { getAuth } from "@clerk/react-router/server";
+import { ConvexHttpClient } from "convex/browser";
+import type { LoaderFunctionArgs } from "react-router";
+import { redirect } from "react-router";
+
+export const createConvexClient = async (args: LoaderFunctionArgs): Promise<ConvexHttpClient> => {
+  const auth = await getAuth(args);
+  if (!auth.isAuthenticated) {
+    throw redirect(`/sign-in?redirect_url=${encodeURIComponent(args.request.url)}`);
+  }
+  const token = await auth.getToken({ template: "convex" });
+  const client = new ConvexHttpClient(process.env.VITE_CONVEX_URL!);
+  if (token) {
+    client.setAuth(token);
+  }
+  return client;
+};
+```
+
+Use `getToken({ template: "convex" })` (not the default session token). In server loaders use `process.env.VITE_CONVEX_URL` (not `import.meta.env`).
+
+### Bootstrap — `surfaces/.../bootstrap.ts`
+
+- Accept `{ client: ConvexHttpClient }` from the route loader
+- Use `client.query(api...)` only — no `ConvexReactClient`, `convexQuery`, or `ensureQueryData` in bootstrap
+- May `throw redirect(...)` for invalid params
+
+### Route module
+
+```typescript
+export async function loader(args: Route.LoaderArgs) {
+  const client = await createConvexClient(args);
+  return bootstrapAllTodos({ client });
+}
+
+export async function clientLoader({ serverLoader }: Route.ClientLoaderArgs) {
+  return serverLoader();
+}
+
+export default function Page({ loaderData: bootstrap }: Route.ComponentProps) {
+  return <AllTodos bootstrap={bootstrap} />;
+}
+```
+
+### Client `create.tsx`
+
+```typescript
+const { data: todos } = useQuery({
+  ...convexQuery(api.todos.crud.listTodos, {}),
+  initialData: bootstrap.todos as never,
+});
+```
+
+Spread `convexQuery` first, then `initialData`. The `as never` cast is often needed for serialized vs local types.
+
+### Anti-patterns
+
+| Wrong | Right |
+|-------|--------|
+| `clientLoader` calling `ensureQueryData(convexQuery(...))` for SSR | Server `loader` + `clientLoader` → `serverLoader()` |
+| Building `ConvexHttpClient` inside bootstrap | Receive `client` from `createConvexClient` |
+| Duplicating Clerk redirects in every bootstrap | Centralize in `createConvexClient` / middleware |
+
+---
+
+## Shell vs pages
+
+- **Layout-mounted** (e.g. sidebar): `useEffect(() => installSidebar(...), [])` once.
+- **Route-mounted** pages: synchronous **`useRef` install guard** on first render (avoids empty flash; StrictMode-safe).
+
+---
+
+## Surface entry (`[feature].tsx`)
+
+- Receives **`bootstrap` from the route** — never fetch the primary payload inside the surface
+- `useMemo(() => createLayout(), [])` once
+- `useRef` guard calls `installFeature({ layout, bootstrap, navigate })` synchronously on first run
+- Obtain `useNavigate` (and similar) here and **pass into `install`**, not inside `install` itself
+
+---
+
+## `install.tsx`
+
+- **New `Controller()` here** — exactly once; shared across all `create` closures
+- Use dynamic `import()` per section for code splitting
+- Plain function — not a hook, not a component
+- Do not use React Context to replace explicit controller passing
+
+---
+
+## `layout.tsx`
+
+- `LayoutController` holds `@observable.ref` slots for `ComponentType`
+- `@action` setters for slots; observer shell renders skeletons until slots load
+
+---
+
+## Controllers and presenters
+
+- **Controller**: cross-section UI state; `convex.mutation` / `convex.query` when needed; **no React**
+- **Presenter**: one section’s logic; same rules — **no React**
+- Prefer **`@action async`** without extra `runInAction` for Stage 3 decorators when using MobX’s supported pattern
+
+---
+
+## `create.tsx`
+
+- Call child factories **outside** the returned `observer()` so identities stay stable
+- Inside `observer`: `useQuery`, `useForm`, etc.
+- Pass **`initialData: bootstrap.\*`** for the same Convex function used in SSR
+- No `useMutation` for routine writes — use `convex.mutation` in controller/presenter and pass callbacks
+- No `useState` for feature UI state — controller/presenter own that
+- Inline JSX handlers: **block or multi-line** — not one-liner `onClick={() => foo()}`
+
+---
+
+## Display components
+
+- Props + callbacks only; **no** `Doc<"todos">` / raw Convex types — import **`Todo`**, **`TodoId`** from `@/api/todos/types` (or the entity’s `types.ts`)
+- Never import **`Ent<...>`** on the frontend
+- **Forms**: `useForm` + `<FormProvider>` in `create.tsx`; display uses **`useFormContext()`** — never pass `UseFormReturn` as a prop
+- **Thin UIs** can live inline in `create.tsx` without a separate display file
+- Arrow functions, named `Props` type, explicit `return (...)` for JSX
+
+---
+
+## Schema (`schema.ts`)
+
+Same PascalCase name for type and Zod value (see `coding_standards.mdc`):
+
+```typescript
+export type NewTodoSchema = z.infer<typeof NewTodoSchema>;
+export const NewTodoSchema = z.object({
+  title: z.string().min(1, "Title is required"),
+});
+```
+
+---
+
+## Factory opts vs observer props
+
+- **Opts** — known when the factory runs (`controller`, `bootstrap`, child components created by parent). Closed over.
+- **Props** on the observer — per-render / per-item values (`todoId`, list row props).
+
+Component slots are **`ComponentType`**, not `ReactNode`.
+
+---
+
+## DI tree
+
+Nested surfaces (sheets, dialogs) live **under** the section that constructs them so dependencies stay a subtree of that section’s `create.tsx`.
+
+---
+
+## Next.js variant
+
+Adapt loader and client-entry patterns to your framework’s routing and data APIs — layer names and surface rules stay the same.
+
+---
+
+## Quick reference
+
+| File | Hooks? | Controller |
+|------|--------|------------|
+| Route module | No in loader | No |
+| `bootstrap.ts` | No | No |
+| `[feature].tsx` | `useRef`, `useMemo`, router | No — passes to install |
+| `install.tsx` | No | **Instantiates** |
+| `layout.tsx` | No | No |
+| `*_controller.ts` | No (class) | — |
+| `*_presenter.ts` | No (class) | — |
+| `create.tsx` | Yes, inside observer | Receives via closure |
+| Display | `useFormContext` only | No |

package/templates/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  actions: read
+  contents: read
+
+jobs:
+  build:
+    name: Build & Type-check
+    runs-on: ubuntu-latest
+    env:
+      SKIP_HOOKS: "1"
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Typecheck affected projects
+        run: bun run typecheck
+
+      - uses: nrwl/nx-set-shas@v4
+
+      - name: Build affected projects
+        run: bun nx affected -t build
+      # - name: Test affected projects
+      #   run: bun nx affected -t test