Next Hexagonal Architecture

Next Hexagonal Architecture is a free, open-source Next.js 15.4.1 boilerplate that enforces hexagonal architecture in a production-ready project setup. It is a template for building scalable applications with a clean separation of business logic, framework code, and UI.

What is Next Hexagonal Architecture?

Next Hexagonal Architecture is a Next.js starter template using the App Router and server components. It organizes source code into modules with dedicated domain, application, and infrastructure layers, plus a presentation layer in src/sections. The template runs on Bun as package manager and runtime, and is released under the MIT license.

Key Features

• Hexagonal architecture — Source is split into src/modules with separate domain/, application/, and infrastructure/ folders per module, plus src/sections for the presentation layer.
• Next.js 15.4.1 — Uses the latest App Router with server components and API routes under src/app.
• TailwindCSS v4 — Utility-first styling configured in tailwind.config.ts along with src/styles/globals.css.
• shadcn/ui — Pre-built component library including button, card, input, and label components in src/components/ui.
• TypeScript and Zod — Type-safe development with runtime validation for forms and schemas.
• Bun toolchain — Package manager and runtime for install, dev, build, and test commands; Biome.js handles linting and formatting, replacing ESLint and Prettier.
• Testing stack — Vitest with @testing-library/react and Happy-DOM for unit tests, and Cypress for end-to-end tests (commands bun test, bun run cy:run, bun run cy:open).
• Command shortcuts — package.json scripts for dev, build, start, lint, format, check, and check:fix.

Who is it for?

• Backend-minded Next.js developers who want to separate business logic from framework code using hexagonal architecture.
• Engineering teams that need a consistent, layered structure for large Next.js applications and enforce boundaries with domain/application/infrastructure modules.
• Developers adopting modern tooling who want Bun, Tailwind v4, Biome, and a complete test setup out of the box.

What can you do with Next Hexagonal Architecture?

• Start a new production-ready project — clone the repository, run bun install and bun dev, then build features inside the modular structure.
• Write and run tests — use bun test for unit tests and bun run cy:run for Cypress E2E tests, with configuration files already present.
• Keep code quality — run bun run check to lint and format with Biome, and bun run check:fix to auto-fix issues.

How does Next Hexagonal Architecture work?

The template organizes code into modules under src/modules, each with application (use cases), domain (entities and interfaces), and infrastructure (external adapters). The presentation layer lives in src/sections, where feature components are grouped. To use it, clone the repo, run bun install, then start the dev server with bun dev at localhost:3000.

Pricing

The template is free and open source, released under the MIT License.

FAQ

Is Next Hexagonal Architecture free?

Yes, it is open source under the MIT License, so you can use, modify, and distribute it without licensing fees.

What commands do I use with this template?

Use bun install to install dependencies, bun dev to start the dev server, bun build for production builds, bun test for unit tests, and bun run cy:run for end-to-end tests.

Which testing tools are included?

Vitest with @testing-library/react and Happy-DOM powers unit tests, while Cypress handles end-to-end testing. Configuration files vitest.config.ts and cypress.config.ts are already in the project.