When establishing a Next.js boilerplate repository, a senior software engineer would advise considering the following best practices and standard operating procedures (SOPs):

Project Structure and Organization:

• Clear Folder Structure: Establish a logical and consistent file and folder structure (e.g., src/pages, src/components, src/lib, src/styles, src/utils). This enhances navigability and maintainability.

• Modularity: Design components and utility functions to be modular and reusable, promoting code reusability and reducing redundancy. • Co-location: Group related files and components together where it makes sense, improving discoverability and understanding.

Development Tooling and Configuration:

• TypeScript: Integrate TypeScript for type safety, improved code quality, and better developer experience.

• ESLint and Prettier: Configure ESLint for code linting and Prettier for consistent code formatting, ensuring adherence to coding standards.

• Husky and Lint-Staged: Implement pre-commit hooks with Husky and Lint-Staged to automatically run linters and formatters on staged files, preventing inconsistent code from entering the repository.

• Environment Variables: Clearly define and manage environment variables (e.g., API keys, database URLs) for different environments (development, staging, production).

Performance Optimization:

• SSR, SSG, and ISR: Understand and strategically utilize Server-Side Rendering (SSR), Static Site Generation (SSG), and Incremental Static Regeneration (ISR) based on the content's dynamism and performance requirements.

• Image Optimization: Integrate Next.js's Image component and optimize image assets for faster loading times.

• Caching Strategies: Implement effective caching mechanisms (e.g., request memorization, data cache, router cache) to minimize server load and improve user experience.

Testing and Quality Assurance:

• Testing Framework: Integrate a robust testing framework (e.g., Jest, React Testing Library) and establish a clear testing strategy (unit, integration, end-to-end tests).

• Code Coverage: Set up code coverage reporting (e.g., Codecov) to monitor and ensure adequate test coverage.

Deployment and CI/CD:

• Version Control: Utilize Git and establish a clear branching strategy (e.g., Gitflow, GitHub Flow) for managing code versions and collaboration.

• CI/CD Pipeline: Configure a Continuous Integration/Continuous Deployment (CI/CD) pipeline (e.g., GitHub Actions, Vercel) for automated builds, tests, and deployments.

Documentation and SOPs:

• README.md: Provide a comprehensive README.md with clear instructions for setup, development, testing, and deployment.

• Contributing Guidelines: Establish clear contributing guidelines for new developers joining the project.

• Architecture Documentation: Document key architectural decisions and system design.

Security Considerations:

• Secure API Handling: Implement secure practices for handling API keys, tokens, and sensitive data.

• Authentication and Authorization: Integrate robust authentication and authorization mechanisms as needed.

By adhering to these principles and establishing clear SOPs, the Next.js boilerplate will serve as a solid foundation for building scalable, maintainable, and performant applications.

AI responses may include mistakes.

This is an excellent starting point for building the ultimate Next.js boilerplate repository. As the expert software engineer, I will draw upon the extensive details provided regarding Next.js App Router conventions, development tooling, performance optimizations, and documentation requirements to draft highly detailed prompts for each required document.

Here are the structured prompts you can use to generate the foundational documentation for your best-in-class Next.js repository:

Prompts for Documentation Generation

1. ai_guidelines.md (Central Control Document)

Prompt: Draft the ai_guidelines.md file serving as the central control document for the Next.js boilerplate. Specify that the project must strictly use the Next.js App Router to leverage modern React features. Mandate the adoption of React Server Components (RSC) as the default component type. Integrate TypeScript for robust type safety and enforce the use of Statically Typed Links by enabling typedRoutes: true in next.config.ts. Mandate Tailwind CSS for styling and the use of shadcn/ui. Emphasize that all component integration must follow the shadcn/ui Open Code philosophy rather than importing pre-compiled packages. Finally, establish that all future development prompts must strictly adhere to the documented Project Structure and Organization best practices, including colocation and the use of private folders (_folderName) for utilities.

2. requirements.md (Requirements Analysis)

Prompt: Draft the requirements.md file. Detail the fundamental software requirements for this production-ready application, including the prerequisite for Node.js v18.18.0 or later. The core application must be built using the Next.js App Router to facilitate modern features such as nested layouts and the use of React Server Components. List mandatory features based on the App Router's design principles:

1. Comprehensive Routing Capabilities covering Static Routes, Nested Routes, Dynamic Routes ([segment]), Catch-All/Optional Catch-All Routes ([...segment]/[[...segment]]), Parallel Routing (@folder), and Route Grouping ((folder)).
2. Robust Error Handling using the dedicated error.js file for runtime errors, loading.js for suspense boundaries, and not-found.js or the notFound() function for 404 handling.
3. Efficient Data Fetching using async React Server Components and server-side fetch with support for caching, revalidation, and request memoization.
4. Integration of SEO and Metadata requirements using the Next.js metadata API.

3. architecture.md (Architecture Design)

Prompt: Draft the architecture.md file outlining the system design for the boilerplate. Detail the reliance on the file-system based routing system of the Next.js App Router, where directories define routes and special files like page.js define page content. Explain how the architecture maximizes code reusability through the use of Nested Layouts (layout.js) and the component architecture. Describe the structural advantages of Colocation and the ability to structure paths without affecting the URL using Route Groups ((folderName)). Detail the usage of Parallel Routing (@slot) to render independent pages/components simultaneously within the same layout. Explain the primary data fetching paradigm: utilizing async React Server Components (RSC) to fetch data directly, noting that this allows safe performance of sensitive data requests (like database calls) without needing an intermediary API route. Finally, define the backend architecture based on Next.js Route Handlers (route.js/.ts) for developing API services supporting methods like GET, POST, PUT, DELETE, etc..

4. implementation.md (Implementation Guidelines)

Prompt: Draft the implementation.md file. Provide detailed guidelines for setting up the codebase and ensuring consistency.

1. Type Safety: Enforce the use of TypeScript and ensure the inclusion of generated Next.js types in tsconfig.json.
2. Styling and Components: Define the strategy using the utility-first philosophy of Tailwind CSS and mention key styling methods supported (Tailwind CSS, CSS Modules, Global CSS). Detail component implementation using shadcn/ui and its approach of providing direct component code for customization.
3. Routing Implementation: Instruct developers on navigating using the Link component for transitions and the useRouter hook for programmatic navigation. Note that components using hooks like useRouter must be declared as Client Components using the 'use client' directive.
4. State Management: Outline implementation using the special files: loading.js (Suspense), error.js (must be a client component), and not-found.js (custom 404 page).
5. SEO/Optimization: Require using the export const metadata = {} or generateMetadata() convention in the App Router for SEO metadata. Mandate strategic utilization of SSR, SSG, and ISR, along with Image and Font Optimization.

5. testing.md (Testing Approach)

Prompt: Draft the testing.md file defining the Quality Assurance strategy. Specify the integration of a robust testing framework such as Jest and React Testing Library as development dependencies. Detail the need for a clear testing strategy encompassing unit, integration, and end-to-end tests. Establish the mandatory requirement for Code Coverage reporting to ensure adequate test coverage is maintained. Ensure the plan requires testing critical Next.js features, including:

1. Functionality of all major route types (Static, Dynamic, Nested, Parallel).
2. Validation of programmatic navigation using the useRouter hook methods (push, replace, prefetch).
3. Confirmation that the specialized files, error.js and not-found.js, correctly intercept and display expected errors and 404 states.

6. security.md (Security Considerations)

Prompt: Draft the security.md file addressing key concerns for a Next.js application. Outline secure practices for handling API keys, tokens, and sensitive data. Mandate the clear definition and management of Environment Variables for different stages (development, production) using .env files. Highlight the security benefit of using React Server Components (RSC) for data fetching, as this allows direct, safe execution of sensitive operations (like database queries) on the server, preventing credentials from leaking to the client. Require the integration of robust Authentication and Authorization mechanisms, noting that features like NextAuth.js and Middleware are common components for protecting dashboard pages.

7. sop.md (Standard Operating Procedures)

Prompt: Draft the sop.md (Standard Operating Procedures) file detailing the required operational workflow and code management standards for the project.

