create-aron-app 0.1.0 → 0.1.1

package/templates/_base/.cursor/rules/frontend_rules.mdc

@@ -0,0 +1,268 @@
+---
+description: Frontend coding standards for the Next.js web app. Covers TanStack Query + Convex data fetching, component structure, form handling, and UI patterns.
+globs: apps/web/**/*.tsx,apps/web/**/*.ts
+---
+
+# Frontend Rules
+
+## Surfaces & File Structure
+
+### Surfaces as Route Entry Points
+
+Every route must have a corresponding **surface** — the single entry point for that page. Surfaces are isolated vertical slices: they own their data fetching and pass data strictly downward to child components. Pages are thin wrappers that simply render the surface.
+
+```
+app/(dashboard)/todos/page.tsx         → renders <AllTodosSurface />
+app/(dashboard)/todos/[id]/page.tsx    → renders <SingleTodoSurface />
+```
+
+```typescript
+// app/(dashboard)/todos/page.tsx
+import { AllTodosSurface } from "@/surfaces/todos/all_todos_surface";
+
+export default function TodosPage() {
+  return <AllTodosSurface />;
+}
+```
+
+### Naming Convention
+
+All file names must be **snake_case** (e.g. `all_todos_surface.tsx`, `create_todo_sheet.tsx`).
+
+Use **`All`** for list pages and **`Single`** for id-specific pages — both in the surface name and the file name:
+
+| Route | Surface component | File |
+|---|---|---|
+| `/todos` | `AllTodosSurface` | `surfaces/todos/all_todos_surface.tsx` |
+| `/todos/[id]` | `SingleTodoSurface` | `surfaces/todos/single_todo_surface.tsx` |
+
+### Component Placement
+
+| What | Where |
+|---|---|
+| Shared components (used across surfaces) | `src/ui/` |
+| Components scoped to one surface | inside that surface's folder |
+| Multiple shared components within a surface | `src/surfaces/<feature>/ui/` subfolder |
+| Providers | `src/providers/` |
+
+```
+src/
+  surfaces/
+    todos/
+      all_todos_surface.tsx
+      single_todo_surface.tsx
+      ui/                        ← shared components for this surface only
+        todo_card.tsx
+        todo_filters.tsx
+  ui/                            ← truly shared across the app
+    sidebar/
+      sidebar.tsx
+  providers/
+    convex_provider.tsx
+```
+
+
+
+
+
+## Data Fetching with TanStack Query
+
+**ALWAYS use TanStack Query for Convex queries and mutations**, never the direct Convex hooks.
+
+### Queries
+
+```typescript
+import { useQuery } from "@tanstack/react-query";
+import { convexQuery } from "@convex-dev/react-query";
+import { api } from "@/api/_generated/api";
+
+// Basic query
+const { data: todos } = useQuery(
+  convexQuery(api.todos.crud.listTodos, { userId: user.id }),
+);
+
+// Conditional / skipped query
+const { data: todos } = useQuery(
+  convexQuery(
+    api.todos.crud.listTodos,
+    user?.id ? { userId: user.id } : "skip"
+  ),
+);
+```
+
+### Mutations
+
+```typescript
+import { useMutation } from "@tanstack/react-query";
+import { useConvexMutation } from "@convex-dev/react-query";
+import { api } from "@/api/_generated/api";
+
+const { mutate, isPending } = useMutation({
+  mutationFn: useConvexMutation(api.todos.crud.createTodo),
+});
+
+const handleButtonClick = () => {
+  mutate({ title, userId });
+}
+
+```
+
+## Component Structure
+
+### Declaration
+
+Always export components as **const arrow functions**:
+
+```typescript
+// Good
+export const ComponentName = ({ prop1, prop2 }: ComponentNameProps) => {
+  return <div />;
+};
+
+// Bad
+export function ComponentName({ prop1, prop2 }: ComponentNameProps) {
+  return <div />;
+}
+```
+
+### Props Types
+
+Always define props as a **separate named type** above the component:
+
+```typescript
+type ComponentNameProps = {
+  entityId: Id<"entities">;
+  onComplete: () => void;
+};
+
+export const ComponentName = ({ entityId, onComplete }: ComponentNameProps) => {
+  // ...
+};
+```
+
+## Form Handling
+
+Use `react-hook-form` + `zod` + TanStack `useMutation`. Standard pattern:
+
+```typescript
+export const CreateEntityForm = ({ onSuccess }: CreateEntityFormProps) => {
+  const form = useForm<FormSchema>({
+    resolver: zodResolver(formSchema),
+    defaultValues: { title: "" },
+  });
+
+  const { mutate: createEntity, isPending } = useMutation({
+    mutationFn: useConvexMutation(api.entities.crud.createEntity),
+    onSuccess,
+  });
+
+  const handleSubmit = form.handleSubmit((values) => {
+    createEntity(values);
+  });
+
+  return (
+    <Form {...form}>
+      <form
+        onSubmit={handleSubmit}
+        className="space-y-4"
+        onKeyDown={(e) => {
+          if (e.key === "Enter") {
+            e.preventDefault();
+            handleSubmit();
+          }
+        }}
+      >
+        <FormField
+          control={form.control}
+          name="title"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Title</FormLabel>
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit" disabled={isPending}>
+          {isPending ? "Saving..." : "Save"}
+        </Button>
+      </form>
+    </Form>
+  );
+};
+```
+
+Key rules:
+- Store `form.handleSubmit(...)` in a `handleSubmit` const
+- Include `onKeyDown` to prevent implicit form submission on Enter
+- Use `isPending` for loading states
+
+## Sheet / Dialog Components
+
+```typescript
+export const CreateEntitySheet = ({ entityId }: CreateEntitySheetProps) => {
+  return (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button>
+          <PlusIcon className="mr-2 h-4 w-4" />
+          Add Entity
+        </Button>
+      </SheetTrigger>
+      <SheetContent className="sm:max-w-[500px]">
+        <DialogHeader>
+          <DialogTitle>Add Entity</DialogTitle>
+          <DialogDescription>Fill in the details below.</DialogDescription>
+        </DialogHeader>
+        {/* form content */}
+        <DialogFooter>
+          <Button type="submit">Save</Button>
+        </DialogFooter>
+      </SheetContent>
+    </Sheet>
+  );
+};
+```
+
+- Use `SheetContent` with `DialogHeader` / `DialogTitle` / `DialogDescription` for consistent styling
+- Use `DialogFooter` for action buttons
+
+## Import Aliases
+
+Always use alias-based imports — never relative paths outside the same directory:
+
+```typescript
+import { api } from "@/api/_generated/api";
+import { Button } from "@/ui/base/button";
+import { SomeUtil } from "@/utils/some_util";
+```
+
+
+## Routing
+
+The app uses Next.js App Router:
+
+| Path | Description |
+|---|---|
+| `(auth)/sign-in` | Clerk sign-in (public) |
+| `(dashboard)/` | Authenticated area — wrapped in sidebar layout |
+
+Add new authenticated pages inside `apps/web/src/app/(dashboard)/`.
+
+## Sidebar Navigation
+
+To add a nav item, update `apps/web/src/components/sidebar/sidebar.tsx`:
+
+```typescript
+export const nav = {
+  main: [
+    { id: "dashboard", title: "Dashboard", url: "/", icon: HomeIcon },
+    { id: "my-feature", title: "My Feature", url: "/my-feature", icon: SomeIcon },
+  ],
+  secondary: [
+    { id: "settings", title: "Settings", url: "/settings", icon: SettingsIcon },
+  ],
+};
+```

