Next.js 15+ Best Practices & Project Organization

A comprehensive skill for building high-quality Next.js 15+ applications with strong typing, functional patterns, and systematic project documentation.

Core Coding Principles

Code Quality & Style

1. **TypeScript First**

- Write concise, maintainable, strongly typed code

- Use accurate TypeScript implementations throughout

- Prefer type inference where appropriate

2. **Functional & Declarative**

- Embrace functional, declarative programming patterns

- Avoid OOP and classes

- Use pure functions and immutable data structures

3. **File Organization**

- Limit files to maximum 150 lines

- Refactor into smaller modules when exceeded

- Use lowercase with dashes for directories/files: `components/auth-wizard`

- Favor named exports for components

4. **Naming Conventions**

- Use descriptive, semantic variable names

- Include auxiliary verbs: `isLoading`, `hasError`, `canSubmit`

- Functions should be verb-based: `fetchUserData`, `handleSubmit`

5. **Code Reusability**

- Apply DRY (Don't Repeat Yourself) principles consistently

- Prefer iteration and modularization over duplication

- Use RORO pattern (Receive an Object, Return an Object) for function parameters/returns

6. **Performance & Quality**

- Monitor Web Vitals (LCP, CLS, FID)

- Conduct regular code reviews

- Perform frequent refactoring sessions

Stack & Framework Implementation

Next.js 15+ Specifics

- Offline capabilities

- App-like experience

- Cross-device installability

State Management

UI Components

Monorepo Structure (if applicable)

Project Documentation Workflow

Build Notes System

**Purpose:** Track progress and decisions for each task group systematically.

**Location:** `/ProjectDocs/Build_Notes/`

**Naming Convention:** `<build-title>_phase-<#>_<task-group-name>.md`

**Example:** `supabase-schema-standardization_phase-1_preparation-and-code-analysis.md`

**File Structure:**

```markdown

[Task Title]

Task Objective

[Brief summary of what you aim to achieve]

Current State Assessment

[Description of current project state related to this task]

Future State Goal

[Description of desired future state]

Implementation Plan

1. **Step Name**

- [ ] Task 1

- [ ] Task 2

- [x] Completed task (checked)

- ~~Not applicable task~~ (struck through, never deleted)

2. **Next Step**

- [ ] Task 1

...

```

**Update Guidelines:**

1. **At Task Start:** Create file with initial plan before coding

2. **During Execution:** Add updates when plans change or issues arise

3. **At Completion:** Append summary verifying alignment with objective

4. **Never delete tasks** — strike through if not applicable

5. **Append new steps/tasks** as plan evolves

**Completion Workflow:**

Project Context Files

**Master Context:** `/ProjectDocs/contexts/projectContext.md`

**Additional Context Files:**

**Change Management:**

Implementation Steps

When working on any task, follow this workflow:

1. **Review Context**

- Read `/ProjectDocs/contexts/projectContext.md`

- Check relevant supplementary context files

2. **Create/Open Build Notes**

- Navigate to `/ProjectDocs/Build_Notes/`

- Create or open appropriate task notes file

- Document Task Objective, Current State, Future State, Implementation Plan

3. **Code with Standards**

- Follow TypeScript and functional programming principles

- Keep files under 150 lines

- Use proper naming conventions

- Apply DRY principles

- Leverage Next.js 15+ App Router patterns

- Minimize client-side code

4. **Update Build Notes**

- Check off completed tasks

- Strike through non-applicable items

- Append new steps if plan evolves

- Document decisions and changes

5. **Verify Quality**

- Ensure Web Vitals are maintained

- Conduct code review

- Verify alignment with context files

6. **Complete Task**

- Append completion summary to build notes

- Move completed build notes to appropriate directory

- Update context files if major changes occurred

Key Constraints