1. Version Control: Specify the utilization of Git with a clear branching strategy (e.g., Gitflow or GitHub Flow).
2. Code Quality Enforcement: Establish the use of Husky and Lint-Staged to run linters and formatters (ESLint, Prettier) on staged files automatically before committing.
3. Development Structure: Enforce adherence to the Next.js Project Structure, including the recommendation to use the optional src/ directory to separate application code from configuration files.
4. Deployment: Define the CI/CD Pipeline using services like GitHub Actions or Vercel for automated builds, testing, and deployment.
5. Documentation Maintenance: Stipulate the required project documentation: a comprehensive README.md, clear Contributing Guidelines, and consistent maintenance of the Architecture Documentation.
6. Next.js Utility Usage: Document the correct use of navigation elements, specifically reserving the native anchor tag (<a/>) for external links, and using the Next.js Link component for internal application navigation.

ai_guidelines.md

AI Development Guidelines for Next.js Boilerplate

This document serves as the central control mandate for all development work, ensuring consistency, maintainability, and optimal performance of the Next.js boilerplate. All future prompts and development implementations must strictly adhere to these principles.

1. Core Framework and Routing Mandates

The boilerplate must exclusively utilize the Next.js App Router and leverage modern React features.

1.1 App Router Requirement

The project must strictly use the Next.js App Router. This is the recommended approach for new projects and offers significant improvements over previous page routers. The App Router leverages the benefits and updates introduced in the latest version of React (React 18 and later), including the use of React canary releases built-in.

1.2 Default Component Type: React Server Components (RSC)

React Server Components (RSC) are mandated as the default component type. The App directory enforces server-side rendering by default and makes use of RSC.

• RSC Benefits: Each page under a route in the App Router is a ReactJS server component. RSC reduces the amount of client-side code that needs to be loaded, improving application performance.
• Data Fetching: For data fetching, developers should use fetch and async APIs directly within Server Components. Since RSCs perform requests on the server, sensitive data requests (like database calls) can be performed directly without needing an intermediary API route, as credentials or secrets are not leaked to the client.

2. Type Safety and Linking

TypeScript must be integrated for robust type safety and improved code quality.

2.1 Statically Typed Links

To enhance type safety when navigating between pages and prevent typos and errors when using next/link, Statically Typed Links must be enforced.

This feature requires enabling typedRoutes: true in the Next.js configuration.

Implementation in next.config.ts:

typescriptCopy
1import type { NextConfig } from 'next'
2
3const nextConfig: NextConfig = {
4    typedRoutes: true, // Mandates statically typed links
5}
6
7export default nextConfig

When enabled, Next.js validates literal href strings and types next/navigation methods like push, replace, and prefetch within the App Router.

3. Styling and UI Library

3.1 Styling with Tailwind CSS

Tailwind CSS is mandated for all styling needs. Tailwind CSS uses a utility-first approach, scanning components for class names and generating corresponding styles.

3.2 UI Component Strategy: shadcn/ui and Open Code

The UI components must be sourced using shadcn/ui.

• Open Code Philosophy Mandate: Component integration must strictly follow the shadcn/ui Open Code philosophy. Shadcn/ui is explicitly not a traditional component library where pre-compiled packages are imported from NPM.
• Integration Method: Developers must integrate components by obtaining the actual component code, allowing for full transparency and easy customization. This allows developers to directly edit the source code, avoiding the need for wrapping components or writing workarounds to override styles.
• Composition: All components should share a common, composable interface, making them predictable.

4. Project Structure and Organization

All future development prompts and implementations must strictly adhere to the documented Project Structure and Organization best practices.

4.1 Colocation

Colocation is mandated for improved code structure, organization, and developer experience. Related files and components should be grouped together where it makes sense.

• In the App Router, files can be safely colocated inside route segments in the app directory without accidentally being routable, as only the content returned by page.js or route.js is sent to the client.

4.2 Private Folders for Utilities

To separate implementation details from the routing logic and organize internal files consistently, the use of Private Folders is mandated for utilities, hooks, or shared components.

• Naming Convention: Private folders must be created by prefixing a folder with an underscore: _folderName.
• Routing Exclusion: Prefixing a folder with an underscore opts the folder and all its subfolders out of the routing system, signifying it as a private implementation detail.
• Use Cases: These folders are a safe place for non-routable files such as UI utilities (_components) or data utilities (_lib).

requirements.md

1. System Prerequisites

To ensure stable development and deployment of the application, the following environment prerequisites must be met:

| Requirement | Details | Source | | :--- | :--- | :--- | | Node.js | v18.18.0 or later must be installed. Next.js installation typically requires Node.js v18.x or above. | | | Next.js | The latest stable version of Next.js should be used, with the App Router enabled during project creation. | | | Development OS | Support for macOS, Windows (including WSL), or Linux operating systems. | |

2. Core Application Framework

The application must be built as a full-stack web application using the Next.js App Router, leveraging modern React features for optimal performance and structure.

| Requirement | Details | Source | | :--- | :--- | :--- | | Framework | The core application must exclusively utilize the Next.js App Router. The App Router is the recommended approach for new projects, replacing the older Pages Router. | | | Component Architecture | The application must leverage the capabilities of React Server Components (RSC), which the App Router supports. Each route page (page.js or .tsx) is, by default, a ReactJS server component. | | | Layout Management | The application structure must utilize the App Router's file-system based routing to implement nested layouts using the dedicated layout.js (or .tsx) file convention. Layouts defined at any level wrap their child segments. | |

3. Mandatory Features based on App Router Design Principles

3.1 Comprehensive Routing Capabilities

The application must demonstrate mastery of the file-system based routing principles of the App Router. Folders define URL segments, and a route becomes public when a page or route file exists within the directory.

| Feature | Convention/Usage | Source | | :--- | :--- | :--- | | Static Routes | Defined by directories with known route segment names (e.g., app/about/page.tsx results in /about). | | | Nested Routes | Created by nesting folders under the app/ directory (e.g., app/blog/authors/page.tsx results in /blog/authors). | | | Dynamic Routes | Parameterize segments using square brackets (e.g., [segment] or [slug]). Values are accessed via the params prop in the page component. | | | Catch-All Routes | Defined using [...segment]. This matches multiple subsequent route segments (e.g., /shop/clothing/shirts). | | | Optional Catch-All Routes | Defined using [[...segment]]. This allows matching a variable number of segments, including zero segments (e.g., /docs or /docs/pages). | | | Parallel Routing | Renders one or more pages in the same layout simultaneously. Named slots are defined using the @folder convention (e.g., @growth) and are received as props in the parent layout. | | | Route Grouping | Used for organizing routes logically without affecting the URL path. Group folders are wrapped in parentheses (e.g., (marketing)). | |

3.2 Robust Error Handling and Suspense Boundaries

The application must implement robust error management using dedicated special files and functions provided by the App Router.

| Feature | Convention/Usage | Source | | :--- | :--- | :--- | | Runtime Error Handling | Implemented using the dedicated error.js file within a route segment. The component exported from error.js must be a client component (using 'use client'). | | | Loading States / Suspense | Implemented using the loading.js file convention in a route segment to display loading UI (skeletons). This file automatically wraps the corresponding page in a <Suspense> boundary. | | | 404 Not Found UI | A customized 404 page must be implemented using not-found.js under the app/ directory to handle any unmatched routes throughout the application. | | | Programmatic 404 | The built-in notFound() function must be used within a route segment to throw the NEXT_NOT_FOUND error, which stops the current rendering process and displays the nearest not-found.js file. | |

3.3 Efficient Data Fetching

Data fetching must prioritize server-side operations using React Server Components to optimize performance and security.

| Feature | Convention/Usage | Source | | :--- | :--- | :--- | | Server Data Fetching | Data fetching must be performed directly using async React Server Components and the native server-side fetch function. This allows for direct, safe calls to sensitive resources (like databases) without needing an intermediary API route, as requests occur safely on the server. | | | Caching Support | Server-side fetch requests must utilize Next.js's built-in caching features, supporting strategies similar to getStaticProps (e.g., cache: 'force-cache'). | | | Revalidation Support | Fetch requests must support time-based revalidation to fetch data at specific intervals (similar to getStaticProps with revalidate option, e.g., next: { revalidate: 10 }). | | | Request Memoization | The application must leverage Next.js's automatic request memoization for all fetch requests within the component tree, ensuring that duplicate requests for the same data do not incur performance penalties. | |

3.4 Integration of SEO and Metadata Requirements

Search Engine Optimization (SEO) must be integrated using the Next.js metadata API conventions specific to the App Router.

