The Next.js Project Architecture Template is a production-focused boilerplate that demonstrates a Model-View-Presenter (MVP) UI flow architecture for Next.js applications, created by Emmanuel Onah. It scaffolds a Next.js project with pre-configured HTTP services, a design system, testing infrastructure, and CI/CD tooling so you can start building without wiring up the usual boilerplate.
What is the Next.js Project Architecture Template?
This is a GitHub repository that serves as a starter or base for Next.js projects. It takes a placeholder project name — you search for "You-Project-Name-Here" and replace it — and provides a structured codebase with folders like src/services/http-services, src/design-system, src/globalstore, and src/mocks. It runs on Next.js and uses styled-components with Radix UI for styling, Jest and React Testing Library for tests, and includes GitHub Actions and Husky for CI.
Key Features
- MVP architecture — Separates concerns into Model (API and business logic), View (UI in the app folder), and Presenter (hooks, utils) with no direct Model–View interaction.
- Axios HTTP services — A pre-built services layer built on axios resides in src/services/http-services.
- Design system with styled-components and Radix UI — Integrated design tokens (colors, typography, breakpoints) under src/styles, plus Storybook to visualize components.
- Global store — A custom global store implementation in src/globalstore removes the need for Redux or MobX.
- PWA integration — Configured in next.config.js so the app can be a progressive web app.
- Testing setup — Jest, React Testing Library, and the msw mock server; encourages trophy testing and enforces a minimum of 80% coverage via
yarn run test:coverage. - CI/CD pre-configuration — GitHub Actions runs unit tests on master and PR branches; Husky git hooks run linters and tests locally.
Who is it for?
Next.js developers who want a production-ready project structure without hand-rolling tooling. It also suits teams that prefer a layered MVP pattern for clear separation of data, logic, and UI. Additionally, developers who value a strong testing setup with realistic integration tests via MSW.
What can you do with this template?
- Indie developers: clone the repo, replace the placeholder name and host URLs, and get a working Next.js app with lint, test, build, and storybook scripts ready.
- Tech leads: adopt the MVP architecture to enforce separation of concerns across teams, using the presenter layer for stateful logic.
- Quality-focused teams: leverage the trophy testing pattern and msw mock server to write integration tests that implicitly cover units, with a coverage floor of 80%.
How does it work?
The README describes a straightforward workflow: clone or fork the repository, search for "You-Project-Name-Here" and substitute your project name, then install dependencies with yarn and start the development server with yarn run dev. It also documents the MVP flow: Model communicates with Presenter, Presenter requests input from View, View returns it, and responses flow back through Presenter to View.
Pros and cons
- Pros: Ready-to-use tooling for testing, linting, and storybook; opinionated architecture that can keep codebases consistent; includes a global store and PWA support out of the box.
- Cons: The placeholder project name and host URLs must be manually replaced; e2e tests are not yet included, only unit and integration tests.
FAQ
Is a global state manager like Redux included?
No. The template ships with a custom global store implementation in src/globalstore, so you don't need to add Redux, MobX, or another external state manager.
What Node.js version do I need?
The README recommends using the latest Node.js version. If you use nvm, run nvm use to select it.
How do I run the unit tests?
Use yarn run test to execute tests, or yarn run test:coverage to run tests with coverage reporting (the project enforces at least 80% coverage).
What testing pattern does it follow?
It follows the trophy testing pattern, focusing on integration tests that implicitly test units. It uses Jest, React Testing Library, and an MSW mock server for realistic test scenarios.
