Nextjs clean architecture boilerplate

Table of content

• Nextjs clean architecture boilerplate
  • Table of content
  • Overview
  • Motivation
  • Technologies
  • Architecture
    • Folder structure
  • Requirements
  • Getting Started
    • Local
    • Docker
  • naming convetions:

Overview

This project is a starting point for your medium to large scale projects with Nextjs, to make sure having a structured, maintainable and scalable foundation for your Next.js project based on best practices in clean architecture, DDD approach for business logics, MVVM for the frontend part, storybook and vitest for testing and, localization and also functional programming with error handling for business logics.

Motivation

Next.js and many other modern SSR frameworks provide powerful tools and a fresh approach to frontend development. However, since these tools are relatively new, the focus has largely been on features rather than software engineering best practices.

As a result, many teams use Next.js for its capabilities but neglect maintainability, architecture, and scalability—especially in medium to large-scale applications. Over time, this leads to unmanageable codebases, difficulty in adding new features, and even business failures.

After extensive trial and error in my career, I decided to create a structured, robust, and maintainable boilerplate for Next.js, incorporating best practices that align with its features. This template is based on real-world experience and is designed to serve as a solid foundation for SSR projects.

I’ve personally used this boilerplate in multiple enterprise-level web applications, and it has been thoroughly tested. You can confidently use it in production.

Note: I welcome your feedback, issues, and suggestions to improve this project together. For contribution guidelines, please check CONTRIBUTE.md.

Technologies

• Language: Typescript
• Framework: Next.js
• Testing tools: Vitest
• UI documenting: Storybook
• Lintins: ESlint
• Component library: Shadcn
• Css utility: Tailwindcss
• i18n: I18Next
• dependency injection: tsyringe
• functional programming: fp-ts
• MVVM architecture: ReactVVM
• Schema validator: Zod
• Mocking tool: Moq.ts
• Faking tool: Fakerjs
• Containerization: Docker
• CI: Gihub actions

Architecture

To make sure about maintainability and scalibility of the application we're following clean architecture, MVVM architectural patter in frontend part with using ReactVVM and DDD approach in business logic related layers.

• To know more about details, diagrams and tutorials check documents in catalog folder.

Folder structure

└── src/
    ├── app/
    │   └── users/
    │       ├── controllers
    │       ├── view/
    │       │   ├── server
    │       │   └── client/
    │       │       └── some-component/
    │       │           ├── some-component.view.tsx
    │       │           ├── stories
    │       │           └── style/
    │       │               └── i-vm
    │       ├── page
    │       └── vm
    ├── feature/
    │   ├── core/
    │   │   └── users/
    │   │       ├── data/
    │   │       │   ├── repository
    │   │       │   └── mapper
    │   │       └── domain/
    │   │           ├── failure
    │   │           ├── i-repository
    │   │           ├── entity
    │   │           └── usecase
    │   ├── support
    │   └── generic
    ├── bootstrap/
    │   ├── boundary
    │   ├── config/
    │   │   ├── server
    │   │   └── client
    │   ├── di
    │   ├── endpoint
    │   ├── helper
    │   └── i18n
    └── test/
        ├── common
        ├── unit
        └── e2e

Requirements

To work with this boilerplate, there are some base requirements based on some best practices in software development which we used in this boilerplate. We've provided all necessary documentation for each one to learn about them step by step:

• Clean architecture
• Business Logic handling with DDD
• MVVM
• Failure handling
• i18n
• Endpoints managements
• Dependency injection

Getting Started

Local

1. DB: First, run your postgres db:
2. ENVs: Update .env.example file and specify all db related environments and remove .example part from the file name
3. Install deps

yarn install

4. Seed db:

yarn seed

5. run development

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

6. Open http://localhost:3000 with your browser to see the result.

Docker

1. ENVs: Update .env.example file and specify all db related environments and remove .example part from the file name

2. Just run the docker-compose.yml file by this command:

docker-compose up

2. Seed db:

yarn seed

4. Open http://localhost:3000 with your browser to see the result.

naming convetions:

1. all folders follow the kebab-case convention for naming.
2. all files follow the kebab-case.[layer name] convention for naming.
3. all variables and functions follow the camelCase convention for naming.