package/templates/_base/.env.convex.example

@@ -0,0 +1,3 @@
+CLERK_SECRET_KEY=
+CLERK_JWT_ISSUER_DOMAIN=
+RESEND_API_KEY=

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

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  actions: read
+  contents: read
+
+jobs:
+  main:
+    name:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      #      - run: bun install --no-cache
+      #      - uses: nrwl/nx-set-shas@v4
+
+      # - run: bun nx affected -t build

package/templates/_base/.nvmrc

@@ -0,0 +1 @@
+22

package/templates/_base/.vscode/settings.json

@@ -0,0 +1,9 @@
+{
+  "psi-header.templates": [
+    {
+      "language": "typescriptreact",
+      "template": ["Copyright (c) Aron Weston <<yeartoyear(fc!P,now)>>."]
+    }
+  ],
+  "nxConsole.generateAiAgentRules": true
+}

package/templates/_base/apps/api/auth.config.ts

@@ -0,0 +1,18 @@
+import type { AuthConfig } from "convex/server";
+
+if (!process.env.CLERK_JWT_ISSUER_DOMAIN) {
+  throw new Error("CLERK_JWT_ISSUER_DOMAIN is not set");
+}
+
+export default {
+  providers: [
+    {
+      // Replace with your own Clerk Issuer URL from your "convex" JWT template
+      // or with `process.env.CLERK_JWT_ISSUER_DOMAIN`
+      // and configure CLERK_JWT_ISSUER_DOMAIN on the Convex Dashboard
+      // See https://docs.convex.dev/auth/clerk#configuring-dev-and-prod-instances
+      domain: process.env.CLERK_JWT_ISSUER_DOMAIN!,
+      applicationID: "convex",
+    },
+  ],
+} satisfies AuthConfig;