| Requirement | Convention/Usage | Source | | :--- | :--- | :--- | | Metadata API | Metadata requirements must be defined in layouts or pages using the Next.js export const metadata = {} object or the generateMetadata() function. | | | Mandatory Tags | Every page must include essential SEO tags: title (keyword-focused, $\le$ 60 characters) and description (compelling, $\le$ 160 characters). | | | Social Sharing | Implementation must include Open Graph tags (og:title, og:description, og:image, og:url) and Twitter Card tags to optimize content for social sharing. | | | Generated Files | The application structure should account for file conventions for automatic SEO generation, such as sitemap.xml or sitemap.js (Generated Sitemap), and robots.txt or robots.js (Generated Robots file). | |

architecture.md

System Design Overview: Next.js App Router Boilerplate

This boilerplate utilizes the Next.js App Router, which leverages advanced features of React Server Components (RSC) and a powerful file-system based routing system to build scalable, maintainable, and performant full-stack applications.

1. Routing Architecture

The core routing system is governed by a file-system based routing convention housed within the top-level app/ directory.

• Route Definition: A directory (folder) within app/ indicates a route or a route segment, and nesting folders creates nested routes. The application's root route (/) is defined by the top-level app/ directory.
• Page Content: The page content for a specific route is defined by the special file named page.js (or .ts/.tsx) located within the corresponding route directory. A route becomes publicly accessible only when a page.js or route.js file exists within the segment.
• Dynamic Routing: Dynamic route segments are defined using square brackets in the folder name, such as [name] or [slug], allowing the creation of routes that match dynamic data.

2. Structural Organization and Reusability

The architecture maximizes code organization and reuse through colocation, nested layouts, and route grouping.

A. Colocation and Component Architecture

The Next.js App Router improves development experience through Colocation, which involves organizing and managing pages alongside other related files (like layouts and components) within the same app/ directory.

• Safety: While folders define the route structure, a route is not publicly accessible until it contains a page.js or route.js file. This means that project files (such as UI utilities or internal logic) can be safely colocated inside route segments in the app directory without accidentally becoming routable paths.
• Modularity: The architecture encourages building applications with a component architecture that follows a tree hierarchy, promoting modularity and reuse of components and utility functions.

B. Nested Layouts (layout.js)

The system employs Nested Layouts using the special layout.js file to maximize code reusability.

• Shared UI: The layout.js file is used for defining shared UI (such as headers or navigation) across multiple child routes or segments.
• Hierarchy: Layouts at any level wrap their child segments. Layout components are rendered recursively in nested routes, ensuring that the components of a child route segment are nested inside the components of its parent segment.
• Optimization: During client-side navigation between pages that share a layout, the layout does not re-render and remains interactive.

C. Route Groups ((folderName))

Route Groups allow developers to organize routes logically within the app/ directory without impacting the resulting URL path.

• Structural Advantage: Route groups are created by wrapping a folder name in parentheses, such as (marketing) or (shop). This indicates that the folder is for organizational purposes and should not be included in the route's URL path.
• Layout Scope: They are particularly useful for enabling nested layouts, allowing the creation of multiple root layouts or applying a layout to a subset of routes in a common segment.

3. Parallel Rendering

The architecture uses Parallel Routing to enhance dashboard-like features where independent sections need to render simultaneously.

• Simultaneous Rendering: Parallel Routing allows one or more pages/components to render simultaneously within the same layout.
• Named Slots: Parallel routes are defined using named slots, established with the @slot (or @folder) convention (e.g., @growth or @revenue).
• Integration: These named slots are automatically received by the parent layout component as props and are rendered within the layout's JSX structure.
• Isolation: Each parallel route can define its own independent loading state (loading.js) and error state (error.js). Note that these slots are not actual route segments and cannot be accessed via a dedicated route path.

4. Data Fetching Paradigm

The primary data fetching paradigm relies heavily on React Server Components (RSC).

• Server Component Direct Fetching: The App directory, enforcing server-side rendering by default, supports async React Server Components (RSC) which can use async/await to directly fetch data.
• Sensitive Data Requests: A key benefit is the ability to safely perform sensitive data requests (like database calls) directly in the component. Since RSCs execute all data fetching on the server, there is no risk of leaking credentials or secrets, removing the need for an intermediary API route for securing data retrieval.
• Recommendation: Next.js recommends fetching all data on the server, either via an RSC or a Route Handler.

5. Backend Architecture: Route Handlers

The backend services are developed using Next.js Route Handlers.

• API Implementation: Route Handlers implement API services, replacing the older API routes used in the Pages Router.
• File Convention: They are defined by creating a special file named route.js (or .ts) inside the relevant app folder (e.g., app/api/route.js).
• Supported Methods: Route Handlers leverage the Request and Response APIs and support standard HTTP methods, including: GET, POST, PUT, DELETE, PATH, HEAD, and OPTIONS.

implementation.md

This document outlines the foundational guidelines and standard operating procedures (SOPs) for setting up and maintaining the Next.js application codebase using the App Router. Adhering to these guidelines ensures code consistency, type safety, performance optimization, and maintainability.

1. Codebase Setup and Consistency

The project will use the Next.js App Router for all new development. The App Router is designed to leverage modern React features, such as Server Components, and provides improved structure and performance.

Project Organization:

• Structure: We utilize a logical and consistent file/folder structure. The primary application logic resides within the app/ directory. We may optionally use a src/ folder to separate application code from project configuration files.
• Colocation: Favor colocation, grouping related components, logic, and tests within their respective route directories where it makes sense. Files placed within a route segment folder that are not special files (page.js, route.js, etc.) are safe to be colocated without accidentally becoming routable.
• Utility Folders: Use private folders (prefixed with an underscore, e.g., _utils, _components) for storing utility functions and shared components, although colocation generally ensures non-routability.

2. Type Safety and Development Tooling

Mandate the use of TypeScript for improved code quality, type safety, and better developer experience.

2.1 TypeScript Configuration

Next.js provides built-in TypeScript support. When configuring or verifying the project setup:

1. Enforce TypeScript: All application files must use .ts or .tsx extensions.

2. Include Generated Next.js Types: To maintain type validation, especially for features like statically typed links, developers must ensure the generated Next.js types are included in the tsconfig.json file.

   • Verify that .next/types/**/*.ts is present in the include array of tsconfig.json:

   jsonCopy
   1// tsconfig.json excerpt
   2{
   3  "include": [
   4    "next-env.d.ts",
   5    ".next/types/**/*.ts", // This is required for generated types
   6    "**/*.ts",
   7    "**/*.tsx"
   8  ],
   9  "exclude": ["node_modules"]
   10}

2.2 Tooling

Configure essential tooling such as ESLint for code linting and Prettier for consistent code formatting.

3. Styling and Component Implementation

3.1 Styling Strategy

The primary styling strategy is the utility-first philosophy of Tailwind CSS. Tailwind CSS works by scanning HTML files and components for class names and generating corresponding styles.

Supported styling methods within the application include:

1. Tailwind CSS: Preferred method using utility classes.
2. CSS Modules: Supported for scoped component styles.
3. Global CSS: Used for defining base styles and configuration.

3.2 Component Implementation (shadcn/ui)

We will utilize shadcn/ui for high-quality, accessible components.

• Open Code Philosophy: Unlike traditional component libraries installed via NPM, shadcn/ui operates on an Open Code philosophy. Developers are handed the actual component code (distributed via a CLI).
• Customization: This approach provides full control to customize and extend components directly, making it unnecessary to wrap components or write workarounds to override styles.
• Composition: All shadcn/ui components are designed to be composable and share a common, predictable interface, promoting system consistency.
• Installation: Components are added using the command-line tool (npx shadcn@latest add <component>).

4. Routing Implementation

The Next.js App Router uses a file-system-based routing system where folders define URL segments and special files like page.js (or .tsx) define the page contents.

4.1 Navigation Between Routes

Developers should use the following methods for navigation:

1. Link Component: For declarative navigation and smooth client-side transitions, use the Link component imported from next/link. The Link component uses the href property to specify the navigation route.
2. useRouter Hook: Use the useRouter hook (from next/navigation) for programmatic navigation, such as navigating after a button click or form submission. Programmatic navigation is typically handled using methods like router.push(url) or router.replace(url).

4.2 Client Component Directive

