PAELLADOC

--- title: "Next.js Coding Style Guide and Best Practices" date: 2025-03-22 author: "PAELLADOC" version: 1.0 status: "Active" tags: ["Next.js", "React", "frontend", "SSR", "TypeScript"] --- # Next.js Coding Style Guide and Best Practices ## Project Structure - Organize by feature rather than file type - Use the `/app` directory for new projects, leveraging React Server Components - Keep API routes in `/app/api` with a clear naming structure - Place reusable UI components in `/components` - Store global styles in `/styles` with component-specific styles alongside components - Use `/lib` for utility functions and shared logic - Store types and interfaces in `/types` or alongside their components - Maintain constants and configuration in `/config` - Keep middleware in a separate `/middleware` directory ## Core Conventions - Use TypeScript for type safety and better developer experience - Follow a consistent naming convention (PascalCase for components, camelCase for functions) - Implement proper error boundaries for fault tolerance - Structure pages with clear, logical routing patterns - Prefer functional components over class components - Implement comprehensive metadata for SEO - Document complex components with JSDoc or similar ## Component Architecture - Create small, reusable components with single responsibilities - Implement proper prop validation with TypeScript interfaces - Use React.memo for components that render often with the same props - Apply composition over inheritance for component extension - Implement appropriate error boundaries around complex components - Use React Context for state that needs to be accessed by many components - Separate logic from presentation using custom hooks ## Routing and Navigation - Use file-based routing according to Next.js conventions - Implement dynamic routes for content-based pages - Use shallow routing for URL updates without running data fetching methods - Implement proper middleware for route protection and redirects - Prefer Link component for client-side navigation - Use Next.js router hooks for programmatic navigation - Handle 404 pages with custom not-found pages ## Data Fetching - Use React Server Components for server-side data fetching where appropriate - Implement proper caching strategies using Next.js cache - Use SWR or React Query for client-side data fetching with stale-while-revalidate - Handle loading states and errors consistently - Implement incremental static regeneration for semi-dynamic content - Cache expensive operations where possible - Use proper error boundaries around data-fetching components ## State Management - Use React's useState and useReducer for local component state - Implement React Context for global state when appropriate - Consider Zustand, Jotai, or Redux for complex applications - Keep state management consistent throughout the application - Use server state management tools for remote data - Document state management patterns used in the project - Implement proper hydration techniques for server-rendered state ## Styling - Use CSS Modules or Tailwind CSS for component styling - Maintain a consistent styling approach throughout the project - Implement responsive design using modern CSS features - Use CSS variables for theming and consistent values - Consider component library integration for consistent UIs - Optimize for dark mode and accessibility - Use styled-jsx for component-scoped CSS when appropriate ## Performance Optimization - Implement code-splitting with dynamic imports - Use Image component for optimized image loading - Implement proper lazy loading for below-the-fold content - Use Next.js automatic static optimization when possible - Configure proper caching headers for static assets - Monitor and optimize bundle size - Implement virtualization for large lists - Use web workers for CPU-intensive tasks ## SEO and Metadata - Implement proper metadata for all pages using Next.js metadata API - Create a comprehensive sitemap.xml strategy - Implement structured data / JSON-LD for rich search results - Use proper semantic HTML throughout - Implement Open Graph and Twitter card metadata - Use robots.txt for search engine crawling control - Implement canonical URLs for duplicate content ## API Routes - Structure API routes logically, mirroring frontend routes where appropriate - Implement proper request validation - Use consistent error handling and response formats - Implement rate limiting for public APIs - Add appropriate caching headers - Secure endpoints with proper authentication and authorization - Document API endpoints comprehensively ## Testing - Write unit tests for utility functions and hooks - Implement component tests for UI elements - Write integration tests for key user flows - Use end-to-end tests for critical paths - Implement visual regression testing for UI components - Mock external services and API calls in tests - Aim for high test coverage on critical application paths ## Internationalization - Use Next.js internationalization features for multi-language support - Implement proper locale detection and switching - Structure translations in an organized, maintainable way - Support right-to-left languages where needed - Consider cultural differences in UI design - Use proper date, time, and number formatting based on locale - Test thoroughly with different languages and RTL layouts ## Authentication and Authorization - Implement secure authentication using trusted libraries or services - Use proper JWT handling with secure cookies - Implement role-based access control where appropriate - Secure API routes with proper middleware - Use Next.js middleware for route protection - Implement proper session management - Follow OWASP security best practices ## Deployment and Infrastructure - Use Vercel or similar platforms for optimal Next.js deployment - Implement proper environment variable management - Configure CI/CD pipelines for automated testing and deployment - Use feature branches and preview deployments - Implement proper logging and monitoring - Configure proper error tracking - Use content delivery networks for global performance ## Accessibility - Follow WCAG 2.1 AA standards at minimum - Implement proper semantic HTML - Ensure keyboard navigation works throughout the application - Add proper ARIA attributes where needed - Test with screen readers and accessibility tools - Ensure sufficient color contrast and text sizing - Implement proper focus management