package/templates/_base/apps/api/functions.ts

@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) Fabra Pty Ltd 2025.
+ */
+
+import { entsTableFactory } from "convex-ents";
+import {
+  customCtx,
+  customMutation,
+  customQuery,
+} from "convex-helpers/server/customFunctions";
+import { zCustomMutation, zCustomQuery } from "convex-helpers/server/zod";
+
+import {
+  internalMutation as baseInternalMutation,
+  internalQuery as baseInternalQuery,
+  mutation as baseMutation,
+  query as baseQuery,
+} from "./_generated/server";
+import { entDefinitions } from "./schema";
+
+export const query = customQuery(
+  baseQuery,
+  customCtx(async (ctx) => {
+    return {
+      table: entsTableFactory(ctx, entDefinitions),
+      db: undefined,
+    };
+  }),
+);
+
+export const zQuery = zCustomQuery(
+  baseQuery,
+  customCtx(async (ctx) => {
+    return {
+      table: entsTableFactory(ctx, entDefinitions),
+      db: undefined,
+    };
+  }),
+);
+
+export const internalQuery = customQuery(
+  baseInternalQuery,
+  customCtx(async (ctx) => {
+    return {
+      table: entsTableFactory(ctx, entDefinitions),
+      db: undefined,
+    };
+  }),
+);
+
+export const zInternalQuery = zCustomQuery(
+  baseInternalQuery,
+  customCtx(async (ctx) => {
+    return {
+      table: entsTableFactory(ctx, entDefinitions),
+      db: undefined,
+    };
+  }),
+);
+
+export const mutation = customMutation(
+  baseMutation,
+  customCtx(async (ctx) => {
+    return {
+      table: entsTableFactory(ctx, entDefinitions),
+      db: undefined,
+    };
+  }),
+);
+
+export const zMutation = zCustomMutation(
+  baseMutation,
+  customCtx(async (ctx) => {
+    return {
+      table: entsTableFactory(ctx, entDefinitions),
+      db: undefined,
+    };
+  }),
+);
+
+export const internalMutation = customMutation(
+  baseInternalMutation,
+  customCtx(async (ctx) => {
+    return {
+      table: entsTableFactory(ctx, entDefinitions),
+      db: undefined,
+    };
+  }),
+);
+
+export const zInternalMutation = zCustomMutation(
+  baseInternalMutation,
+  customCtx(async (ctx) => {
+    return {
+      table: entsTableFactory(ctx, entDefinitions),
+      db: undefined,
+    };
+  }),
+);

package/templates/_base/apps/api/project.json

@@ -0,0 +1,22 @@
+{
+  "name": "project:api",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "./apps/api",
+  "projectType": "application",
+  "tags": [],
+  "targets": {
+    "dev": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bunx convex dev"
+      }
+    },
+    "env": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "bun scripts/sync_convex_env.ts",
+        "cwd": "{workspaceRoot}"
+      }
+    }
+  }
+}

package/templates/_base/apps/api/schema.ts

@@ -0,0 +1,11 @@
+import { defineEntSchema, getEntDefinitions } from "convex-ents";
+
+import { todoEnts } from "@/api/todos/schema";
+
+const schema = defineEntSchema({
+  ...todoEnts,
+});
+
+export default schema;
+
+export const entDefinitions = getEntDefinitions(schema);

package/templates/_base/apps/api/todos/crud.ts

