create-aron-app 0.1.6 → 0.1.7

package/templates/.cursor/rules/frontend_architecture_nextjs.mdc

@@ -0,0 +1,458 @@
+---
+description: Frontend surface architecture — Next.js App Router + Convex variant. Covers MobX setup with makeObservable, server-side bootstrap with fetchQuery, and "use client" boundaries. Extends frontend_architecture_core.
+globs: apps/nextjs/src/**
+alwaysApply: false
+---
+
+# Frontend Surface Architecture — Next.js + Convex
+
+This document covers the Next.js-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
+
+Next.js uses SWC for compilation, not Babel. TC39 Stage 3 decorator support in SWC requires pinned WASM plugins that break on Next.js version upgrades. Use `makeObservable` instead — identical semantics, zero build tooling risk, works with SWC out of the box.
+
+Do **not** set `experimentalDecorators: true`. Do **not** add a `babel.config.js` — this disables SWC entirely.
+
+```typescript
+import { makeObservable, observable, action, computed } from "mobx";
+
+export class ExampleController {
+  value = "";
+  isPending = false;
+
+  constructor() {
+    makeObservable(this, {
+      value: observable,
+      isPending: observable,
+      isReady: computed,
+      setValue: action,
+    });
+  }
+
+  get isReady() {
+    return this.value.trim().length > 0;
+  }
+
+  setValue(v: string) {
+    this.value = v;
+  }
+}
+```
+
+Rules:
+- Use `makeObservable` with an explicit annotation map in the constructor
+- Use `observable.ref` for fields that hold object/component references (only reference equality needed)
+- Use `runInAction(() => { ... })` when mutating observables inside an async callback or Promise `.then`
+
+### Convex Client
+
+The `ConvexReactClient` singleton is exported from the provider so presenters can call mutations directly outside of React:
+
+```typescript
+// src/providers/convex_provider.tsx
+export const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
+```
+
+Rules:
+- Presenters import `convex` from `@/web/providers/convex_provider` to call `convex.mutation()` directly
+
+### Auth Token Helper
+
+Required for passing authenticated requests to `fetchQuery` during server rendering:
+
+```typescript
+// src/utils/auth.ts
+import { auth } from "@clerk/nextjs/server";
+
+export const getAuthToken = async () => {
+  return (await (await auth()).getToken()) ?? undefined;
+};
+```
+
+---
+
+## App routing: `(auth)` vs `(dashboard)`
+
+Next.js [route groups](https://nextjs.org/docs/app/building-your-application/routing/route-groups) use parentheses: `app/(auth)/` and `app/(dashboard)/`. **Parent folder names do not appear in the URL.**
+
+| Group | Role |
+| --- | --- |
+| `(auth)` | Sign-in and other unauthenticated pages. **No** app sidebar — minimal or centered layout (see `(auth)/layout.tsx`). |
+| `(dashboard)` | Authenticated app **shell**: `SidebarProvider` + **Sidebar** surface + `SidebarInset` wrapping `{children}`. All main app routes nest here. |
+
+Canonical URLs (unchanged by group folders):
+
+- `/` — home
+- `/todos` — all todos
+- `/todos/[id]` — single todo
+- `/sign-in/[[...sign-in]]` (or your Clerk catch-all) — auth
+
+The `(dashboard)/layout.tsx` file should remain a **Server Component** when possible: compose providers and the client **Sidebar** entry only; avoid pulling server-only auth into client trees unnecessarily. The Sidebar surface module is a **`"use client"`** boundary (MobX + optional hooks).
+
+---
+
+## Shell surface vs page surfaces
+
+- **Shell (layout-mounted):** `surfaces/sidebar/` — mounted **only** from `(dashboard)/layout.tsx`. Persists across navigations inside the dashboard. Uses **`SidebarLayout`** + **`installSidebar`** with lazy section `create*.tsx` files.
+- **Page surfaces:** `surfaces/home/`, `surfaces/todos/all_todos/`, `surfaces/todos/single_todo/` — mounted from **`page.tsx`** under `(dashboard)/`. Each follows `frontend_architecture_core`: `bootstrap.ts` → `[feature].tsx` → `install.tsx` → layout slots → section `create.tsx` / display / controllers.
+
+See `frontend_architecture_core` for folder naming: **`all_todos`**, **`single_todo`**, and exported components **`AllTodos`**, **`SingleTodo`** (or `AllTodoSurface` / `SingleTodoSurface` if you keep the `Surface` suffix consistently).
+
+---
+
+## Sidebar surface (layout chrome)
+
+Required structure (slots are **product-dependent** — add/remove sections as needed):
+
+```
+surfaces/sidebar/
+  sidebar.tsx          # client entry: useMemo(createSidebarLayout), useEffect(() => installSidebar({ layout }))
+  layout.tsx           # SidebarLayout + createSidebarLayout() — MobX observable slots + shell JSX
+  install.tsx          # installSidebar — dynamic import() each section's create
+  nav_main/            # example section
+    create.tsx
+    nav_main.tsx       # dumb display
+  nav_secondary/
+    create.tsx
+    nav_secondary.tsx
+  user_menu/
+    create.tsx
+    user_menu.tsx
+  ui/                  # optional: shared dumb pieces for this surface only
+```
+
+**Install timing:** Layout-mounted chrome uses **`useEffect`** to run `installSidebar` once (avoids some Strict Mode / hydration edge cases for persistent shell). **Route-mounted** feature surfaces use the **synchronous `useRef` install guard**.
+
+---
+
+## Route → surface map
+
+| URL | Mount |
+| --- | --- |
+| `/` | `Home` (`surfaces/home/`) |
+| `/todos` | `AllTodos` (`surfaces/todos/all_todos/`) |
+| `/todos/[id]` | `SingleTodo` (`surfaces/todos/single_todo/`) |
+| `(dashboard)` layout | `Sidebar` (`surfaces/sidebar/`) |
+
+---
+
+## Route + Bootstrap Pattern
+
+Each Next.js page is a **Server Component** that calls the surface's bootstrap function, then renders the client surface with the bootstrap as a prop. The bootstrap runs `fetchQuery` to load the initial Convex data server-side, so the client surface renders with data immediately — no loading spinner on first paint.
+
+### Page File (`app/(group)/[path]/[id]/page.tsx`)
+
+```typescript
+import type { Metadata } from "next";
+import type { TodoId } from "@/api/todos/types";
+import { bootstrapTodoDetail } from "@/web/surfaces/todo_detail/bootstrap";
+import { TodoDetail } from "@/web/surfaces/todo_detail/todo_detail";
+import { getAuthToken } from "@/web/utils/auth";
+
+type TodoDetailPageProps = {
+  params: Promise<{ id: TodoId }>;
+};
+
+export const metadata: Metadata = {
+  title: "Todo",
+  description: "Todo detail",
+};
+
+export default async function TodoDetailPage({ params }: TodoDetailPageProps) {
+  const { id } = await params;
+  const token = await getAuthToken();
+  const bootstrap = await bootstrapTodoDetail({ todoId: id, token });
+  return <TodoDetail bootstrap={bootstrap} />;
+}
+```
+
+Rules:
+- Page is an `async` Server Component — no `"use client"` directive
+- `params` is a `Promise` in Next.js App Router — always `await` it
+- `getAuthToken()` passes the Clerk JWT to `fetchQuery` for authenticated queries
+- Page passes `bootstrap` directly to the surface — no intermediate data reshaping
+
+---
+
+## Layer Reference (Next.js-specific)
+
+### `bootstrap.ts`
+
+Async function called in the server page. Uses `fetchQuery` from `convex/nextjs` to load the surface's primary entity server-side. The result is passed as `initialData` to queries in the `create` layer.
+
+```typescript
+import { fetchQuery } from "convex/nextjs";
+
+import { api } from "@/api/_generated/api";
+import type { Todo, TodoId } from "@/api/todos/types";
+
+export type TodoDetailBootstrapArgs = {
+  todoId: TodoId;
+  token?: string;
+};
+
+export type TodoDetailBootstrap = Awaited<ReturnType<typeof bootstrapTodoDetail>>;
+
+export const bootstrapTodoDetail = async ({ todoId, token }: TodoDetailBootstrapArgs) => {
+  const todo = await fetchQuery(
+    api.todos.crud.getTodo,
+    { todoId },
+    { token },
+  );
+  return { todoId, todo };
+};
+```
+
+Rules:
+- Use `fetchQuery` from `convex/nextjs` — returns the actual data value, passes `token` for authenticated queries
+- Auth failures/redirects belong here, not in components
+
+### `[feature].tsx` — Surface Entry Component
+
+`"use client"` boundary. Receives `bootstrap` from the server page. **Does not instantiate controllers** — that happens in `install.tsx`.
+
+```typescript
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useMemo, useRef } from "react";
+
+import type { TodoDetailBootstrap } from "@/web/surfaces/todo_detail/bootstrap";
+import { installTodoDetail } from "@/web/surfaces/todo_detail/install";
+import { createLayout } from "@/web/surfaces/todo_detail/layout";
+
+export type TodoDetailProps = {
+  bootstrap: TodoDetailBootstrap;
+};
+
+export const TodoDetail = ({ bootstrap }: TodoDetailProps) => {
+  const router = useRouter();
+  const { layout, Layout } = useMemo(() => createLayout(), []);
+  const installed = useRef(false);
+
+  if (!installed.current) {
+    installed.current = true;
+    installTodoDetail({ layout, bootstrap, router });
+  }
+
+  return <Layout />;
+};
+```
+
+Rules:
+- Always add `"use client"` — this is the boundary between server and client
+- Use `useRouter` from `next/navigation`
+- **Never instantiate controllers here** — pass deps to install, which creates the controller
+- All imports use `@/` aliases — no relative imports
+
+### `install.tsx`
+
+```typescript
+import type { AppRouterInstance } from "next/dist/shared/lib/app-router-context.shared-runtime";
+
+import type { TodoDetailBootstrap } from "@/web/surfaces/todo_detail/bootstrap";
+import type { TodoDetailLayoutController } from "@/web/surfaces/todo_detail/layout";
+import { TodoDetailController } from "@/web/surfaces/todo_detail/todo_detail_controller";
+
+export type InstallTodoDetailOpts = {
+  layout: TodoDetailLayoutController;
+  bootstrap: TodoDetailBootstrap;
+  router: AppRouterInstance;
+};
+
+export const installTodoDetail = ({ layout, bootstrap, router }: InstallTodoDetailOpts) => {
+  const controller = new TodoDetailController();
+
+  import("@/web/surfaces/todo_detail/header/create").then(({ createHeader }) => {
+    layout.setHeader(createHeader({ controller, bootstrap }));
+  });
+
+  import("@/web/surfaces/todo_detail/main/create").then(({ createMain }) => {
+    layout.setMain(createMain({ controller, bootstrap, router }));
+  });
+};
+```
+
+Rules:
+- Use `AppRouterInstance` from `next/dist/shared/lib/app-router-context.shared-runtime` for the router type
+- **Controller instantiated here** — exactly once
+- Dynamic `import()` paths use `@/` aliases
+
+### `layout.tsx`
+
+```typescript
+"use client";
+
+import { makeObservable, observable, action, runInAction } from "mobx";
+import { observer } from "mobx-react-lite";
+import type { ComponentType } from "react";
+
+import { Skeleton } from "@/ui/base/skeleton";
+
+export class LayoutController {
+  Header: ComponentType | undefined = undefined;
+  Main: ComponentType | undefined = undefined;
+
+  constructor() {
+    makeObservable(this, {
+      Header: observable.ref,
+      Main: observable.ref,
+      setHeader: action,
+      setMain: action,
+    });
+  }
+
+  setHeader(Header: ComponentType) {
+    runInAction(() => {
+      this.Header = Header;
+    });
+  }
+
+  setMain(Main: ComponentType) {
+    runInAction(() => {
+      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:
+- `runInAction` required when mutating observables inside a Promise `.then`
+
+### `[section]/create.tsx`
+
+```typescript
+"use client";
+
+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 { TodoDetailBootstrap } from "@/web/surfaces/todo_detail/bootstrap";
+import type { TodoDetailController } from "@/web/surfaces/todo_detail/todo_detail_controller";
+import { Main } from "@/web/surfaces/todo_detail/main/main";
+
+export type CreateMainOpts = {
+  controller: TodoDetailController;
+  bootstrap: TodoDetailBootstrap;
+};
+
+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:
+- Add `"use client"` — create files are client components
+- Spread `convexQuery` with `initialData: bootstrap.[entity]` — eliminates loading flash, query stays reactive after hydration
+- All imports use `@/` aliases — no relative imports
+
+### Display Components
+
+Rules:
+- No `"use client"` directive needed — display components have no hooks (exception: `useFormContext` for form displays, which does need `"use client"`)
+
+### `[section]_presenter.ts`
+
+```typescript
+import { makeObservable, observable, action, computed, runInAction } from "mobx";
+import { convex } from "@/web/providers/convex_provider";
+import { api } from "@/api/_generated/api";
+import type { AppRouterInstance } from "next/dist/shared/lib/app-router-context.shared-runtime";
+
+export type NewTodoPresenterOpts = {
+  router: AppRouterInstance;
+};
+
+export class NewTodoPresenter {
+  private readonly router: AppRouterInstance;
+
+  input = "";
+  isPending = false;
+
+  constructor({ router }: NewTodoPresenterOpts) {
+    this.router = router;
+
+    makeObservable(this, {
+      input: observable,
+      isPending: observable,
+      isSubmitDisabled: computed,
+      setInput: action,
+      submit: action,
+    });
+  }
+
+  get isSubmitDisabled() {
+    return !this.input.trim() || this.isPending;
+  }
+
+  setInput(value: string) {
+    this.input = value;
+  }
+
+  async submit() {
+    runInAction(() => {
+      this.isPending = true;
+    });
+
+    try {
+      await convex.mutation(api.todos.crud.createTodo, {
+        title: this.input.trim()
+      });
+
+      runInAction(() => {
+        this.input = "";
+      });
+
+    } finally {
+      runInAction(() => {
+        this.isPending = false;
+      });
+    }
+  }
+}
+```
+
+Rules:
+- Use `runInAction` when mutating observables after an `await`