How takunagai/nextjs-boilerplate works
Main Components
• Next.js Application: Represent the core app under the “src/app” directory. This includes:
• Page routing (App Router)
• Global styles (globals.css)
• Static routing and dynamic generation (pages such as about, contact, privacy, etc.)
• Utility and Business Logic: “src/lib” houses utility functions, constants, and validation logic. Clearly mark this as the service layer or “helper” module.
• Testing Environment: Represent the “tests” directory with separate segments for E2E tests (Playwright) and unit tests (Vitest). Indicate that there is a specific setup file (setupTests.ts) to boot the testing environment.
• Public and Static Assets: The “public” directory handles static files (images, site manifest, etc.), which is used by the front-end during runtime.
• CI/CD & Dev Tools: Indicate continuous integration components from the “.github/workflows” folder (e.g., for Playwright tests), as well as configuration files for Biome (linters), Tailwind CSS, PostCSS, and TypeScript. Also note that there is a .windsurfrules file that supports AI-driven development tools.
• Documentation & Reference: The “reference” folder contains documentation and sample code files. Treat these as resources for internal developers to understand design patterns, performance optimization tips, and API/interface designs.
Relationships and Interactions
• Testing interactions: show that both unit and E2E testing frameworks directly interact with the application’s components and pages.
• Integration flows from the build/deployment pipeline (such as GitHub Actions and Vercel deployments) to the repository, highlighting how CI/CD integrates with code quality (Biome settings, linters) and testing.
Architectural Patterns and Design Principles
• Component-Based Architecture: Emphasize that the project is modular—with clear separation between UI, business logic, and styling.
• Server-Side Rendering & Static Generation: Illustrate that Next.js manages routing and rendering (both static and dynamic) through the App Router.
• Responsive & Thematic Design: Note the integration of Tailwind CSS and next-themes for responsive design and theme switching.
• Testing and Quality Assurance: Outline the inclusion of unit tests and end-to-end tests, implying a robust quality assurance process.
• Developer Tooling: Show how developer experience is enhanced via TypeScript, linting/formatting (Biome), and GitHub Actions for automated testing.
Relevant Technologies and Libraries
• Next.js, React, and TypeScript as the core.
• UI/Styling: Tailwind CSS, shadcn/ui, next-themes, and framer-motion.
• State Management and Utilities: Immer, date-fns, class-variance-authority, and clsx.
• Form Handling: react-hook-form and Zod.
• Testing: Vitest, Playwright, and Testing Library.
• CI/CD: GitHub workflows and Vercel for deployment.
• Developer Support: .windsurfrules for AI-code-generation guidance and Biome for code quality.
• Clearly demarcate the separation between front-end (components, pages) and the backend/server-rendering capabilities managed by Next.js.
• API routes if applicable (even though most API folders might be inside /src/lib or similar), and indicate that server-side logic (if any) is part of the Next.js framework.
• Static file serving provided by the “public” directory.
• Incorporate testing pipelines and deployment workflows as external processes that interact with the project repository.
• Segment is detailed by separating sub-components (for instance, within UI, include Layout, Theme, and SEO as distinct nodes).
• Review the “reference” documents and sample code in the project to verify that all critical interactions (like data-fetching strategies or form handling) are represented.