Sales & GTM

Fundraising & Ecosystem

Actions

Server actions — auth, tenant, permission, validate, execute, revalidate.

actions.ts runs on the server and mutates state. Every action follows the 5-step flow: authenticate → tenant → permission → validate → execute + revalidate. Reads belong in queries.ts.

Category	Shape	Reference
CRUD	Create / read / update / delete (200–1,300 lines)	`listings/grades/actions.ts`
Form step	Validate one wizard step, no DB write	`apply/personal/actions.ts`
Integration	External API wrappers (Stripe, AI, email)	`billing/actions.ts`
SaaS admin	DEVELOPER-only platform operations	`saas-dashboard/tenants/actions.ts`
Auth	Pre-tenant; uses singular `action.ts`	`auth/login/action.ts`
File / upload	Signed URL minting, S3 confirms	`file/upload/actions.ts`

Rules

#	Rule
1	`"use server"` at the top
2	The 5-step flow — auth → tenant → permission → validate → execute + revalidate
3	Import `ActionResponse` from `@/lib/action-response`, never redefine
4	Validate with Zod schemas from `validation.ts` — never raw `FormData`
5	Mutations only — reads in `queries.ts`
6	`try/catch` with structured errors — return `errorCode`, never throw
7	Include `schoolId` in every query
8	Stay under ~300 lines — split into `actions/` subdirectory by capability

Canonical example — the 5 steps

"use server"
 
import { revalidatePath } from "next/cache"
import { auth } from "@/auth"
 
import type { ActionResponse } from "@/lib/action-response"
import { db } from "@/lib/db"
import { getTenantContext } from "@/lib/tenant-context"
 
import { canCreate } from "./authorization"
import { subjectCreateSchema, type SubjectCreateInput } from "./validation"
 
export async function createSubject(
  input: SubjectCreateInput
): Promise<ActionResponse<{ id: string }>> {
  try {
    // 1. authenticate
    const session = await auth()
    if (!session?.user?.id) return { success: false, errorCode: "UNAUTHORIZED" }
 
    // 2. tenant
    const { schoolId } = await getTenantContext()
    if (!schoolId) return { success: false, errorCode: "MISSING_TENANT" }
 
    // 3. permission
    if (!canCreate(session.user.role)) {
      return { success: false, errorCode: "FORBIDDEN" }
    }
 
    // 4. validate
    const parsed = subjectCreateSchema.safeParse(input)
    if (!parsed.success) {
      return { success: false, errorCode: "INVALID_INPUT" }
    }
 
    // 5. execute and revalidate
    const subject = await db.subject.create({
      data: { ...parsed.data, schoolId },
      select: { id: true },
    })
    revalidatePath("/subjects")
    return { success: true, data: { id: subject.id } }
  } catch (error) {
    console.error("createSubject error", error)
    return { success: false, errorCode: "SERVER_ERROR" }
  }
}

Error codes

Return codes; the dictionary maps them on the client via useI18nMessages(dictionary).error.

Code	Meaning
`UNAUTHORIZED`	`auth()` failed
`MISSING_TENANT`	No `schoolId` on the session
`FORBIDDEN`	Permission check failed
`INVALID_INPUT`	Zod validation failed
`NOT_FOUND`	Record doesn't exist or other tenant
`CONFLICT`	Unique constraint violation
`SERVER_ERROR`	Unexpected exception

type ActionResponse<T> =
  | { success: true; data: T }
  | { success: false; errorCode: ErrorCode; error?: string }

The error field is for developer diagnostics only — never show to users.

Anti-patterns

Redefining ActionResponse (27+ files) — import from @/lib/action-response.
Monolith files — 5,692-line timetable/actions.ts is the canonical bad example. Split into actions/.
Duplicate function names across files (createPeriod, getInvoices).
console.log of auth data — never log emails, tokens, sessions.
Raw FormData.get() as string — parse with Zod first.
any types (150+ in codebase) — use inferred Zod or Prisma payloads.
Read functions in actions.ts — move to queries.ts.

Naming

File: actions.ts (plural). action.ts (singular) only for legacy auth flows.

Sibling roles

Imports schemas + types from validation.ts.
Imports permission helpers from authorization.ts.
Never imports from form.tsx / table.tsx.
Never imports from another feature's actions.

Actions

Server actions — auth, tenant, permission, validate, execute, revalidate.