@@ -0,0 +1,81 @@
+import { ConvexError } from "convex/values";
+import { zid } from "convex-helpers/server/zod";
+import { z } from "zod";
+
+import { zMutation, zQuery } from "@/api/functions";
+
+export const getTodo = zQuery({
+  args: {
+    todoId: zid("todos"),
+  },
+  handler: async (ctx, args) => {
+    return ctx.table("todos").getX(args.todoId);
+  },
+});
+
+export const listTodos = zQuery({
+  handler: async (ctx) => {
+    const user = await ctx.auth.getUserIdentity();
+
+    if (!user) {
+      throw new ConvexError("Unauthorized");
+    }
+
+    return ctx.table("todos", "by_user_id", (q) => q.eq("userId", user.subject));
+  },
+});
+
+export const updateTodo = zMutation({
+  args: {
+    todoId: zid("todos"),
+    title: z.string().min(1).optional(),
+    description: z.string().optional(),
+    isCompleted: z.boolean().optional(),
+  },
+  handler: async (ctx, args) => {
+    const { todoId, ...updates } = args;
+    const todo = await ctx.table("todos").getX(todoId);
+    return todo.patch(updates);
+  },
+});
+
+export const createTodo = zMutation({
+  args: {
+    title: z.string().min(1),
+    description: z.string().optional(),
+  },
+  handler: async (ctx, args) => {
+    const user = await ctx.auth.getUserIdentity();
+
+    if (!user) {
+      throw new ConvexError("Unauthorized");
+    }
+
+    return ctx.table("todos").insert({
+      title: args.title,
+      description: args.description,
+      isCompleted: false,
+      userId: user.subject,
+    });
+  },
+});
+
+export const deleteTodo = zMutation({
+  args: {
+    todoId: zid("todos"),
+  },
+  handler: async (ctx, args) => {
+    const user = await ctx.auth.getUserIdentity();
+    if (!user) {
+      throw new ConvexError("Unauthorized");
+    }
+
+    const todo = await ctx.table("todos").getX(args.todoId);
+
+    if (todo.userId !== user.subject) {
+      throw new ConvexError("Unauthorized");
+    }
+
+    await todo.delete();
+  },
+});

package/templates/_base/apps/api/todos/schema.ts

@@ -0,0 +1,11 @@
+import { v } from "convex/values";
+import { defineEnt } from "convex-ents";
+
+export const todoEnts = {
+  todos: defineEnt({
+    title: v.string(),
+    description: v.optional(v.string()),
+    isCompleted: v.boolean(),
+    userId: v.string(),
+  }).index("by_user_id", ["userId"]),
+};

package/templates/_base/apps/api/todos/types.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+import type { Doc, Id } from "@/api/_generated/dataModel";
+import type { Ent } from "@/api/types";
+
+export type TodoId = Id<"todos">;
+export type Todo = Doc<"todos">;
+export type TodoEnt = Ent<"todos">;
+
+export type CreateTodo = z.infer<typeof CreateTodo>;
+export const CreateTodo = z.object({
+	title: z.string().min(1),
+	description: z.string().optional(),
+	userId: z.string(),
+});
+
+export type UpdateTodo = z.infer<typeof UpdateTodo>;
+export const UpdateTodo = z.object({
+	title: z.string().min(1).optional(),
+	description: z.string().optional(),
+	isCompleted: z.boolean().optional(),
+});

package/templates/_base/apps/api/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    /* These settings are not required by Convex and can be modified. */
+    "allowJs": true,
+    "strict": true,
+    "moduleResolution": "Bundler",
+    "noUnusedLocals": true,
+    "jsx": "react-jsx",
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    /* These compiler options are required by Convex */
+    "target": "ESNext",
+    "lib": ["ES2021", "dom"],
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "exclude": ["node_modules", "./_generated", "CODEOWNERS"],
+  "extends": "../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.js", "**/*.json"]
+}

package/templates/_base/apps/api/types.ts

@@ -0,0 +1,16 @@
+import type { mutation, query } from "apps/api/functions";
+import type { entDefinitions } from "apps/api/schema";
+import type { GenericEnt, GenericEntWriter } from "convex-ents";
+import type { CustomCtx } from "convex-helpers/server/customFunctions";
+
+import type { TableNames } from "@/api/_generated/dataModel";
+
+export type QueryCtx = CustomCtx<typeof query>;
+export type MutationCtx = CustomCtx<typeof mutation>;
+
+export type Ent<TableName extends TableNames> = GenericEnt<typeof entDefinitions, TableName>;
+
+export type EntWriter<TableName extends TableNames> = GenericEntWriter<
+  typeof entDefinitions,
+  TableName
+>;