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:

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]

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)

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.
Data: add query/mutation helpers in
```
src/db/queries/*
```
/
```
src/db/mutations/*
```
as needed. Reuse
```
getDb()
```
.
Actions: create
```
src/actions/<domain>/{schema.ts,actions.ts}
```
with zod v4 schemas and server actions.

Form: in the route’s

client.tsx

, use

useActionState

useForm({ action, lastResult, schema })

, and

<Form>

<Input>

components.

Auth: add
```
unstable_middleware
```
to routes requiring auth, and call
```
requireUser()
```
inside actions.
Caching: call
```
cacheRoute()
```
in server
```
route.tsx
```
if the page can be cached; avoid for highly dynamic/authenticated content.
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.

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.

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

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

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.

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.

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:

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.

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.

Use

getUser()

to read current user (may be

undefined

). Use

requireUser()

when user must exist.

For route-level protection, add

unstable_middleware = [requireUserMiddleware]

route.tsx

getSession().set("user", { id })

; logout destroys it via

destroySession()

Redirect using React Router’s

redirect()

only from server contexts.

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.

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.

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.

Data: add query/mutation helpers in

src/db/queries/*

src/db/mutations/*

as needed. Reuse

getDb()

Actions: create

src/actions/<domain>/{schema.ts,actions.ts}

with zod v4 schemas and server actions.

Form: in the route’s

client.tsx

, use

useActionState

useForm({ action, lastResult, schema })

, and

<Form>

<Input>

components.

Auth: add

unstable_middleware

to routes requiring auth, and call

requireUser()

inside actions.

Caching: call

cacheRoute()

in server

route.tsx

if the page can be cached; avoid for highly dynamic/authenticated content.

Styling: use daisyUI components and semantic colors; keep shared primitives in

src/components/ui/*

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 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.

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