# Development Guide

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

*Canonical: https://makerkit.dev/docs/nextjs-prisma/development-guide/overview*

---

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](/courses/nextjs-prisma/course).

## Documentation Structure

| Page | Purpose |
|------|---------|
| [Development Workflow](./development-workflow) | Daily development process and file organization |
| [Adding Features](./adding-features) | Complete step-by-step feature tutorial |
| [Server Actions](./server-actions) | Type-safe mutations with authentication |
| [Action Middleware](./action-middleware) | Authentication and authorization configuration |
| [Working with Forms](./working-with-forms) | Client-side forms with validation |
| [Database Operations](./database-operations) | Query 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.

{% faq
   title="Frequently Asked Questions"
   items=[
     {"question": "Where should I put my feature code?", "answer": "Create a directory under apps/web/app/[locale]/(internal)/ with _lib/ for logic and _components/ for UI. If logic becomes broadly reusable, extract it into a domain package under packages/."},
     {"question": "Should I use API routes or server actions?", "answer": "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."},
     {"question": "How do I handle errors in server actions?", "answer": "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."},
     {"question": "Can I share code between features?", "answer": "Yes. For shared logic, create a package under packages/ using the repo's domain structure. For simpler cases, export from a shared _lib/ directory. Use pnpm turbo gen package to scaffold new packages."}
   ]
/%}

---

**Next:** [Development Workflow →](./development-workflow)