Guide: Handling Forms & Validation in Next.js Stacks

(Prisma, Zod, React Hook Form)

This document outlines patterns and solutions for managing forms, validation, and data consistency in full-stack applications using Next.js (App Router), an ORM like Prisma, a database like PostgreSQL, Zod for validation, and React Hook Form (RHF) for form state management.

1. Understanding the Layers of Types & Schemas

Effective data handling requires understanding the distinct roles types and schemas play at different layers:

1.1. Database Schema (e.g., schema.prisma)

• Purpose: Defines the structure of your database tables, fields, data types (String, Int, DateTime, etc.), relations (@relation), and constraints (@id, @unique, @default).

• Role: The single source of truth for your database structure.

• Example (Generic Item Model):

  // prisma/schema.prisma
  model Item {
    id            String    @id @default(cuid())
    userId        String    // Relation to a User model
    name          String    // Required field
    description   String?   // Optional text field
    count         Int?      // Optional number field
    emailField    String?   // Optional field needing email format
    codeField     String?   // Optional field needing specific regex format
    createdAt     DateTime  @default(now())
    updatedAt     DateTime  @updatedAt
    // user       User      @relation(...) // Example relation
  }
  
  

1.2. ORM Client Types (e.g., @prisma/client Types)

• Purpose: TypeScript types auto-generated by your ORM's generation step (e.g., prisma generate). They provide type safety when using the ORM client library.

• Role: Ensures your database queries and mutations are type-safe according to the DB schema. Represents data as it comes directly from/goes directly to the DB via the ORM Client.

• Example (Conceptual):

  // Generated by ORM
  type OrmGeneratedItem = {
      id: string;
      userId: string;
      name: string;
      description: string | null;
      count: number | null;
      emailField: string | null;
      codeField: string | null;
      createdAt: Date; // ORM maps DB DateTime to JS Date
      updatedAt: Date;
      // Relations NOT included by default
  }
  
  

1.3. Custom App Types (e.g., src/types/models/)

• Purpose: TypeScript interfaces/types defined by you for consistent use within your frontend and backend logic. Often based on ORM types but can be refined or extended.

• Role: Define the shape of data within your application's code. Can guarantee types (like Date) and structure data conveniently (e.g., including relations).

• Example:

  // src/types/models/index.ts
  import type { Item as OrmItem } from "@prisma/client"; // Example import
  
  // Explicitly define application's Item type
  export interface AppItem extends Omit<OrmItem, "createdAt" | "updatedAt"> {
    createdAt: Date;
    updatedAt: Date;
  }
  
  // Extend for views needing related data
  export interface AppItemWithDetails extends AppItem {
    // user: AppUser; // Example related type
    // ... other relations
  }
  
  

1.4. Zod Schemas (e.g., src/lib/schemas/)

• Purpose: Define rules for runtime data validation. Crucial for data coming into your application (API request bodies, form inputs). Ensures data shape and specific constraints (min/max length, format, etc.).