create-aron-app 0.1.7 → 0.1.8

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

@@ -1,473 +0,0 @@
----
-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/nextjs/.env.example

@@ -1,10 +0,0 @@
-# Backend
-CONVEX_DEPLOYMENT=
-CLERK_SECRET_KEY=
-CONVEX_SITE_URL= # HTTPS URL
-CLERK_JWT_ISSUER_DOMAIN=
-RESEND_API_KEY=
-
-# Frontend
-NEXT_PUBLIC_CONVEX_URL=
-NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=

package/templates/apps/nextjs/index.d.ts

@@ -1,6 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-declare module '*.svg' {
-  const content: any;
-  export const ReactComponent: any;
-  export default content;
-}

package/templates/apps/nextjs/next-env.d.ts

@@ -1,5 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/apps/nextjs/next.config.js

@@ -1,22 +0,0 @@
-//@ts-check
-
-// eslint-disable-next-line @typescript-eslint/no-var-requires
-const { composePlugins, withNx } = require("@nx/next");
-
-/**
- * @type {import('@nx/next/plugins/with-nx').WithNxOptions}
- **/
-const nextConfig = {
-  nx: {
-    // Set this to true if you would like to use SVGR
-    // See: https://github.com/gregberge/svgr
-    svgr: false,
-  },
-};
-
-const plugins = [
-  // Add more Next.js plugins to this list if needed.
-  withNx,
-];
-
-module.exports = composePlugins(...plugins)(nextConfig);

package/templates/apps/nextjs/postcss.config.js

@@ -1,17 +0,0 @@
-/*
- * Copyright (c) Aron Weston 2025.
- */
-
-const { join } = require("node:path");
-
-// Note: If you use library-specific PostCSS/Tailwind configuration then you should remove the `postcssConfig` build
-// option from your application's configuration (i.e. project.json).
-//
-// See: https://nx.dev/guides/using-tailwind-css-in-react#step-4:-applying-configuration-to-libraries
-
-module.exports = {
-  plugins: {
-    "@tailwindcss/postcss": {},
-    autoprefixer: {},
-  },
-};

package/templates/apps/nextjs/project.json

@@ -1,22 +0,0 @@
-{
-  "name": "nextjs",
-  "$schema": "../../node_modules/nx/schemas/project-schema.json",
-  "sourceRoot": "apps/nextjs",
-  "projectType": "application",
-  "tags": [],
-  "targets": {
-    "dev": {
-      "executor": "nx:run-commands",
-      "options": {
-        "command": "bunx next dev apps/nextjs --port 5001"
-      }
-    },
-    "build": {
-      "executor": "@nx/next:build",
-      "options": {
-        "root": "apps/nextjs",
-        "outputPath": "dist/apps/nextjs"
-      }
-    }
-  }
-}

package/templates/apps/nextjs/src/app/(auth)/layout.tsx

@@ -1,21 +0,0 @@
-/*
- * Copyright (c) Aron Weston 2025.
- */
-
-import "../app.css";
-
-import { Toaster } from "sonner";
-
-
-type RootLayoutProps = {
-  children: React.ReactNode;
-};
-
-export default function AuthLayout({ children }: RootLayoutProps) {
-  return (
-    <main className="flex min-h-screen flex-col justify-center items-center overflow-hidden">
-      {children}
-      <Toaster />
-    </main>
-  );
-}

package/templates/apps/nextjs/src/app/(auth)/not-allowed/page.tsx

@@ -1,23 +0,0 @@
-/*
- * Copyright (c) Aron Weston 2025.
- */
-
-import type { Metadata } from "next";
-import Link from "next/link";
-
-export const metadata: Metadata = {
-  title: "Not Allowed",
-  description: "You are not allowed to access this page.",
-};
-
-export default async function NotAllowed() {
-  return (
-    <div className="flex flex-col items-center justify-center h-screen">
-      <h1 className="text-2xl font-bold">Not Allowed</h1>
-      <p className="text-sm text-gray-500">You are not allowed to access this page.</p>
-      <Link href="/sign-in" className="text-blue-500">
-        Continue to login page
-      </Link>
-    </div>
-  );
-}

package/templates/apps/nextjs/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx

@@ -1,15 +0,0 @@
-/*
- * Copyright (c) Aron Weston 2025.
- */
-
-import { SignIn } from "@clerk/nextjs";
-import type { Metadata } from "next";
-
-export const metadata: Metadata = {
-  title: "Sign In",
-  description: "Sign In to your account",
-};
-
-export default function LoginPage() {
-  return <SignIn withSignUp={true} />;
-}

package/templates/apps/nextjs/src/app/(dashboard)/layout.tsx

@@ -1,22 +0,0 @@
-/*
- * Copyright (c) Aron Weston 2026.
- */
-
-import { SidebarInset, SidebarProvider } from "@/ui/base/side_bar";
-import { Sidebar } from "@/web/surfaces/sidebar/sidebar";
-
-type DashboardLayoutProps = {
-  children: React.ReactNode;
-};
-
-export default function DashboardLayout({ children }: DashboardLayoutProps) {
-  return (
-    <SidebarProvider
-      style={{ "--sidebar-width": "265px" } as React.CSSProperties}
-      defaultOpen={true}
-    >
-      <Sidebar />
-      <SidebarInset>{children}</SidebarInset>
-    </SidebarProvider>
-  );
-}

package/templates/apps/nextjs/src/app/(dashboard)/page.tsx

@@ -1,12 +0,0 @@
-/*
- * Copyright (c) Aron Weston 2026.
- */
-
-import { bootstrapHome } from "@/web/surfaces/home/bootstrap";
-import { Home } from "@/web/surfaces/home/home";
-
-export default async function HomePage() {
-  const bootstrap = await bootstrapHome();
-
-  return <Home bootstrap={bootstrap} />;
-}

package/templates/apps/nextjs/src/app/(dashboard)/todos/[id]/page.tsx

@@ -1,26 +0,0 @@
-/*
- * Copyright (c) Aron Weston 2026.
- */
-
-import type { Metadata } from "next";
-
-import type { TodoId } from "@/api/todos/types";
-import { bootstrapSingleTodo } from "@/web/surfaces/todos/single_todo/bootstrap";
-import { SingleTodo } from "@/web/surfaces/todos/single_todo/single_todo";
-
-type SingleTodoPageProps = {
-  params: Promise<{ id: TodoId }>;
-};
-
-export const metadata: Metadata = {
-  title: "Todo",
-  description: "Todo",
-};
-
-export default async function SingleTodoPage({ params }: SingleTodoPageProps) {
-  const { id } = await params;
-
-  const bootstrap = await bootstrapSingleTodo({ todoId: id });
-
-  return <SingleTodo bootstrap={bootstrap} />;
-}