Crucially, any component utilizing React Hooks, including useRouter from next/navigation, must be explicitly declared as a Client Component.

• This declaration is achieved by adding the 'use client' directive at the top of the file, before any import statements.

5. State Management and Error Handling

The App Router provides dedicated special files for managing loading states, errors, and unhandled routes, utilizing React Suspense and Error Boundaries.

| Special File | Purpose | Requirement/Context | | :--- | :--- | :--- | | loading.js / .tsx | Shows a loading indicator or skeleton UI for a route segment. | Automatically wraps the component in a <Suspense> boundary. This UI triggers when an asynchronous request is detected. | | error.js / .tsx | Catches unexpected runtime errors within a route segment or its children. | The exported React component must be a Client Component and include the 'use client' directive at the top. | | not-found.js / .tsx | Defines a custom UI for unmatched routes, serving as a custom 404 page. | This special file must export a React component. It can also be invoked programmatically using notFound(). |

6. SEO and Performance Optimization

All pages must prioritize SEO and performance optimizations.

6.1 SEO Metadata

In the Next.js App Router, metadata handling utilizes specific conventions.

• Requirement: For defining SEO metadata, developers must use the export const metadata = {} object or the generateMetadata() function.
• Content: Each page must include essential metadata such as title, meta description, Open Graph tags (e.g., og:title, og:image), and Twitter Card tags.

6.2 Strategic Rendering and Data Fetching

Mandate the strategic utilization of server-side rendering (SSR), static site generation (SSG), and incremental static regeneration (ISR) based on content dynamism.

In the App Router, data fetching uses the standard fetch API and Async React Server Components. Next.js manages caching and rendering based on fetch options:

| Rendering Type | Next.js App Router Data Fetching equivalent | fetch Options | | :--- | :--- | :--- | | Static Site Generation (SSG) | Cached until manually invalidated (similar to getStaticProps). | cache: 'force-cache' (default) | | Incremental Static Regeneration (ISR) | Cached with a specific lifetime (similar to getStaticProps with revalidate). | next: { revalidate: N } | | Server-Side Rendering (SSR) | Refetched on every request (similar to getServerSideProps). | cache: 'no-store' |

6.3 Optimization Assets

• Image Optimization: Developers must integrate the Next.js Image component and optimize image assets for faster loading times.
• Font Optimization: Utilize Next.js Font Optimization to improve web performance.

testing.md:

Quality Assurance Strategy

1. Quality Assurance Strategy Overview

The Quality Assurance strategy mandates the integration of robust testing practices throughout the development lifecycle to ensure the scalability, reliability, and maintainability of the Next.js application. This strategy requires a tiered approach to testing, encompassing unit, integration, and end-to-end (E2E) tests.

2. Testing Framework and Dependencies

A robust testing framework must be integrated to facilitate comprehensive quality assurance.

2.1 Development Dependencies

The following tools shall be included in the project's devDependencies to establish a standard testing environment:

| Tool | Purpose | Source Support | | :--- | :--- | :--- | | Jest | Primary JavaScript testing framework. | Found listed in devDependencies as jest and related configurations (@types/jest, jest-environment-jsdom). | | React Testing Library (RTL) | Utility for testing React components, focusing on user experience. | Found listed in devDependencies as @testing-library/react and @testing-library/jest-dom. |

2.2 Code Coverage Requirement

It is a mandatory requirement to set up and maintain code coverage reporting. Code coverage tracking must be implemented (e.g., using a service like Codecov) to monitor and ensure adequate test coverage is consistently maintained across the application.

3. Testing Strategy: Levels of Testing

A clear testing strategy must be established, partitioning testing efforts into three primary categories:

1. Unit Tests: Focus on testing individual components and utility functions in isolation. For Next.js development, this includes ensuring modularity and reusability of components and logic.
2. Integration Tests: Focus on verifying how different parts of the application interact, such as testing data flow between components or verifying component interactions with API mock layers.
3. End-to-End (E2E) Tests: Focus on validating complete user flows from start to finish, simulating a user’s interaction with the entire application.

4. Critical Next.js Feature Testing Requirements

Given the reliance on the Next.js App Router, specific testing must be performed to confirm the correct functionality of core routing and error handling conventions.

4.1 Route Types Functionality Testing

Testing must confirm the correct behavior and accessibility of all major file-system routing patterns:

| Route Type | Next.js Convention | Testing Requirement | Source Support | | :--- | :--- | :--- | :--- | | Static Routes | Defined by directories containing a page.js or .tsx file (e.g., /app/page.js or /app/blog/page.js). | Validate that standard, non-dynamic paths resolve correctly and display the expected content. | | | Dynamic Routes | Defined using folders enclosed in square brackets (e.g., [slug]). | Verify that dynamic segments resolve correctly and that the page component receives the necessary parameters (params prop) to render content based on the route segment value. | | | Nested Routes | Created by nesting folders under the app/ directory (e.g., app/about/form/page.js). | Confirm that the nested URL structure is correctly mapped to the corresponding directory structure and that layouts are inherited or scoped correctly. | | | Parallel Routes | Defined using named slots (@folder convention) and rendered simultaneously within the parent layout.js file. | Verify that pages defined in parallel route slots (@growth, @revenue) render correctly when accessed via the parent route (e.g., /dashboard). Also, confirm that these slots are not directly accessible as URL segments (e.g., /dashboard/@growth should not be a route). | |

4.2 Programmatic Navigation Validation

Tests must validate the functionality of programmatic navigation using the useRouter hook, which allows changing routes without the Link component:

1. router.push(url): Validate that this method handles client-side transitions and adds a new entry to the browser history stack, as intended for standard navigation.
2. router.replace(url): Validate that this method performs navigation without adding a new entry to the history stack (similar to the replace prop on next/link), preventing the user from navigating back to the previous page using the browser back button.
3. router.prefetch(url): Validate that this method successfully prefetches the necessary resources for the target URL to ensure faster client-side transitions, particularly useful for non-standard navigations.

4.3 Specialized File Functionality Confirmation

Tests must confirm that special Next.js files correctly handle application errors and missing routes, which are critical aspects of error handling:

1. error.js (Runtime Errors): Confirm that the presence of an error.js file at a route segment correctly intercepts runtime errors occurring within that segment or its children. Verification must include ensuring the error.js component is correctly defined as a client component using the 'use client' directive.
2. not-found.js (404/Missing Routes): Confirm that not-found.js correctly intercepts and displays the expected UI when an unmatched route is visited. Furthermore, tests should confirm that invoking the notFound() function programmatically stops rendering the current segment and triggers the nearest not-found.js file.

security.md

This document outlines the mandatory security practices and architecture considerations for securing this Next.js application, focusing on handling sensitive data, environment configuration, and authorization controls.

1. Handling Sensitive Information

It is mandatory to implement secure practices for handling API keys, tokens, and sensitive data. These credentials must never be exposed directly in client-side code, and their storage and access should adhere strictly to the guidelines for environment variables and server-side operations outlined below.

2. Environment Variable Management

All sensitive configuration data, such as API keys and database URLs, must be managed using Next.js Environment Variables.

Mandates for Environment Variables:

1. Clear Definition and Management: Environment variables (e.g., API keys, database URLs) must be clearly defined and managed.
2. Staging Differentiation: Variables must be segmented based on the application stage (development, staging, production).
3. Use of .env Files: Next.js utilizes specific top-level files to define environment variables for different stages:
   • .env: General environment variables.
   • .env.local: Local environment variables.
   • .env.production: Production environment variables.
   • .env.development: Development environment variables.
4. Type Safety (Recommended): If TypeScript is enabled, Next.js can generate types for loaded environment variables during development for improved IntelliSense. Note that types are generated based on variables loaded at development runtime, excluding variables from .env.production* files unless the development server is run with NODE_ENV=production.

3. Leveraging React Server Components (RSC) for Data Security

The Next.js App Router utilizes React Server Components (RSC). This architecture provides a crucial security benefit for data fetching:

• Safe Server-Side Execution: Next.js recommends fetching all data on the server via RSCs or Route Handlers.
• Preventing Credential Leakage: Because React Server Components (RSC) execute directly on the server, sensitive operations—such as direct database calls—can be safely performed. This prevents credentials or secrets from leaking to the client, thereby removing the necessity of using an intermediary API Route (Route Handler) to hide secrets when performing data fetching.
• Direct Data Fetching: RSCs enable developers to use async/await and fetch directly within the component for data retrieval on the server.

