Development Workflow

Establish an efficient development workflow for building features in your Next.js Prisma kit application.

Reduce friction and ship faster by following consistent file organization, development commands, and quality checks - the workflow used throughout the Next.js Prisma kit.

A predictable development workflow eliminates decision fatigue and helps you focus on building features rather than wondering where to put files or which commands to run. The Next.js Prisma kit follows conventions that scale: feature directories with predictable structures, git branches per feature, and quality checks before every commit.

The development workflow is the set of commands, file conventions, and practices you follow when building features. It establishes consistency across your team and makes the codebase navigable as it grows.

Start Development Server

If you have not yet setup your development environment, please refer to the Installation guide for more information.

To run the development server, run the following command:

# Start all apps and packages
pnpm dev
# Development server runs at:
# - Web app: http://localhost:3000

In addition to the Next.js development server, make sure to also start the Database service. We've discussed this in the Installation - so please refer to that section for more information.

File Organization

Consistent file organization makes your codebase navigable. Each feature lives in its own directory with a predictable structure:

apps/web/app/[locale]/(internal)/dashboard/
├── feature/
│   ├── page.tsx                              # Route page
│   ├── _lib/
│   │   ├── actions/
│   │   │   └── feature-server-actions.ts     # Server actions
│   │   ├── schemas/
│   │   │   └── feature.schema.ts             # Validation schemas
│   │   └── loaders/
│   │       └── feature-page.loader.ts        # RSC Data loading
│   └── _components/
│       ├── feature-form.tsx
│       └── feature-list.tsx

Naming Conventions:

  • Pages: page.tsx (Next.js convention)
  • Loaders: {feature}-page.loader.ts for server-side data fetching
  • Actions: {feature}-server-actions.ts for server actions (or {feature}.action.ts if you prefer)
  • Schemas: {feature}.schema.ts for Zod validation schemas
  • Components: kebab-case.tsx for all component files

While you can use any other convention that you prefer, we recommend following the ones mentioned above.

Using Packages for Features

When building features, you can use packages to share code between features. For example, if you are building a feature that is related to projects, you can create a package called projects and put the code for the projects feature in it.

packages/features/projects/
├── index.ts
├── schema.ts

You can use the command pnpm turbo gen package to generate a new package.

Note: this is not a requirement, only create packages if you're comfortable with the concept and want to use it. Placing all your features in the apps/web/app/[locale]/(internal) folder is perfectly fine and will still be organized.

Development Flow

A typical feature follows a predictable path from branch to deployment. This section outlines each step.

1. Create Feature Branch

Creating a git branch before working on a new feature or code change is a good practice. This helps you to isolate your changes from the main branch and allows you to easily revert your changes if needed, all while being able to review your changes before merging them into the main branch.

git checkout -b feature/new-feature

2. Plan Your Feature

Before writing code, break the feature into concrete steps. This prevents scope creep and ensures you don't miss critical pieces:

  1. Define the data model and validation schema
  2. Create database tables and relationships
  3. Build server actions for mutations
  4. Create UI components
  5. Connect everything in page components

If you're using AI to help you with the feature, consider using the PRD tool in our MCP server to help you plan your feature. You can find the instructions here.

I do recommending going through the following steps to better understand the feature and the codebase, even if you use AI to help you.

3. Implement Feature

Work through the layers in order. Each layer builds on the previous one, so starting with the schema ensures type safety flows through the entire stack:

  1. Schema - Define types and validation with Zod
  2. Database - Create tables and push changes
  3. Server Actions - Implement business logic
  4. Components - Build the UI
  5. Page - Wire everything together

4. Verify Quality

Before committing, run these checks to catch issues early. Type errors and lint issues are easier to fix while the code is fresh in your mind:

# Check types
pnpm typecheck
# Fix linting issues
pnpm lint:fix
# Format code
pnpm format:fix

5. Commit Changes

When you have completed working on your new feature, you can commit and push the branch to your Git repository.

git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature

From Github (or other Git hosting provider), you can create a pull request to review your changes. Some AI services can help you debug and review your PR before merging it into the main branch. It's a decent additional "pair of eyes" to help you catch issues before they reach production.

Common Pitfalls

  • Skipping pnpm typecheck: Type errors caught early are easier to fix. Run before every commit.
  • Committing without running lint:fix: Inconsistent formatting creates noisy diffs and merge conflicts.
  • Forgetting to start the database: The dev server runs, but database operations fail silently. Start Postgres before pnpm dev.
  • Wrong directory structure: Placing components outside _components/ or logic outside _lib/ makes code harder to find.
  • Large commits: Break features into logical commits. Easier to review, easier to revert.
  • Mixing concerns: Keep loaders, actions, and schemas in separate files. One responsibility per file.

Frequently Asked Questions

What's the difference between _lib/ and _components/?
The _lib/ directory holds server-side logic: actions, loaders, and schemas. The _components/ directory holds React components. The underscore prefix tells Next.js not to treat these as routes.
Should I create a package for every feature?
No. Use packages/features/ only for code shared across multiple apps or teams. For most features, keep code in the app directory - it's simpler and easier to maintain.
Why use feature branches?
Feature branches isolate your changes, enable code review via pull requests, and let you work on multiple features without conflicts. They also make it easy to revert a feature if needed.
How often should I run the quality checks?
Run pnpm typecheck and pnpm lint:fix before every commit. This catches issues while the code is fresh in your mind and prevents broken builds.

Next: Adding Features →