Clean Arch Nextjs Starter

The Clean Arch Nextjs Starter is a Next.js and TypeScript boilerplate that provides a clean architecture foundation with TDD-oriented tooling, created by Yazalde Filimone and released under the MIT license.

What is the Clean Arch Nextjs Starter?

The Clean Arch Nextjs Starter is a starting template for building Next.js 12 and React 18 applications with TypeScript. It scaffolds a project with a layered src directory, path mapping using the ~/ prefix, and a preconfigured code-quality toolkit including ESLint, Prettier, Husky, Commitlint, lint-staged, and EditorConfig. The template runs on Node.js version 12.22.0 or higher and is installed by using create-next-app with the repository URL.

Key Features

• Next.js 12 and React 18 — The template is built on Next.js 12 with React 18 and TypeScript, providing a modern React framework setup.
• Clean architecture directory layout — The src folder separates application code into layers such as presentation and shared, with path mapping configured so you can import with ~/ instead of long relative paths.
• Styled Components — CSS-in-JS is preconfigured, including a global styles file at src/shared/styles/globals.ts and an updated src/pages/_document.tsx; both can be removed if you don't use styled-components.
• ESLint and Prettier — ESLint is configured to find and fix code problems, Prettier formats code for consistent style, and lint-staged runs both against staged Git files.
• Husky and Commitlint — Husky runs scripts before commits and Commitlint enforces conventional commit message format.
• EditorConfig — A configuration file maintains consistent coding styles across editors and IDEs.
• Either Error Handler — An error-handling utility based on the Either pattern (holding either a left or a right value but never both) is included for functional error handling.

Who is the Clean Arch Nextjs Starter for?

• Next.js developers who want a preconfigured setup with linting, formatting, and Git hooks so they can focus on writing features instead of configuring tooling.
• Teams practicing clean architecture who need a folder structure that separates concerns and enforces a layered design from the start.
• Developers who use styled-components and want a CSS-in-JS setup already integrated with Next.js.
• Open-source maintainers who want an MIT-licensed starter they can fork and adapt for their own boilerplate projects.

What can you do with the Clean Arch Nextjs Starter?

• Scaffold a new project: Run yarn create next-app -e https://github.com/yazaldefilimonepinto/clean-arch-nextjs-starter (or the npm equivalent) to instantly create a Next.js app with all included tooling.
• Enforce code quality: Use the built-in lint script to run ESLint across the src directory, and rely on Husky/Commitlint to check commits before they land.
• Develop locally: Use npm dev or yarn dev to start the development server at http://localhost:3000 with hot reloading.
• Structure by clean architecture: Use the src folder and the ~/ path mapping to maintain a clean separation of concerns.

How does it work?

The template follows the standard Next.js workflow. After scaffolding, you run yarn dev or npm dev to start development at http://localhost:3000. Scripts are provided for building (yarn build), running in production (yarn start), and linting (yarn lint). The project uses a .husky directory for Git hooks and a public folder for static assets such as robots.txt and images.

Pricing

The template is free to use. It is released under the MIT license, as shown in the License section of the repository.

FAQ

What Node.js version do I need?

You need Node.js version 12.22.0 or higher. The Requirements section of the README specifies this minimum version.

How do I start the development server?

Run npm dev or yarn dev from the project root, then open http://localhost:3000 in your browser to see the application.

Does this template include a test runner?

The template is labeled "Clean-Arch TDD NextJs" in its badge, and the repository name includes "tdd". However, the README does not document a specific testing library or setup, so you may need to inspect the repository to see what testing tools are present.

Can I remove the styled-components setup?

Yes. The README notes that if you don't use styled-components, you can remove the settings in src/pages/_document.tsx and delete the global styles in src/shared/styles/globals.ts.

Is the template free?

Yes, it is offered under an MIT license, which allows free use, modification, and distribution with attribution.