4. Authentication and Authorization

The application must integrate robust Authentication and Authorization mechanisms to protect specific routes and resources.

Requirements:

1. Protected Routes: Features like dashboard pages must be protected by authentication.
2. Middleware Integration: Middleware (middleware.ts) is a required component for authorization logic. Middleware can inspect incoming requests and implement logic (such as checking for session tokens) before a request is completed.
3. Authentication Framework: Features like NextAuth.js are common components used in conjunction with Middleware to enforce protected routes.
4. Redirection: If a user is unauthenticated or unauthorized for a page, they must be programmatically redirected (e.g., using router.push('/login')).

sop.md:

Standard Operating Procedures and Code Management Standards

This document outlines the required operational workflow and code management standards for this project, ensuring consistency, maintainability, and quality across all development phases.

1. Version Control and Branching Strategy

All source code must be managed using Git.

1.1. Platform: The official project repository is hosted on GitHub. 1.2. Branching Strategy: The project must establish and adhere to a clear branching strategy. Developers must choose and follow either the Gitflow or GitHub Flow model for managing code versions and collaboration.

2. Code Quality Enforcement

To ensure adherence to consistent coding standards and enhance code quality, automated tooling must be configured and enforced.

2.1. Linters and Formatters:

• ESLint must be configured for code linting.
• Prettier must be configured for consistent code formatting.

2.2. Pre-commit Hooks:

• Husky and Lint-Staged must be implemented to establish pre-commit hooks.
• These hooks will automatically run configured linters and formatters (ESLint, Prettier) on staged files before a commit is finalized. This process prevents inconsistent or poorly formatted code from entering the repository.

2.3. Type Safety:

• TypeScript must be integrated for improved code quality, type safety, and a better developer experience.

3. Development Structure

The project structure must adhere to Next.js conventions, prioritizing organization and code discoverability.

3.1. Next.js App Router Structure:

• The project utilizes the Next.js App Router.
• Routes are determined by directory names, and a route is made publicly accessible when a page.js (or .ts/.tsx) or route.js file is added to a route segment.

3.2. Source Directory (src/):

• It is highly recommended that the optional src/ directory be used to house the application code (including the app/ directory).
• Utilizing the src/ directory helps separate application code from project configuration files (which typically reside in the root directory).

3.3. Modularity and Co-location:

• Components and utility functions must be designed to be modular and reusable to promote code reusability.
• Practice co-location by grouping related files and components together, especially within route segments in the app directory, where non-routable files are safe from public access.

4. Deployment

A robust CI/CD pipeline must be configured to automate the process of building, testing, and deploying the application.

4.1. CI/CD Pipeline Services:

• A Continuous Integration/Continuous Deployment (CI/CD) pipeline must be configured using services such as GitHub Actions or Vercel.
• This pipeline will ensure automated builds, tests, and deployment.

4.2. Deployment Platform:

• The application should be deployed on Vercel.

5. Documentation Maintenance

Comprehensive documentation is required for project maintenance and onboarding new developers.

5.1. README.md:

• A comprehensive README.md must be maintained.
• It must include clear instructions for project setup, development, testing, and deployment.

5.2. Contributing Guidelines:

• Clear Contributing Guidelines must be established to streamline the process for new developers joining the project.

5.3. Architecture Documentation:

• Key architectural decisions and system design must be consistently documented.

6. Next.js Utility Usage: Navigation Standards

All navigation within the application must follow Next.js best practices for performance and clarity.

6.1. Internal Navigation:

• For navigation between internal routes or pages within the Next.js application, developers must use the Next.js Link component (imported from next/link).
• The Link component is the best option for navigating routes, as it enables client-side navigation with built-in optimizations like prefetching.

6.2. External Navigation:

• The native anchor tag (<a/>) must be reserved exclusively for linking and navigating to a page that is external to the application, or for invoking specific non-navigation functions.

6.3. Programmatic Navigation:

• If programmatic route changes are necessary (e.g., triggering navigation upon a button click), the useRouter hook (from next/navigation in the App Router) should be utilized.
• The useRouter hook allows access to methods like router.push() to navigate programmatically. Note that window.location is better suited for external URLs rather than router.push.

CLine Prompt: Next.js Boilerplate Repository Creation with Observability Ledger

You are an expert software engineer tasked with creating a production-ready Next.js boilerplate repository. This boilerplate must adhere strictly to all guidelines, requirements, architecture patterns, implementation standards, testing strategies, security practices, and operational procedures documented in the existing docs/ folder.

Project Parameters

• PROJECT_NAME: [nextjs-boilerplate] (replace with actual project name)
• TECH_STACK: Next.js (App Router), React 18+, TypeScript, Tailwind CSS, shadcn/ui
• DEPLOYMENT_TARGET: [Vercel] (replace with target platform)
• NODE_VERSION: v18.18.0 or later
• REPOSITORY_HOST: [GitHub] (replace with Git hosting platform)

Phase 0: Initialize Observability Ledger (CRITICAL FIRST STEP)

Before any code generation begins, you must create docs/checklist.md as your progress tracking and observability ledger.

Step 0.1: Create Checklist Structure

Create docs/checklist.md with the following structure:

markdownCopy
1# Next.js Boilerplate - Implementation Checklist & Progress Ledger
2
3## Purpose
4This document tracks the implementation progress of the Next.js boilerplate repository, ensuring full traceability between documentation context and actual code deliverables.
5
6## Legend
7- ⬜ Not Started
8- 🟡 In Progress
9- ✅ Done
10- ❌ Blocked/Issue
11
12## Progress Overview
13| Phase | Status | Progress | Last Updated |
14|-------|--------|----------|--------------|
15| Phase 0: Ledger Setup | 🟡 | 0% | [TIMESTAMP] |
16| Phase 1: Repository Initialization | ⬜ | 0% | - |
17| Phase 2: Core Framework Setup | ⬜ | 0% | - |
18| Phase 3: Type Safety & Tooling | ⬜ | 0% | - |
19| Phase 4: Styling & UI Components | ⬜ | 0% | - |
20| Phase 5: Project Structure | ⬜ | 0% | - |
21| Phase 6: Routing Implementation | ⬜ | 0% | - |
22| Phase 7: Data Fetching & State | ⬜ | 0% | - |
23| Phase 8: Testing Infrastructure | ⬜ | 0% | - |
24| Phase 9: Security Hardening | ⬜ | 0% | - |
25| Phase 10: CI/CD Pipeline | ⬜ | 0% | - |
26| Phase 11: Performance & SEO | ⬜ | 0% | - |
27| Phase 12: Documentation | ⬜ | 0% | - |
28| Phase 13: Final Validation | ⬜ | 0% | - |
29
30---
31
32## Detailed Task Tracking
33
34[Task sections will be populated as you progress through each phase]

Step 0.2: Update Ledger After Each Task

After completing each task in subsequent phases:

1. Update the task status (⬜ → 🟡 → ✅)
2. Add timestamp
3. Link to relevant docs context
4. Note any deviations or decisions made
5. List next actions

Commit the checklist after every major milestone.

Phase 1: Repository Initialization

Docs Context References:

• docs/sop.md (Section 1: Version Control)
• docs/requirements.md (Section 1: System Prerequisites)

Task 1.1: Initialize Git Repository ⬜

Action Steps:

1. Initialize a new Git repository
2. Create .gitignore for Next.js (node_modules, .next, .env.local, etc.)
3. Set up initial branch structure (main/develop based on chosen Git Flow strategy)

Docs Traceability:

• Reference: docs/sop.md - Section 1.2 Branching Strategy
• Requirement: Git-based version control with GitHub hosting

Checklist Update:

markdownCopy
1### Task 1.1: Initialize Git Repository ✅
2- **Status**: Done
3- **Timestamp**: [YYYY-MM-DD HH:MM]
4- **Docs Reference**: docs/sop.md#version-control
5- **Deliverables**: 
6  - ✅ .git folder initialized
7  - ✅ .gitignore created
8  - ✅ main branch established
9- **Commit**: `git commit -m "chore: initialize repository with .gitignore"`
10- **Next Action**: Task 1.2

Task 1.2: Initialize Next.js Project ⬜

Action Steps:

