Development Guide

Learn how to develop features and extend your Next.js Prisma kit application with server actions, forms, and database operations.

Build production-ready features in your Next.js Prisma kit by following consistent patterns for server actions, forms, and database operations - from schema definition through to the user interface.

The Next.js Prisma kit provides a layered architecture where each piece builds on the previous: Zod schemas define validation, Prisma handles database operations, server actions wrap business logic with authentication, and forms connect everything to the UI. Following these patterns ensures type safety flows through your entire stack and makes your codebase navigable as it grows.

The development guide covers the conventions and patterns used throughout the Next.js Prisma kit for building features. It establishes a predictable workflow: schema → database → server action → form → page.

For a more complete guide, please refer to the Course.

Documentation Structure

PagePurpose
Development WorkflowDaily development process and file organization
Adding FeaturesComplete step-by-step feature tutorial
Server ActionsType-safe mutations with authentication
Action MiddlewareAuthentication and authorization configuration
Working with FormsClient-side forms with validation
Database OperationsQuery and mutation patterns with Prisma

The Development Stack

Each layer in the stack has a specific responsibility:

┌─────────────────────────────────────┐
│  Page (Server Component)            │  Fetches data, renders UI
├─────────────────────────────────────┤
│  Form (Client Component)            │  User input, validation
├─────────────────────────────────────┤
│  Server Action + Middleware         │  Business logic, auth
├─────────────────────────────────────┤
│  Prisma ORM                         │  Database operations
├─────────────────────────────────────┤
│  Zod Schema                         │  Validation (shared)
└─────────────────────────────────────┘

Common Pitfalls

  • Skipping validation: Always define Zod schemas first - they're used on both client and server.
  • Forgetting organization scope: Every database query must filter by organizationId to maintain multi-tenancy.
  • Manual auth checks: Use authenticatedActionClient instead of rolling your own authentication.
  • Missing 'use server': Server action files must start with this directive or they won't work.
  • Catching redirect errors: Next.js redirects throw special errors that must propagate - don't swallow them.
  • N+1 queries: Use Prisma's include to fetch related data in one query instead of looping.

Frequently Asked Questions

Where should I put my feature code?
Create a directory under apps/web/app/[locale]/(internal)/ with _lib/ for logic and _components/ for UI. Use packages/features/ only for shared cross-app code.
Should I use API routes or server actions?
Use server actions for form submissions and mutations called from React components. Use API routes for webhooks, external integrations, or when you need custom request/response handling.
How do I handle errors in server actions?
The authenticatedActionClient returns errors in a consistent format. On the client, check result.serverError and result.validationErrors. Use toast.promise for automatic loading/error states.
Can I share code between features?
Yes. For shared logic, create a package in packages/features/. For simpler cases, export from a shared _lib/ directory. Use pnpm turbo gen package to scaffold new packages.

Next: Development Workflow →