Getting Started

Overview

This guide will help you set up the Next.js SaaS Template and get your development environment running. Follow these steps to go from zero to a working local instance.

What You'll Need

Before starting, ensure you have:

• Node.js 20+ (LTS recommended)
• PostgreSQL (local or remote instance)
• npm or pnpm package manager
• Basic knowledge of TypeScript and React

Quick Start Path

1. Installation - Clone, install dependencies, and configure environment
2. Quick Start - Run the app and create your first feature
3. Project Structure - Understand the folder organization

What's Next?

After completing the getting started guide, explore:

• Architecture - Understand the tech stack and design principles
• Patterns - Learn the 5-file feature pattern and conventions
• Templates - Step-by-step guides for common tasks
• Development - AI agent setup and development workflows

Key Concepts to Know

Feature-Based Architecture

Everything is organized around features in src/features/. Each feature follows a standardized 5-file pattern:

src/features/<feature-name>/
├── schema.ts      # Zod schemas and types
├── functions.ts   # Server-side database operations
├── hooks.ts       # Client-side oRPC hooks
├── fields.tsx     # Reusable form fields
└── prompts.tsx    # Dialog wrappers

Type Safety Everywhere

• All data validated with Zod schemas
• oRPC provides end-to-end type safety
• TypeScript enforced with strict mode
• Use type instead of interface everywhere

Database Operations

Database access is abstracted through createDrizzleOperations from src/db/drizzle-operations.ts:

const operations = createDrizzleOperations({ table: myTable });
await operations.listDocuments();
await operations.getDocument(id);
await operations.createDocument(data);

Error Handling

Return ActionResponse in oRPC procedures for graceful error handling:

return {
  success: true,
  message: ctx.t("toasts.saved"),
  payload: data,
} satisfies ActionResponse;

Development Philosophy

This template follows strict conventions:

• Always use type not interface
• Use double quotes for strings
• Feature-based organization keeps related code together
• Component standards - <Icon>, <H1>-<H6>, <Section>
• No arbitrary values - Use design tokens from tailwind.config.ts

See Patterns for complete guidelines.