Next.js 15: TypeScript Forms with Prisma and Clean Architecture 🚀

11/13/2024

Available in :

How to structure a modern web application? How to ensure it remains maintainable over time? In this guide, we'll create a Next.js application using hexagonal architecture and robust form validation. To make learning more fun, we'll create a Jedi Academy registration system!

The source code is available on GitHub.

Introduction to Hexagonal Architecture
Installation and Structure
The Domain
The Infrastructure
The User Interface
Going Further

1. Introduction to Hexagonal Architecture

1.1 What is Hexagonal Architecture?

Hexagonal Architecture, also known as "Ports and Adapters", is an architectural pattern that allows creating applications where business components are:

Decoupled from technical details
Testable in isolation
Independent from the framework used

The architecture is divided into three main layers:

The Domain: Contains pure business logic
The Ports: Define interfaces to communicate with the domain
The Adapters: Implement ports to interact with the outside world

1.2 Why Use Hexagonal Architecture?

Advantages

Clear separation of concerns
Protected and centralized business logic
Facilitated testing
Flexibility to change technologies
Simplified maintenance

Ideal Use Cases

Applications with complex business rules
Projects intended to evolve over time
Systems requiring high testability
Applications needing to support multiple interfaces

[Content continues...]

2. Installation and Structure

2.1 Complete Installation

bash

