CONVENTIONS.md

Next.js Project Conventions

Overview

These conventions outline our development standards for Next.js projects, specifically focusing on projects using the app router for components and the pages router for API calls.

Core Principles

• Prioritize package usage over custom code
• Maintain low code complexity
• Follow clean, efficient, and well-structured code patterns
• Use modern React and Next.js best practices

File Structure Conventions

1. Use .jsx extension for React components
2. Place non-page files in bracketed folders within app router:
   • (components)
   • (utils)
   • (hooks)
   • etc.

Development Guidelines

Code Organization

1. Prioritize using established packages over writing custom code
2. Opt for low complexity solutions instead of extensive custom implementations
3. Provide complete file code without referencing existing code
4. Remove unnecessary code and avoid over-engineering
5. Split files when it improves architecture
6. Use lodash utility functions to enhance code readability

Performance Optimization

1. Implement Promise.all for concurrent API requests
2. Follow Next.js performance best practices
3. Optimize component rendering and data fetching

Code Style

1. Use backticks (`) for text quotations to prevent code breaks
2. Follow consistent formatting and naming conventions
3. Implement proper error handling
4. Include appropriate TypeScript types when applicable

Analysis Process

Before implementing any solution, developers should:

1. Examine Requirements

   • Review user/client request thoroughly
   • Analyze existing codebase if applicable
   • Identify core functionality needs

2. Evaluate Structure

   • Determine new/modified file requirements
   • Plan component hierarchy
   • Consider data flow patterns

3. Optimize Architecture

   • Identify code structure improvements
   • Look for optimization opportunities
   • Apply Next.js best practices

4. Package Assessment

   • Research relevant packages/libraries
   • Evaluate build size impact
   • Consider maintenance implications

5. Code Review

   • Check for unnecessary complexity
   • Identify potential optimizations
   • Look for removable code

Implementation Checklist

Before submitting code, ensure:

• All new files use correct extensions
• Components are properly organized in bracketed folders
• Package dependencies are documented
• Code is optimized for performance
• Error handling is implemented
• Edge cases are considered
• Solution follows low complexity principles

File Structure Example

project/
├── app/
│   ├── (components)/
│   │   └── ExampleComponent.jsx
│   ├── (utils)/
│   │   └── helpers.js
│   └── page.jsx
└── pages/
    └── api/
        └── example.js

Code Template Examples

API Route Template

// pages/api/example.js
export default async function handler(req, res) {
  try {
    // Implementation
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

Component Template

// app/(components)/ExampleComponent.jsx
'use client';

import { useState } from 'react';

export default function ExampleComponent() {
  // Implementation
}

Maintenance

These conventions should be reviewed and updated regularly to ensure they remain aligned with evolving best practices and team needs.