Next.js SSR Project Development Rules

These rules define the architecture and coding standards for this Next.js project.

Supported AI IDEs: - Cursor - Windsurf - GitHub Copilot - VS Code AI tools - JetBrains AI Assistant

Framework: Next.js (App Router) Language: TypeScript Rendering: Server Components + SSR

Core Principles

Always prioritize:

1. Server Components
2. SSR data fetching
3. Type safety
4. Separation of concerns
5. Scalable folder structure

Avoid unnecessary client components.

Project Folder Structure

Use the following structure.

app/ (api)/ (auth)/ dashboard/ layout.tsx page.tsx

components/ ui/ forms/ shared/

services/ api/ server/

lib/ db/ auth/ config/

hooks/ types/ utils/ constants/ styles/

Rules: - UI components → components/ - API communication → services/api - Server logic → services/server - Shared utilities → utils - Types → types

Rendering Rules

Default behavior must be Server Components.

Example:

export default async function Page() {  const users = await getUsers()
  return (    <div>      {users.map(user => (        <p key={user.id}>{user.name}</p>      ))}    </div>  )}

Only use client components when needed.

Client component must start with:

"use client"

SSR Data Fetching Rules

Always fetch data on the server.

Example:

async function getUsers() {  const res = await fetch("https://api.example.com/users", {    cache: "no-store"  })
  return res.json()}

Rules: - Prefer fetch() inside server components - Use revalidate for caching - Avoid client-side API calls unless required

Server Actions Rules

Use Server Actions for mutations.

Example:

"use server"
export async function createUser(formData: FormData) {  const name = formData.get("name")
  await db.user.create({    data: { name }  })}

Rules: - All mutations must be server actions - Never expose secrets to client components

API Route Rules

Location:

app/api/

Example:

app/api/users/route.ts

Example API handler:

export async function GET() {  return Response.json({ success: true })}

Rules: - API routes should only contain request handling - Business logic must live in services

Component Rules

Component guidelines: - Functional components only - Keep components small - Separate UI and logic

Example:

components/UserCard.tsx

Example:

type Props = {  name: string}
export function UserCard({ name }: Props) {  return <div>{name}</div>}

TypeScript Rules

Strict TypeScript must be used.

Never use: any

Always type: - Props - API responses - Services

Example:

type User = {  id: string  name: string  email: string}

Service Layer Rules

All API logic must live in services.

Example structure:

services/ api/ userService.ts authService.ts

Example:

export async function getUsers(): Promise<User[]> {  const res = await fetch("/api/users")  return res.json()}

Rules: - UI components must not call APIs directly - Use service functions

SEO Rules

Always use Next.js metadata API.

Example:

export const metadata = {  title: "Dashboard",  description: "User dashboard"}

Performance Rules

Always use built-in Next.js optimizations.

Required tools: - next/image - next/font - dynamic imports

Example:

import Image from "next/image"

Environment Variables

Secrets must live in:

.env.local

Example:

DATABASE_URL= NEXT_PUBLIC_API_URL= JWT_SECRET=

Rules: - Server secrets must never be exposed to client components

Error Handling

Use proper error boundaries.

Example:

app/error.tsx

Example:

export default function Error({ error }) {  return <div>Something went wrong</div>}

Naming Conventions

Components → PascalCase Hooks → camelCase starting with use Services → camelCase

Examples: UserCard.tsx useAuth.ts userService.ts formatPrice.ts

Testing Rules

Testing tools: - Jest - React Testing Library

Example test file:

UserCard.test.tsx

Code Quality Rules

Never: - Use any - Put business logic inside UI - Fetch data inside client components unnecessarily - Duplicate logic

Always: - Write reusable components - Use proper types - Follow folder structure - Keep components small