actions.ts runs on the server and mutates state. Every action follows the 5-step flow: authenticate → tenant → permission → validate → execute + revalidate. Reads belong in queries.ts.

Category	Shape	Reference
CRUD	Create / read / update / delete (200–1,300 lines)	`listings/grades/actions.ts`
Form step	Validate one wizard step, no DB write	`apply/personal/actions.ts`
Integration	External API wrappers (Stripe, AI, email)	`billing/actions.ts`
SaaS admin	DEVELOPER-only platform operations	`saas-dashboard/tenants/actions.ts`
Auth	Pre-tenant; uses singular `action.ts`	`auth/login/action.ts`
File / upload	Signed URL minting, S3 confirms	`file/upload/actions.ts`

Rules

#	Rule
1	`"use server"` at the top
2	The 5-step flow — auth → tenant → permission → validate → execute + revalidate
3	Import `ActionResponse` from `@/lib/action-response`, never redefine
4	Validate with Zod schemas from `validation.ts` — never raw `FormData`
5	Mutations only — reads in `queries.ts`
6	`try/catch` with structured errors — return `errorCode`, never throw
7	Include `schoolId` in every query
8	Stay under ~300 lines — split into `actions/` subdirectory by capability

Canonical example — the 5 steps

"use server"
 
import { revalidatePath } from "next/cache"
import { auth } from "@/auth"
 
import type { ActionResponse } from "@/lib/action-response"
import { db } from "@/lib/db"
import { getTenantContext } from "@/lib/tenant-context"
 
import { canCreate } from "./authorization"
import { subjectCreateSchema, type SubjectCreateInput } from "./validation"
 
export async function createSubject(
  input: SubjectCreateInput
): Promise<ActionResponse<{ id: string }>> {
  try {
    // 1. authenticate
    const session = await auth()
    if (!session?.user?.id) return { success: false, errorCode: "UNAUTHORIZED" }
 
    // 2. tenant
    const { schoolId } = await getTenantContext()
    if (!schoolId) return { success: false, errorCode: "MISSING_TENANT" }
 
    // 3. permission
    if (!canCreate(session.user.role)) {
      return { success: false, errorCode: "FORBIDDEN" }
    }
 
    // 4. validate
    const parsed = subjectCreateSchema.safeParse(input)
    if (!parsed.success) {
      return { success: false, errorCode: "INVALID_INPUT" }
    }
 
    // 5. execute and revalidate
    const subject = await db.subject.create({
      data: { ...parsed.data, schoolId },
      select: { id: true },
    })
    revalidatePath("/subjects")
    return { success: true, data: { id: subject.id } }
  } catch (error) {
    console.error("createSubject error", error)
    return { success: false, errorCode: "SERVER_ERROR" }
  }
}

Error codes

Return codes; the dictionary maps them on the client via useI18nMessages(dictionary).error.

Code	Meaning
`UNAUTHORIZED`	`auth()` failed
`MISSING_TENANT`	No `schoolId` on the session
`FORBIDDEN`	Permission check failed
`INVALID_INPUT`	Zod validation failed
`NOT_FOUND`	Record doesn't exist or other tenant
`CONFLICT`	Unique constraint violation
`SERVER_ERROR`	Unexpected exception

type ActionResponse<T> =
  | { success: true; data: T }
  | { success: false; errorCode: ErrorCode; error?: string }

The error field is for developer diagnostics only — never show to users.

Anti-patterns

Redefining ActionResponse (27+ files) — import from @/lib/action-response.
Monolith files — 5,692-line timetable/actions.ts is the canonical bad example. Split into actions/.
Duplicate function names across files (createPeriod, getInvoices).
console.log of auth data — never log emails, tokens, sessions.
Raw FormData.get() as string — parse with Zod first.
any types (150+ in codebase) — use inferred Zod or Prisma payloads.
Read functions in actions.ts — move to queries.ts.

Naming

File: actions.ts (plural). action.ts (singular) only for legacy auth flows.

Sibling roles

Imports schemas + types from validation.ts.
Imports permission helpers from authorization.ts.
Never imports from form.tsx / table.tsx.
Never imports from another feature's actions.

balqalam

Actions

Categories

Rules

Canonical example — the 5 steps

Error codes

Anti-patterns

Naming

Sibling roles

See also

balqalam

Actions

Categories

Rules

Canonical example — the 5 steps

Error codes

Anti-patterns

Naming

Sibling roles

See also