1. Run npx create-next-app@latest [PROJECT_NAME] with following selections:
   • ✅ TypeScript
   • ✅ ESLint
   • ✅ Tailwind CSS
   • ✅ App Router (MANDATORY per docs/ai_guidelines.md Section 1.1)
   • ✅ src/ directory (recommended per docs/sop.md Section 3.2)
   • ❌ Turbopack (optional, evaluate based on stability)
2. Verify Node.js version requirement (v18.18.0+)

Docs Traceability:

• Reference: docs/ai_guidelines.md - Section 1: Core Framework
• Reference: docs/requirements.md - Section 2: Core Application Framework
• Requirement: Exclusive use of App Router

Checklist Update: Add completion details, timestamp, commit reference

Task 1.3: Configure Package.json ⬜

Action Steps:

1. Update project metadata (name, version, description, author)
2. Add custom scripts:

   jsonCopy
   1{
   2  "scripts": {
   3    "dev": "next dev",
   4    "build": "next build",
   5    "start": "next start",
   6    "lint": "next lint",
   7    "lint:fix": "next lint --fix",
   8    "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md}\"",
   9    "format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,md}\"",
   10    "test": "jest",
   11    "test:watch": "jest --watch",
   12    "test:coverage": "jest --coverage",
   13    "type-check": "tsc --noEmit",
   14    "prepare": "husky install"
   15  }
   16}

Docs Traceability:

• Reference: docs/sop.md - Section 2: Code Quality Enforcement
• Reference: docs/testing.md - Section 2: Testing Framework

Checklist Update: Track completion and commit

Phase 2: Core Framework Setup

Docs Context References:

• docs/ai_guidelines.md (Section 1.2: RSC Requirement)
• docs/architecture.md (Section 1: Routing Architecture)

Task 2.1: Configure Next.js Config ⬜

Action Steps:

1. Create/update next.config.ts with mandatory settings:

   typescriptCopy
   1import type { NextConfig } from 'next'
   2
   3const nextConfig: NextConfig = {
   4  typedRoutes: true, // MANDATORY per docs/ai_guidelines.md Section 2.1
   5  reactStrictMode: true,
   6  // Add other configuration as needed
   7}
   8
   9export default nextConfig

Docs Traceability:

• Reference: docs/ai_guidelines.md - Section 2.1: Statically Typed Links
• Requirement: typedRoutes: true must be enabled

Checklist Update: Mark complete with config snippet reference

Task 2.2: Verify App Router Structure ⬜

Action Steps:

1. Confirm app/ directory exists (or src/app/ if using src/)
2. Verify default app/layout.tsx exists
3. Verify default app/page.tsx exists
4. Ensure Server Components are default (no 'use client' in base files)

Docs Traceability:

• Reference: docs/ai_guidelines.md - Section 1.2: Default Component Type RSC
• Reference: docs/architecture.md - Section 1: Routing Architecture
• Requirement: React Server Components as default

Checklist Update: Document structure verification

Phase 3: Type Safety & Tooling

Docs Context References:

• docs/implementation.md (Section 2: Type Safety)
• docs/sop.md (Section 2: Code Quality)

Task 3.1: Configure TypeScript ⬜

Action Steps:

1. Verify/update tsconfig.json includes generated Next.js types:

   jsonCopy
   1{
   2  "compilerOptions": {
   3    "target": "ES2017",
   4    "lib": ["dom", "dom.iterable", "esnext"],
   5    "allowJs": true,
   6    "skipLibCheck": true,
   7    "strict": true,
   8    "noEmit": true,
   9    "esModuleInterop": true,
   10    "module": "esnext",
   11    "moduleResolution": "bundler",
   12    "resolveJsonModule": true,
   13    "isolatedModules": true,
   14    "jsx": "preserve",
   15    "incremental": true,
   16    "plugins": [{ "name": "next" }],
   17    "paths": {
   18      "@/*": ["./src/*"]
   19    }
   20  },
   21  "include": [
   22    "next-env.d.ts",
   23    ".next/types/**/*.ts",
   24    "**/*.ts",
   25    "**/*.tsx"
   26  ],
   27  "exclude": ["node_modules"]
   28}

2. Verify .next/types/**/*.ts is in include array

Docs Traceability:

• Reference: docs/implementation.md - Section 2.1: TypeScript Configuration
• Requirement: Include generated Next.js types for statically typed links

Checklist Update: Track TypeScript configuration

Task 3.2: Configure ESLint ⬜

Action Steps:

1. Verify .eslintrc.json exists with Next.js defaults
2. Add custom rules if needed:

   jsonCopy
   1{
   2  "extends": ["next/core-web-vitals", "next/typescript"],
   3  "rules": {
   4    "@typescript-eslint/no-unused-vars": "error",
   5    "@typescript-eslint/no-explicit-any": "warn"
   6  }
   7}

Docs Traceability:

• Reference: docs/implementation.md - Section 2.2: Tooling
• Reference: docs/sop.md - Section 2.1: Linters and Formatters

Checklist Update: Document ESLint configuration

Task 3.3: Configure Prettier ⬜

Action Steps:

1. Create .prettierrc.json:

   jsonCopy
   1{
   2  "semi": false,
   3  "trailingComma": "es5",
   4  "singleQuote": true,
   5  "tabWidth": 2,
   6  "useTabs": false,
   7  "printWidth": 100
   8}

2. Create .prettierignore:

   textCopy
   1node_modules
   2.next
   3out
   4public

Docs Traceability:

• Reference: docs/sop.md - Section 2.1: Linters and Formatters

Checklist Update: Track Prettier setup

Task 3.4: Setup Husky & Lint-Staged ⬜

Action Steps:

1. Install dependencies:

   bashCopy
   1npm install --save-dev husky lint-staged

2. Initialize Husky:

   bashCopy
   1npx husky-init && npm install

3. Create .husky/pre-commit:

   bashCopy
   1#!/usr/bin/env sh
   2. "$(dirname -- "$0")/_/husky.sh"
   3npx lint-staged

4. Add to package.json:

   jsonCopy
   1{
   2  "lint-staged": {
   3    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
   4    "*.{json,md}": ["prettier --write"]
   5  }
   6}

Docs Traceability:

• Reference: docs/sop.md - Section 2.2: Pre-commit Hooks
• Requirement: Prevent poorly formatted code from entering repository

Checklist Update: Document pre-commit hook setup

Phase 4: Styling & UI Components

Docs Context References:

• docs/ai_guidelines.md (Section 3: Styling and UI)
• docs/implementation.md (Section 3: Styling)

Task 4.1: Verify Tailwind Configuration ⬜

Action Steps:

1. Verify tailwind.config.ts exists with proper content paths:

   typescriptCopy
   1import type { Config } from 'tailwindcss'
   2
   3const config: Config = {
   4  content: [
   5    './src/pages/**/*.{js,ts,jsx,tsx,mdx}',
   6    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
   7    './src/app/**/*.{js,ts,jsx,tsx,mdx}',
   8  ],
   9  theme: {
   10    extend: {},
   11  },
   12  plugins: [],
   13}
   14export default config

2. Verify app/globals.css includes Tailwind directives

Docs Traceability:

• Reference: docs/ai_guidelines.md - Section 3.1: Tailwind CSS Mandate
• Reference: docs/implementation.md - Section 3.1: Styling Strategy

Checklist Update: Verify Tailwind setup

Task 4.2: Setup shadcn/ui ⬜

Action Steps:

1. Initialize shadcn/ui:

   bashCopy
   1npx shadcn@latest init

   • Select style, color scheme, etc.
2. Install initial components for demonstration:

   bashCopy
   1npx shadcn@latest add button
   2npx shadcn@latest add card
   3npx shadcn@latest add input

3. Verify components are copied to src/components/ui/

Docs Traceability:

• Reference: docs/ai_guidelines.md - Section 3.2: Open Code Philosophy
• Reference: docs/implementation.md - Section 3.2: Component Implementation
• Requirement: Components must be source code, not NPM packages

Checklist Update: Document shadcn/ui integration

Task 4.3: Create components.json ⬜

Action Steps:

1. Verify components.json was created during shadcn/ui init
2. Ensure it references correct paths:

   jsonCopy
   1{
   2  "$schema": "https://ui.shadcn.com/schema.json",
   3  "style": "default",
   4  "rsc": true,
   5  "tsx": true,
   6  "tailwind": {
   7    "config": "tailwind.config.ts",
   8    "css": "src/app/globals.css",
   9    "baseColor": "slate",
   10    "cssVariables": true
   11  },
   12  "aliases": {
   13    "components": "@/components",
   14    "utils": "@/lib/utils"
   15  }
   16}

