Cursor rules for react-router-dashboard-saas-template

Cursor rules for react-router-dashboard-saas-template

These rules describe how to work in this repo using Cursor: file layout, React Server Components boundaries, where actions/forms live, and UI/data patterns.

Stack overview

• React 19 + React Router 7 (RSC enabled via @vitejs/plugin-rsc)
• Server rendering entry at src/entry.rsc.tsx; SSR HTML generated by src/entry.ssr.tsx
• Tailwind CSS v4 + daisyUI v5 (semantic component classes)
• Drizzle ORM (PostgreSQL) with drizzle-kit migrations
• Conform (@conform-to/react) + zod/v4 for form validation
• Session and request-scoped context via AsyncLocalStorage

Environment

• Required env: DATABASE_URL, SESSION_SECRET
• Start: pnpm dev. Build: pnpm build. Typecheck: pnpm typecheck. DB: pnpm db, pnpm db:generate, pnpm db:migrate, pnpm db:studio.

Directory layout and conventions

• src/routes/
  • Each route folder typically contains:
    • route.tsx → React Server Component (RSC) entry for the route.
    • client.tsx → co-located Client Components for that route ("islands"). Use "use client" pragma.
    • client-on.ts → small client helpers for imperative UI interactions (e.g., opening modals).
    • Optional handle.ts (see src/routes/app/handle.ts) to expose server-only pieces via the createHandle pattern.
  • Root shells:
    • src/routes/root/route.tsx (layout shell + error boundary export from client)
    • src/routes/marketing/route.tsx (public shell)
    • src/routes/app/route.tsx (authenticated app shell)
• src/actions/<domain>/
  • actions.ts → server actions (must start with "use server").
  • schema.ts → zod/v4 schemas used by the actions and forms.
  • Existing domains: auth, organization, invitation, profile.
• src/components/ → shared components across routes.
  • @/components/form → Conform + zod v4 opinionated wrappers (useForm, Form, Input, etc.).
  • src/components/ui/ → low-level UI primitives (card, modal, etc.).
