create-aron-app 0.1.6 → 0.1.7

package/templates/.cursor/rules/frontend_architecture_reactrouter.mdc

@@ -0,0 +1,473 @@
+---
+description: Frontend surface architecture — React Router + Convex variant. Covers MobX decorator setup, clientLoader bootstrap pattern, and React Router-specific wiring. Extends frontend_architecture_core.
+globs: apps/react-router/src/**
+alwaysApply: false
+---
+
+# Frontend Surface Architecture — React Router + Convex
+
+This document covers the React Router-specific implementation of the surface architecture defined in `frontend_architecture_core`. Read that document first for the layer model, MobX philosophy, and component rules.
+
+---
+
+## Setup
+
+### MobX
+
+MobX 2022.3 (Stage 3) decorators. Requires TypeScript 5.0+ with `experimentalDecorators` **off**.
+
+**`tsconfig.json`:**
+```json
+{ "compilerOptions": { "experimentalDecorators": false } }
+```
+
+**`vite.config.ts`:**
+```typescript
+react({ babel: { plugins: [["@babel/plugin-proposal-decorators", { version: "2023-05" }]] } })
+```
+
+Rules:
+- Every `@observable` field must use the `accessor` keyword
+- No `makeObservable` or `makeAutoObservable` needed when using decorators
+- Direct observable mutations inside a Promise `.then` must be wrapped in an action — `@action` decorated methods satisfy this requirement, so no additional `runInAction` is needed
+
+### Convex Client
+
+The `ConvexReactClient` singleton is exported from the provider so presenters can call mutations directly outside of React:
+
+```typescript
+// src/providers/api_auth_provider.tsx
+export const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
+```
+
+Rules:
+- Presenters import `convex` from `@/web/providers/api_auth_provider` to call `convex.mutation()` directly
+- `create.tsx` files use `useQuery(convexQuery(...))` and `useMutation({ mutationFn: useConvexMutation(...) })` for reactive data and hook-based mutations
+
+### TanStack Query client for `clientLoader`
+
+Export a **module singleton** `queryClient` from the same provider module that wires `ConvexQueryClient` (e.g. `api_auth_provider.tsx`). Dashboard and page `clientLoader` functions import it and call `queryClient.ensureQueryData(convexQuery(...))` so bootstrap can warm the cache before render.
+
+---
+
+## App routing: `(auth)` vs `(dashboard)`
+
+Mirror the filesystem shape: **`routes/(auth)/…`** and **`routes/(dashboard)/…`**. Parentheses are route-group folders only; **URLs are declared in `routes.ts`**, not by folder names.
+
+**`routes.ts` shape:**
+
+```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", [
+      index("./routes/(dashboard)/todos/index.tsx"),
+      route(":id", "./routes/(dashboard)/todos/[id].tsx"),
+    ]),
+  ]),
+] satisfies RouteConfig;
+```
+
+- One **`layout()`** for `(auth)` (sign-in only, no sidebar).
+- One **`layout()`** for `(dashboard)` with `index` + `prefix("todos", …)`.
+
+| Group | Role |
+| --- | --- |
+| `(auth)` | Sign-in pages. **No** sidebar. Optional `(auth)/layout.tsx` for centered chrome. |
+| `(dashboard)` | **`clientLoader`** validates session (e.g. `ensureQueryData` on an auth-gated Convex query; on failure `redirect("/sign-in")`). Renders `SidebarProvider` + **Sidebar** surface + `SidebarInset` + `<Outlet />`. |
+
+**Root** (`root.tsx`): providers + `<Outlet />` only — **no** sidebar and **no** per-route auth gate here.
+
+---
+
+## Shell surface vs page surfaces
+
+- **Shell:** `surfaces/sidebar/` — mounted only from `(dashboard)/layout.tsx`. **`SidebarLayout`** + **`installSidebar`** + lazy section creates (same mental model as Next).
+- **Pages:** `surfaces/home/`, `surfaces/todos/all_todos/`, `surfaces/todos/single_todo/` — each route file imports `bootstrap*` and mounts the surface entry component with `loaderData`.
+
+Naming matches `frontend_architecture_core`: folders **`all_todos`**, **`single_todo`**; components **`Home`**, **`AllTodos`**, **`SingleTodo`** (optional `Surface` suffix if used consistently).
+
+---
+
+## Sidebar surface (layout chrome)
+
+Same structure as the Next.js rule doc: `sidebar.tsx` (entry), `layout.tsx` (`SidebarLayout` / `createSidebarLayout`), `install.tsx`, section folders with `create.tsx` + dumb `*.tsx`. **Slots are product-dependent.**
+
+**Install timing:** Layout-mounted sidebar uses **`useEffect`** to call `installSidebar` once. **Route-mounted** surfaces use the **synchronous `useRef` install guard**.
+
+---
+
+## Route → surface map
+
+| URL | Mount |
+| --- | --- |
+| `/` | `Home` |
+| `/todos` | `AllTodos` |
+| `/todos/:id` | `SingleTodo` |
+| `(dashboard)` layout | `Sidebar` |
+
+---
+
+## Dashboard layout `clientLoader` (auth gate)
+
+```typescript
+import { redirect } from "react-router";
+
+import { convexQuery } from "@convex-dev/react-query";
+
+import { api } from "@/api/_generated/api";
+import type { Route } from "@/router/app/routes/(dashboard)/+types/layout";
+import { queryClient } from "@/web/providers/api_auth_provider";
+
+export async function clientLoader(_args: Route.ClientLoaderArgs) {
+  try {
+    await queryClient.ensureQueryData(convexQuery(api.todos.crud.listTodos, {}));
+  } catch {
+    return redirect("/sign-in");
+  }
+  return null;
+}
+```
+
+Rules:
+
+- Use a **real authenticated Convex query** (or dedicated `api.user.me`-style query) so unauthenticated users fail fast.
+- Import **`queryClient`** from the provider module — do not instantiate a new `QueryClient` in the loader.
+
+---
+
+## Route + Bootstrap Pattern
+
+Each route that mounts a surface uses a **bootstrap** to validate params, handle redirects, and optionally **warm the TanStack Query cache** via `queryClient.ensureQueryData(convexQuery(...))` (import the **`queryClient` singleton** from `@/web/providers/api_auth_provider`). The bootstrap return value is passed into the surface as `bootstrap`; section `create.tsx` files spread `initialData: bootstrap.*` into `useQuery` so the first paint matches the server-loaded data.
+
+### Router Types
+
+The `@/router` alias maps to `./apps/react-router/.react-router/types/*`. After `react-router typegen`, import generated types from paths that mirror the filesystem, e.g.:
+
+- `@/router/app/routes/(dashboard)/+types/layout` — dashboard layout `clientLoader`
+- `@/router/app/routes/(dashboard)/todos/+types/[id]` — todo detail route
+
+Use:
+
+- `Route.ClientLoaderArgs` — params, request, etc. for `clientLoader`
+- `Route.MetaArgs` — includes `loaderData` from `clientLoader`
+- `Route.ComponentProps` — includes `loaderData` for the page component
+
+### Route File (`routes/(dashboard)/todos/[id].tsx`)
+
+```typescript
+import type { Route } from "@/router/app/routes/(dashboard)/todos/+types/[id]";
+import { bootstrapSingleTodo } from "@/web/surfaces/todos/single_todo/bootstrap";
+import { SingleTodo } from "@/web/surfaces/todos/single_todo/single_todo";
+
+export async function clientLoader({ params }: Route.ClientLoaderArgs) {
+  return bootstrapSingleTodo({ params });
+}
+
+export function meta({ loaderData: bootstrap }: Route.MetaArgs) {
+  return [
+    { title: "Todo — App Name" },
+    { name: "description", content: "" },
+  ];
+}
+
+export default function SingleTodoPage({ loaderData: bootstrap }: Route.ComponentProps) {
+  return <SingleTodo bootstrap={bootstrap} />;
+}
+```
+
+Rules:
+- Types come from `@/router/app/routes/(dashboard)/…/+types/…` — React Router generates these from the route module path
+- `clientLoader` runs before render; bootstrap is the single source of initial context
+- `meta` receives `loaderData` (bootstrap output) for document title and meta tags
+- Component receives `loaderData` as `bootstrap` and passes it into the surface
+
+---
+
+## Layer Reference (React Router-specific)
+
+### `bootstrap.ts`
+
+Validates params, handles auth redirects, and pre-populates the TanStack Query cache with the primary entity. The fetched data is passed as `initialData` to queries in the `create` layer.
+
+```typescript
+import { redirect } from "react-router";
+
+import { convexQuery } from "@convex-dev/react-query";
+import type { Route } from "@/router/app/routes/(dashboard)/todos/+types/[id]";
+import type { TodoId } from "@/api/todos/types";
+import { api } from "@/api/_generated/api";
+import { queryClient } from "@/web/providers/api_auth_provider";
+
+export type SingleTodoBootstrapArgs = Pick<Route.ClientLoaderArgs, "params">;
+export type SingleTodoBootstrap = Awaited<ReturnType<typeof bootstrapSingleTodo>>;
+
+export const bootstrapSingleTodo = async ({ params }: SingleTodoBootstrapArgs) => {
+  if (!params.id) {
+    throw redirect("/todos");
+  }
+  const todoId = params.id as TodoId;
+  const todo = await queryClient.ensureQueryData(
+    convexQuery(api.todos.crud.getTodo, { todoId }),
+  );
+  return { todoId, todo };
+};
+```
+
+Rules:
+- Use `queryClient.ensureQueryData` with `convexQuery` — pre-populates the TanStack Query cache
+- Import **`queryClient`** from `@/web/providers/api_auth_provider` (singleton shared with `QueryClientProvider`)
+- Auth failures/redirects belong here, not in components
+
+### `[feature].tsx` — Surface Entry Component
+
+No `"use client"` directive — React Router is fully client-side. **Does not instantiate controllers** — that happens in `install.tsx`.
+
+```typescript
+import { useMemo, useRef } from "react";
+import { useNavigate } from "react-router";
+
+import type { SingleTodoBootstrap } from "@/web/surfaces/todos/single_todo/bootstrap";
+import { installSingleTodo } from "@/web/surfaces/todos/single_todo/install";
+import { createLayout } from "@/web/surfaces/todos/single_todo/layout";
+
+export type SingleTodoProps = {
+  bootstrap: SingleTodoBootstrap;
+};
+
+export const SingleTodo = ({ bootstrap }: SingleTodoProps) => {
+  const navigate = useNavigate();
+  const { layout, Layout } = useMemo(() => createLayout(), []);
+  const installed = useRef(false);
+
+  if (!installed.current) {
+    installed.current = true;
+    installSingleTodo({ layout, bootstrap, navigate });
+  }
+
+  return <Layout />;
+};
+```
+
+Rules:
+- Use `useNavigate` from `react-router`
+- No `"use client"` directive needed
+- **Never instantiate controllers here** — pass deps to install, which creates the controller
+- All imports use `@/` aliases — no relative imports
+
+### `install.tsx`
+
+```typescript
+import type { NavigateFunction } from "react-router";
+
+import type { SingleTodoBootstrap } from "@/web/surfaces/todos/single_todo/bootstrap";
+import type { SingleTodoLayoutController } from "@/web/surfaces/todos/single_todo/layout";
+import { SingleTodoController } from "@/web/surfaces/todos/single_todo/single_todo_controller";
+
+export type InstallSingleTodoOpts = {
+  layout: SingleTodoLayoutController;
+  bootstrap: SingleTodoBootstrap;
+  navigate: NavigateFunction;
+};
+
+export const installSingleTodo = ({ layout, bootstrap, navigate }: InstallSingleTodoOpts) => {
+  const controller = new SingleTodoController();
+
+  import("@/web/surfaces/todos/single_todo/header/create").then(({ createHeader }) => {
+    layout.setHeader(createHeader({ navigate }));
+  });
+
+  import("@/web/surfaces/todos/single_todo/main/create").then(({ createMain }) => {
+    layout.setMain(createMain({ controller, bootstrap }));
+  });
+};
+```
+
+Rules:
+- Use `NavigateFunction` from `react-router` for the navigate type
+- **Controller instantiated here** — exactly once
+- Dynamic `import()` paths use `@/` aliases
+
+### `layout.tsx`
+
+```typescript
+import { action, observable } from "mobx";
+import { observer } from "mobx-react-lite";
+import type { ComponentType } from "react";
+
+import { Skeleton } from "@/ui/base/skeleton";
+
+export class LayoutController {
+  @observable.ref
+  accessor Header: ComponentType | undefined = undefined;
+
+  @observable.ref
+  accessor Main: ComponentType | undefined = undefined;
+
+  @action
+  setHeader(Header: ComponentType) {
+    this.Header = Header;
+  }
+
+  @action
+  setMain(Main: ComponentType) {
+    this.Main = Main;
+  }
+}
+
+export const createLayout = () => {
+  const layout = new LayoutController();
+  return {
+    layout,
+    Layout: observer(() => {
+      const Header = layout.Header;
+      const Main = layout.Main;
+      return (
+        <div className="flex flex-col gap-8 w-full">
+          {Header ? <Header /> : <Skeleton className="h-12" />}
+          {Main ? <Main /> : <Skeleton className="h-64" />}
+        </div>
+      );
+    }),
+  };
+};
+```
+
+Rules:
+- Use `@observable.ref accessor` for component slots
+- `@action` decorated methods create an action boundary — calling them from Promise `.then` is safe without additional `runInAction`
+
+### `[feature]_controller.ts`
+
+```typescript
+import { action, computed, observable } from "mobx";
+
+import type { TodoId } from "@/api/todos/types";
+
+export class SingleTodoController {
+  @observable.ref
+  accessor isEditOpen = false;
+
+  @observable.ref
+  accessor selectedTodoId: TodoId | undefined = undefined;
+
+  @computed
+  get editTitle() {
+    return this.selectedTodoId ? "Edit Todo" : "New Todo";
+  }
+
+  @action
+  openEdit(todoId: TodoId) {
+    this.selectedTodoId = todoId;
+    this.isEditOpen = true;
+  }
+
+  @action
+  closeEdit() {
+    this.isEditOpen = false;
+    this.selectedTodoId = undefined;
+  }
+}
+```
+
+### `[section]_presenter.ts`
+
+```typescript
+import { action, computed, observable } from "mobx";
+import type { NavigateFunction } from "react-router";
+
+import { api } from "@/api/_generated/api";
+import { convex } from "@/web/providers/api_auth_provider";
+
+export type NewTodoPresenterOpts = {
+  navigate: NavigateFunction;
+};
+
+export class NewTodoPresenter {
+  private readonly navigate: NavigateFunction;
+
+  constructor({ navigate }: NewTodoPresenterOpts) {
+    this.navigate = navigate;
+  }
+
+  @observable
+  accessor input = "";
+
+  @observable
+  accessor isPending = false;
+
+  @computed
+  get isSubmitDisabled() {
+    return !this.input.trim() || this.isPending;
+  }
+
+  @action
+  setInput(value: string) {
+    this.input = value;
+  }
+
+  @action
+  async submit() {
+    this.isPending = true;
+    try {
+      await convex.mutation(api.todos.crud.createTodo, { title: this.input.trim() });
+      this.input = "";
+    } finally {
+      this.isPending = false;
+    }
+  }
+}
+```
+
+Rules:
+- `@action` decorated methods satisfy the action boundary — mutations inside an async `@action` method are automatically tracked, no `runInAction` needed
+
+### `[section]/create.tsx`
+
+```typescript
+import { convexQuery } from "@convex-dev/react-query";
+import { useQuery } from "@tanstack/react-query";
+import { observer } from "mobx-react-lite";
+
+import { api } from "@/api/_generated/api";
+import type { SingleTodoBootstrap } from "@/web/surfaces/todos/single_todo/bootstrap";
+import type { SingleTodoController } from "@/web/surfaces/todos/single_todo/single_todo_controller";
+import { Main } from "@/web/surfaces/todos/single_todo/main/main";
+
+export type CreateMainOpts = {
+  controller: SingleTodoController;
+  bootstrap: SingleTodoBootstrap;
+};
+
+export const createMain = ({ controller, bootstrap }: CreateMainOpts) => {
+  return observer(() => {
+    const { data: todo } = useQuery({
+      initialData: bootstrap.todo,
+      ...convexQuery(api.todos.crud.getTodo, { todoId: bootstrap.todoId }),
+    });
+
+    return (
+      <Main
+        todo={todo}
+        onToggle={(isCompleted) =>
+          controller.updateTodo({
+            todoId: bootstrap.todoId,
+            isCompleted,
+          })
+        }
+        onEdit={() => controller.openEdit(bootstrap.todoId)}
+      />
+    );
+  });
+};
+```
+
+Rules:
+- No `"use client"` directive needed
+- Spread `convexQuery` with `initialData: bootstrap.[entity]` — eliminates loading flash, query stays reactive
+- All imports use `@/` aliases — no relative imports

package/templates/apps/api/_generated/api.d.ts

@@ -0,0 +1,57 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as functions from "../functions.js";
+import type * as http from "../http.js";
+import type * as todos_crud from "../todos/crud.js";
+import type * as todos_types from "../todos/types.js";
+import type * as types from "../types.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+
+declare const fullApi: ApiFromModules<{
+  functions: typeof functions;
+  http: typeof http;
+  "todos/crud": typeof todos_crud;
+  "todos/types": typeof todos_types;
+  types: typeof types;
+}>;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;
+
+export declare const components: {};

package/templates/apps/api/_generated/api.js

@@ -0,0 +1,23 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { anyApi, componentsGeneric } from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();

package/templates/apps/api/_generated/dataModel.d.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;