Docs Traceability:

• Reference: docs/ai_guidelines.md - Section 3.2: UI Component Strategy

Checklist Update: Verify components.json configuration

Phase 5: Project Structure

Docs Context References:

• docs/ai_guidelines.md (Section 4: Project Structure)
• docs/architecture.md (Section 2: Structural Organization)
• docs/sop.md (Section 3: Development Structure)

Task 5.1: Create Private Folders ⬜

Action Steps:

1. Create private utility folders following underscore convention:

   textCopy
   1src/
   2├── app/
   3├── _components/     # Shared non-routable components
   4├── _lib/            # Utility functions
   5├── _utils/          # Helper utilities
   6├── _hooks/          # Custom React hooks
   7└── _types/          # TypeScript type definitions

Docs Traceability:

• Reference: docs/ai_guidelines.md - Section 4.2: Private Folders
• Requirement: Private folders prefixed with underscore

Checklist Update: Document folder structure

Task 5.2: Create Base App Structure ⬜

Action Steps:

1. Create sample route structure demonstrating best practices:

   textCopy
   1src/app/
   2├── layout.tsx           # Root layout
   3├── page.tsx            # Home page
   4├── globals.css         # Global styles
   5├── (marketing)/        # Route group
   6│   ├── layout.tsx
   7│   └── about/
   8│       └── page.tsx
   9├── dashboard/
   10│   ├── layout.tsx
   11│   ├── page.tsx
   12│   ├── @analytics/     # Parallel route slot
   13│   │   └── page.tsx
   14│   └── @revenue/       # Parallel route slot
   15│       └── page.tsx
   16├── blog/
   17│   ├── [slug]/         # Dynamic route
   18│   │   └── page.tsx
   19│   └── page.tsx
   20├── api/
   21│   └── hello/
   22│       └── route.ts    # Route handler
   23├── loading.tsx         # Root loading UI
   24├── error.tsx          # Root error boundary
   25└── not-found.tsx      # Custom 404 page

Docs Traceability:

• Reference: docs/architecture.md - Section 1: Routing Architecture
• Reference: docs/architecture.md - Section 2: Route Groups & Parallel Routing
• Requirement: Demonstrate all major routing patterns

Checklist Update: Track structure creation

Task 5.3: Create Utility Files ⬜

Action Steps:

1. Create src/_lib/utils.ts with common utilities:

   typescriptCopy
   1import { type ClassValue, clsx } from 'clsx'
   2import { twMerge } from 'tailwind-merge'
   3
   4export function cn(...inputs: ClassValue[]) {
   5  return twMerge(clsx(inputs))
   6}

2. Create src/_types/index.ts for shared types
3. Create sample custom hooks in src/_hooks/

Docs Traceability:

• Reference: docs/ai_guidelines.md - Section 4.2: Private Folders Use Cases

Checklist Update: Document utility file creation

Phase 6: Routing Implementation

Docs Context References:

• docs/requirements.md (Section 3: Routing Capabilities)
• docs/architecture.md (Section 1: Routing Architecture)
• docs/implementation.md (Section 4: Routing Implementation)

Task 6.1: Implement Root Layout ⬜

Action Steps:

1. Update src/app/layout.tsx with proper structure:

   typescriptCopy
   1import type { Metadata } from 'next'
   2import { Inter } from 'next/font/google'
   3import './globals.css'
   4
   5const inter = Inter({ subsets: ['latin'] })
   6
   7export const metadata: Metadata = {
   8  title: 'Next.js Boilerplate',
   9  description: 'Production-ready Next.js boilerplate',
   10}
   11
   12export default function RootLayout({
   13  children,
   14}: {
   15  children: React.ReactNode
   16}) {
   17  return (
   18    <html lang="en">
   19      <body className={inter.className}>{children}</body>
   20    </html>
   21  )
   22}

Docs Traceability:

• Reference: docs/architecture.md - Section 2.B: Nested Layouts
• Requirement: Root layout wraps all pages

Checklist Update: Track root layout implementation

Task 6.2: Implement Static Routes ⬜

Action Steps:

1. Create home page (app/page.tsx)
2. Create about page (app/(marketing)/about/page.tsx)
3. Implement proper Server Components with async data fetching examples

Docs Traceability:

• Reference: docs/requirements.md - Section 3.1: Static Routes
• Reference: docs/ai_guidelines.md - Section 1.2: RSC as Default

Checklist Update: Document static route implementation

Task 6.3: Implement Dynamic Routes ⬜

Action Steps:

1. Create app/blog/[slug]/page.tsx:

   typescriptCopy
   1interface PageProps {
   2  params: { slug: string }
   3}
   4
   5export default async function BlogPost({ params }: PageProps) {
   6  const { slug } = params
   7  // Fetch data based on slug
   8  return <div>Blog Post: {slug}</div>
   9}
   10
   11export async function generateStaticParams() {
   12  // Generate static paths
   13  return [{ slug: 'first-post' }, { slug: 'second-post' }]
   14}

Docs Traceability:

• Reference: docs/requirements.md - Section 3.1: Dynamic Routes
• Reference: docs/architecture.md - Section 1: Dynamic Routing

Checklist Update: Track dynamic route creation

Task 6.4: Implement Parallel Routes ⬜

Action Steps:

1. Create dashboard with parallel slots:
   • app/dashboard/@analytics/page.tsx
   • app/dashboard/@revenue/page.tsx
2. Update app/dashboard/layout.tsx to receive slots as props:

   typescriptCopy
   1export default function DashboardLayout({
   2  children,
   3  analytics,
   4  revenue,
   5}: {
   6  children: React.ReactNode
   7  analytics: React.ReactNode
   8  revenue: React.ReactNode
   9}) {
   10  return (
   11    <div>
   12      <div>{children}</div>
   13      <div className="grid grid-cols-2 gap-4">
   14        {analytics}
   15        {revenue}
   16      </div>
   17    </div>
   18  )
   19}

Docs Traceability:

• Reference: docs/architecture.md - Section 3: Parallel Rendering
• Reference: docs/requirements.md - Section 3.1: Parallel Routing

Checklist Update: Document parallel routing implementation

Task 6.5: Implement Route Groups ⬜

Action Steps:

1. Create app/(marketing)/ folder for marketing pages
2. Add shared layout in app/(marketing)/layout.tsx
3. Verify URL paths don't include "(marketing)"

Docs Traceability:

• Reference: docs/architecture.md - Section 2.C: Route Groups
• Requirement: Parentheses folders excluded from URL path

Checklist Update: Track route group setup

Task 6.6: Implement Navigation Components ⬜

Action Steps:

1. Create src/_components/navigation.tsx:

   typescriptCopy
   1'use client'
   2
   3import Link from 'next/link'
   4import { useRouter } from 'next/navigation'
   5
   6export function Navigation() {
   7  const router = useRouter()
   8
   9  return (
   10    <nav>
   11      <Link href="/">Home</Link>
   12      <Link href="/about">About</Link>
   13      <Link href="/blog">Blog</Link>
   14      <button onClick={() => router.push('/dashboard')}>
   15        Dashboard
   16      </button>
   17    </nav>
   18  )
   19}

Docs Traceability:

• Reference: docs/implementation.md - Section 4.1: Navigation Between Routes
• Reference: docs/sop.md - Section 6: Navigation Standards
• Requirement: Use Link for internal, useRouter for programmatic

Checklist Update: Document navigation implementation

Phase 7: Data Fetching & State Management

Docs Context References:

• docs/architecture.md (Section 4: Data Fetching Paradigm)
• docs/requirements.md (Section 3.3: Efficient Data Fetching)
• docs/implementation.md (Section 6: Performance Optimization)

Task 7.1: Implement Server-Side Data Fetching ⬜

Action Steps:

1. Create example in app/blog/page.tsx:

   typescriptCopy
   1async function getPosts() {
   2  const res = await fetch('https://api.example.com/posts', {
   3    cache: 'force-cache', // SSG
   4    // cache: 'no-store', // SSR
   5    // next: { revalidate: 60 }, // ISR
   6  })
   7  return res.json()
   8}
   9
   10export default async function BlogPage() {
   11  const posts = await getPosts()
   12  return <div>{/* Render posts */}</div>
   13}

