Development Guide

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

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

The Development Guide is a reference for building features in the Next.js Drizzle kit, covering the schema-to-UI workflow that ensures type safety across your entire stack.

The Next.js Drizzle kit provides a layered architecture where each piece builds on the previous: Zod schemas define validation, Drizzle 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 Drizzle 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

OrderPagePurpose
1Development WorkflowDaily development process and file organization
2Adding FeaturesComplete step-by-step feature tutorial
3Server ActionsType-safe mutations with authentication
4Action MiddlewareAuthentication and authorization configuration
5Working with FormsClient-side forms with validation
6Database OperationsQuery and mutation patterns with Drizzle

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
├─────────────────────────────────────┤
│  Drizzle 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 Drizzle joins 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 →