• src/db/
  • schema.ts → Drizzle table definitions.
  • queries/* and mutations/* → data access layer separated by read/write.
  • index.ts → getDb() pool + drizzle instance (reused via global).
• src/lib/
  • session.ts → cookie session with ALS; use getSession(), destroySession().
  • auth.ts → getUser(), requireUser(), and route unstable_middleware helpers.
  • cache.ts → response caching and dataloader batching.

React Server Components model

• Route files (route.tsx) are server by default. Do data fetching here (DB, session, etc.). Avoid DB access in client components.
• Client components must opt-in with "use client" and should live in client.tsx (or adjacent files) within the route directory.
• Pass server-only values to client via props; avoid leaking server functions or DB clients.
• Use the createHandle/getServerHandle pattern when a route needs to expose server-only components to a parent shell (see src/routes/app/handle.ts).
• Route middleware: export unstable_middleware from the server route module to protect or redirect (see redirectIfLoggedInMiddleware, requireUserMiddleware).
• Caching: call cacheRoute() at the top of server route components when appropriate to set CDN/edge cache headers.

Forms + actions pattern (Conform + zod/v4)

• Always use zod/v4 and @conform-to/zod/v4 to match the configured version.
  • Example imports:
    • import { z } from "zod/v4"
    • import { parseWithZod } from "@conform-to/zod/v4"
• Server action signature:
  • In src/actions/<domain>/actions.ts define actions with "use server" and the shape (prev: SubmissionResult | undefined, formData: FormData) => Promise<SubmissionResult>.
  • Parse on the server: const submission = parseWithZod(formData, { schema }).
  • On validation failure: return submission.reply({ ...options }).
  • On success: perform side effects, optionally redirect(...), and return submission.reply({ resetForm: boolean }).
  • Use requireUser() inside actions that need auth.
• Client form usage (see src/routes/marketing/login/client.tsx):
  • Wire the server action using React 19’s useActionState: const [lastResult, action, pending] = useActionState(serverAction, undefined).
  • Initialize Conform via our wrapper: const [form, fields] = useForm({ action, lastResult, schema }).
  • Render with <Form action={action} form={form}> and use <Input field={fields.email} ... /> etc.
  • Use <FormErrors form={form} /> and <FormSuccessMessage lastResult={lastResult}>...</FormSuccessMessage>.
  • Keep redirect/query state in hidden inputs when needed (e.g., redirectTo).
• Where to put schemas:
  • Define schemas in src/actions/<domain>/schema.ts and import into both the action and the client form.
• Naming:
  • Existing naming is mixed (login, signup, createOrganizationAction, updateName, etc.). Prefer descriptive verbs; suffix with Action when it clarifies intent, but keep consistency within a domain.

Data access (Drizzle)

• Define tables in src/db/schema.ts.
• Get a DB instance via getDb(); do not instantiate pools in actions/components.
• Separate reads/writes: put read functions in src/db/queries/* and mutations in src/db/mutations/*.
• Keep transactions and authorization checks in server actions or server route loaders (not in client).
• Generate and run migrations with drizzle-kit scripts.

Auth and session

• Use getUser() to read current user (may be undefined). Use requireUser() when user must exist.
• For route-level protection, add unstable_middleware = [requireUserMiddleware] to route.tsx.
• Login/signup set the session via getSession().set("user", { id }); logout destroys it via destroySession().
• Redirect using React Router’s redirect() only from server contexts.

Routing specifics

• The route shells use daisyUI and Tailwind for layout (navbar, drawer, etc.).
• The marketing shell (src/routes/marketing/route.tsx) shows how to open auth modals from the navbar using client-on.ts helpers.
• The app shell (src/routes/app/route.tsx) demonstrates co-locating a server-provided SidebarContent via the handle API and rendering notifications fed by server data.

UI and styling

• Tailwind v4 with daisyUI v5 (semantic-first):
  • Prefer daisyUI component classes (e.g., btn, input, card) and semantic colors (primary, base-100, etc.).
  • Use container pattern max-w-screen-xl mx-auto px-4 for page shells.
  • Use responsive helpers (sm:menu-horizontal, lg:drawer-open).
• Shared UI primitives live under src/components/ui/*. Add new ones here if broadly reusable. Route-specific UI belongs next to the route in client.tsx or sibling files.

Adding a new feature (checklist)

1. Routing: create a new folder in src/routes/..., add route.tsx (server). If interactive UI is needed, add client.tsx with "use client" and render it from the server route.
2. Data: add query/mutation helpers in src/db/queries/* / src/db/mutations/* as needed. Reuse getDb().
3. Actions: create src/actions/<domain>/{schema.ts,actions.ts} with zod v4 schemas and server actions.
4. Form: in the route’s client.tsx, use useActionState, useForm({ action, lastResult, schema }), and <Form>/<Input> components.
5. Auth: add unstable_middleware to routes requiring auth, and call requireUser() inside actions.
6. Caching: call cacheRoute() in server route.tsx if the page can be cached; avoid for highly dynamic/authenticated content.
7. Styling: use daisyUI components and semantic colors; keep shared primitives in src/components/ui/*.

TypeScript and code style

• TS is strict; avoid any. Export explicit types for public helpers.
• Use the @/* path alias from tsconfig.json.
• Keep functions small and descriptive; prefer early returns; handle errors close to where they occur.

Do’s and Don’ts

• Do parse and validate all form input on the server with zod v4.
• Do keep business logic in server actions or server route modules, not in client components.
• Don’t mutate session after response generation; use helpers from src/lib/session.ts within the server request lifecycle.
• Don’t access the DB from client code.
• Don’t bypass Conform’s submission.reply pattern; it powers lastResult and error display.