Docs Traceability:

• Reference: docs/architecture.md - Section 4: Server Component Direct Fetching
• Reference: docs/implementation.md - Section 6.2: Strategic Rendering
• Requirement: Server-side data fetching in RSC

Checklist Update: Track data fetching examples

Task 7.2: Implement Route Handlers (API Routes) ⬜

Action Steps:

1. Create app/api/hello/route.ts:

   typescriptCopy
   1import { NextResponse } from 'next/server'
   2
   3export async function GET() {
   4  return NextResponse.json({ message: 'Hello from API' })
   5}
   6
   7export async function POST(request: Request) {
   8  const body = await request.json()
   9  return NextResponse.json({ received: body })
   10}

Docs Traceability:

• Reference: docs/architecture.md - Section 5: Route Handlers
• Requirement: Support GET, POST, PUT, DELETE methods

Checklist Update: Document API route creation

Task 7.3: Implement Loading & Error States ⬜

Action Steps:

1. Create app/blog/loading.tsx:

   typescriptCopy
   1export default function Loading() {
   2  return <div>Loading posts...</div>
   3}

2. Create app/blog/error.tsx:

   typescriptCopy
   1'use client'
   2
   3export default function Error({
   4  error,
   5  reset,
   6}: {
   7  error: Error & { digest?: string }
   8  reset: () => void
   9}) {
   10  return (
   11    <div>
   12      <h2>Something went wrong!</h2>
   13      <button onClick={() => reset()}>Try again</button>
   14    </div>
   15  )
   16}

3. Create app/not-found.tsx:

   typescriptCopy
   1export default function NotFound() {
   2  return <div>404 - Page Not Found</div>
   3}

Docs Traceability:

• Reference: docs/implementation.md - Section 5: State Management
• Reference: docs/requirements.md - Section 3.2: Error Handling
• Requirement: loading.js wraps in Suspense, error.js must be Client Component

Checklist Update: Track state management files

Phase 8: Testing Infrastructure

Docs Context References:

• docs/testing.md (All sections)
• docs/requirements.md (Section 3.2: Error Handling)

Task 8.1: Install Testing Dependencies ⬜

Action Steps:

1. Install Jest and React Testing Library:

   bashCopy
   1npm install --save-dev jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event @types/jest

2. Install additional testing utilities:

   bashCopy
   1npm install --save-dev @testing-library/react-hooks

Docs Traceability:

• Reference: docs/testing.md - Section 2.1: Development Dependencies

Checklist Update: Track testing package installation

Task 8.2: Configure Jest ⬜

Action Steps:

1. Create jest.config.js:

   javascriptCopy
   1const nextJest = require('next/jest')
   2
   3const createJestConfig = nextJest({
   4  dir: './',
   5})
   6
   7const customJestConfig = {
   8  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
   9  testEnvironment: 'jest-environment-jsdom',
   10  moduleNameMapper: {
   11    '^@/(.*)$': '<rootDir>/src/$1',
   12  },
   13  collectCoverageFrom: [
   14    'src/**/*.{js,jsx,ts,tsx}',
   15    '!src/**/*.d.ts',
   16    '!src/**/*.stories.{js,jsx,ts,tsx}',
   17    '!src/**/__tests__/**',
   18  ],
   19  coverageThreshold: {
   20    global: {
   21      branches: 80,
   22      functions: 80,
   23      lines: 80,
   24      statements: 80,
   25    },
   26  },
   27}
   28
   29module.exports = createJestConfig(customJestConfig)

2. Create jest.setup.js:

   javascriptCopy
   1import '@testing-library/jest-dom'

Docs Traceability:

• Reference: docs/testing.md - Section 2.2: Code Coverage Requirement
• Requirement: >80% code coverage

Checklist Update: Document Jest configuration

Task 8.3: Create Sample Tests ⬜

Action Steps:

1. Create src/_components/__tests__/navigation.test.tsx:

   typescriptCopy
   1import { render, screen } from '@testing-library/react'
   2import { Navigation } from '../navigation'
   3
   4jest.mock('next/navigation', () => ({
   5  useRouter: () => ({
   6    push: jest.fn(),
   7  }),
   8}))
   9
   10describe('Navigation', () => {
   11  it('renders navigation links', () => {
   12    render(<Navigation />)
   13    expect(screen.getByText('Home')).toBeInTheDocument()
   14  })
   15})

2. Create unit tests for utilities
3. Create integration tests for API routes

Docs Traceability:

• Reference: docs/testing.md - Section 3: Testing Strategy
• Requirement: Unit, Integration, and E2E tests

Checklist Update: Track test file creation

Task 8.4: Create Test for Routing Patterns ⬜

Action Steps:

1. Create tests for static routes
2. Create tests for dynamic routes with params
3. Create tests for parallel routes rendering
4. Create tests for error.js and not-found.js

Docs Traceability:

• Reference: docs/testing.md - Section 4: Critical Next.js Feature Testing
• Requirement: Test all routing conventions

Checklist Update: Document routing tests

Phase 9: Security Hardening

Docs Context References:

• docs/security.md (All sections)
• docs/architecture.md (Section 6: Security Considerations)

Task 9.1: Setup Environment Variables ⬜

Action Steps:

1. Create .env.example:

   textCopy
   1# Database
   2DATABASE_URL=postgresql://user:password@localhost:5432/db
   3
   4# API Keys
   5NEXT_PUBLIC_API_URL=https://api.example.com
   6API_SECRET_KEY=your-secret-key
   7
   8# Auth
   9NEXTAUTH_URL=http://localhost:3000
   10NEXTAUTH_SECRET=your-nextauth-secret

2. Create .env.local (gitignored)
3. Document environment variable usage

Docs Traceability:

• Reference: docs/security.md - Section 2: Environment Variable Management
• Requirement: Segmented by stage, never exposed to client

Checklist Update: Track env configuration

Task 9.2: Create Middleware for Auth ⬜

Action Steps:

1. Create src/middleware.ts:

   typescriptCopy
   1import { NextResponse } from 'next/server'
   2import type { NextRequest } from 'next/server'
   3
   4export function middleware(request: NextRequest) {
   5  // Example: Check for auth token
   6  const token = request.cookies.get('session')
   7  
   8  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
   9    return NextResponse.redirect(new URL('/login', request.url))
   10  }
   11
   12  return NextResponse.next()
   13}

Docs Traceability:

• Reference: docs/security.md - Section 4: Authentication and Authorization
• Requirement: Middleware for protected routes

Checklist Update: Document middleware implementation

Task 9.3: Implement Server-Side Data Security ⬜

Action Steps:

1. Create example server component with secure data fetching:

   typescriptCopy
   1// app/dashboard/page.tsx
   2async function getSecureData() {
   3  // Direct database call - safe in RSC
   4  const data = await fetch('http://localhost:3000/api/secure', {
   5    headers: {
   6      'Authorization': `Bearer ${process.env.API_SECRET_KEY}`
   7    }
   8  })
   9  return data.json()
   10}
   11
   12export default async function Dashboard() {
   13  const data = await getSecureData()
   14  return <div>{/* Render secure data */}</div>
   15}

2. Document RSC security benefits in README

Docs Traceability:

• Reference: docs/security.md - Section 3: Leveraging RSC for Data Security
• Requirement: Server-side execution prevents credential leakage

Checklist Update: Track secure data fetching implementation

Task 9.4: Add Security Headers ⬜

Action Steps:

1. Update next.config.ts with security headers:

   typescriptCopy
   1const nextConfig: NextConfig = {
   2  typedRoutes: true,
   3  reactStrictMode: true,
   4  async headers() {
   5    return [
   6      {
   7        source: '/(.*)',
   8        headers: [
   9          {
   10            key: 'X-Frame-Options',
   11            value: 'DENY',
   12          },
   13          {
   14            key: 'X-Content-Type-Options',
   15            value: 'nosniff',
   16          },
   17          {
   18            key: 'X-XSS-Protection',
   19            value: '1; mode=block',
   20          },
   21          {
   22            key: 'Referrer-Policy',
   23            value: 'strict-origin-when-cross-origin',
   24          },
   25        ],
   26      },
   27    ]
   28  },
   29}