When creating the project, answer the following questions:

Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like to use `src/` directory? Yes
Would you like to use App Router? (recommended) Yes
Would you like to customize the default import alias (@/*)? Yes

Using Next.js version 15.0.0+ with Turbopack

Once the project is created, install the dependencies:

bash

When initializing shadcn/ui, answer the following questions:

Would you like to use TypeScript (recommended)? Yes
Which style would you like to use? › Default
Which color would you like to use as base color? › Slate
Where is your global CSS file? › src/app/globals.css
Would you like to use CSS variables for colors? › Yes
Where is your tailwind.config.js located? › tailwind.config.js
Configure the import alias for components: › @/components
Configure the import alias for utils: › @/lib/utils
Are you using React Server Components? › Yes

# Install necessary components
npx shadcn@latest add form input select textarea button card toast table

bash

2.2 Project Structure

src/
├── app/
│   ├── actions/
│   │   └── register-padawan.ts
│   ├── components/
│   │   ├── ui/          # shadcn/ui components
│   │   ├── jedi-form.tsx
│   │   └── padawan-list.tsx
│   ├── lib/
│   │   └── utils.ts     # shadcn/ui utilities
│   └── page.tsx
├── core/
│   ├── domain/
│   │   ├── models/
│   │   │   └── padawan.ts
│   │   ├── ports/
│   │   │   └── padawan-repository.ts
│   │   ├── services/
│   │   │   └── padawan-eligibility.ts
│   │   ├── validation/
│   │   │   └── padawan-schema.ts
│   │   └── events/
│   │       └── padawan-registered.ts
│   └── usecases/
│       └── register-padawan.ts
└── infrastructure/
    └── db/
        ├── prisma/
        │   ├── migrations/
        │   └── schema.prisma
        ├── prisma.ts
        └── repositories/
            └── prisma-padawan-repository.ts

This structure follows a clear hexagonal architecture with:

app/ - Next.js user interface layer

actions/ - Server Actions for form handling
components/ - React components with UI/business separation
lib/ - Shared utilities

core/ - Pure business logic

domain/ - Models, ports, and business services
usecases/ - Application use cases

infrastructure/ - Technical implementations

db/ - Prisma configuration and repository implementations

3. The Domain: Core of the Application

3.1 Understanding the Domain

The domain is the heart of our application. This is where we translate business rules into code, independently of any technical consideration. In our case, the domain represents all the rules governing registration at the Jedi Academy.

Key Domain Principles

Technological Independence

No framework dependencies
No persistence-related code
No UI logic

Centralized Business Rules

All business logic is in the domain
Rules are explicit and documented
Business validations are separated from technical validations

Rich Modeling

Use of precise types and interfaces
Value Objects for important business concepts
Entities with clear identity

3.2 Domain Components

3.2.1 Models

Models represent fundamental business concepts.

typescript

3.2.2 Domain Events

Events represent important facts that have occurred in the domain.

typescript

3.2.3 Ports (Interfaces)

Ports define how the domain interacts with the outside world.

typescript

3.2.4 Domain Services

Domain services encapsulate business logic that doesn't naturally fit into an entity.

typescript

3.2.5 Use Cases

Use cases orchestrate interactions between different domain elements to achieve a business functionality.

typescript

4. The Infrastructure

The infrastructure implements the ports defined in the domain to interact with the outside world.

4.1 Prisma Configuration

prisma

4.2 Adapter Implementation

typescript

5. The User Interface

5.1 Validation with Zod

Input data validation uses Zod to ensure consistency with our domain.

typescript

Now we can generate the db.

bash

For further exploration, Prisma provides a client to visualize the db.

bash

5.2 Server Action for Registration

typescript

5.3 Form Component

typescript

5.4 Padawan List

typescript

These components use shadcn/ui to create a modern and accessible user interface, with:

JediRegistrationForm:

Complete validation with react-hook-form and Zod
Error handling with contextual messages
User feedback with toasts
Form reset after successful submission

PadawanList:

Tabular data display
Empty state handling
Date formatting in English
Skill icons
Consistent styling with the form

Everything integrates perfectly into our hexagonal architecture while staying at the presentation layer, without business logic.

6. Going Further

6.1 Technical Improvements

Cache and Performance

typescript

Monitoring and Logging

typescript

6.2 Functional Evolutions

Approval Workflow
Rating System
Promotion Management
Padawan Communication

Conclusion

Hexagonal architecture has allowed us to create an application that is:

Maintainable

Clear separation of concerns
Isolated and protected business code

Scalable

Easy to add new features
Ability to change infrastructure
Support for new input/output channels

To go further, you could:

Add authentication
Implement a caching system
Set up monitoring
Set up automated tests
Add webhooks

Remember: good architecture is like the Force - it must be in balance! 🌟

[End of translation]

Next.js 15: TypeScript Forms with Prisma and Clean Architecture 🚀

Table of Contents

1. Introduction to Hexagonal Architecture

1.1 What is Hexagonal Architecture?

1.2 Why Use Hexagonal Architecture?

Advantages

Ideal Use Cases

2. Installation and Structure

2.1 Complete Installation

2.2 Project Structure

3. The Domain: Core of the Application

3.1 Understanding the Domain

Key Domain Principles

3.2 Domain Components

3.2.1 Models

3.2.2 Domain Events

3.2.3 Ports (Interfaces)

3.2.4 Domain Services

3.2.5 Use Cases

4. The Infrastructure

4.1 Prisma Configuration

4.2 Adapter Implementation

5. The User Interface

5.1 Validation with Zod

5.2 Server Action for Registration

5.3 Form Component

5.4 Padawan List

6. Going Further

6.1 Technical Improvements

6.2 Functional Evolutions

Conclusion

Table of Contents

1. Introduction to Hexagonal Architecture

1.1 What is Hexagonal Architecture?

1.2 Why Use Hexagonal Architecture?

Advantages

Ideal Use Cases

2. Installation and Structure

2.1 Complete Installation

2.2 Project Structure

3. The Domain: Core of the Application

3.1 Understanding the Domain

Key Domain Principles

3.2 Domain Components

3.2.1 Models

3.2.2 Domain Events

3.2.3 Ports (Interfaces)

3.2.4 Domain Services

3.2.5 Use Cases

4. The Infrastructure

4.1 Prisma Configuration

4.2 Adapter Implementation

5. The User Interface

5.1 Validation with Zod

5.2 Server Action for Registration

5.3 Form Component

5.4 Padawan List

6. Going Further

6.1 Technical Improvements

6.2 Functional Evolutions

Conclusion