One File to Generate Them All: JHipster JDL in Practice

The Synchronization Tax

Every full-stack team knows the drill: you design a domain model, then manually create JPA entities, repositories, DTOs, MapStruct mappers, Liquibase changelogs, TypeScript interfaces, Angular services, and HTML templates. A single field addition touches six files across two repositories. A relationship change cascades into join tables, bidirectional navigation, and multi-select components. The synchronization tax isn't just tedious—it's where bugs hide.

JHipster's JDL (JHipster Domain Language) attacks this by making the domain model the single source of truth. One .jdl file declares entities, fields, validation, relationships, and architectural options (DTO pattern, service layer, pagination). Running jhipster import-jdl generates the entire stack—Spring Boot backend and React/Vue/Angular frontend—in one pass. This blog walks through a concrete example, shows where the approach shines, and highlights the discipline it demands.

What JDL Actually Declares

A JDL file is a concise DSL. Entities look like this:

entity User {
  login String required unique
  email String required unique
  firstName String
  lastName String
  activated Boolean
}

entity Authority {
  name String required unique
}

Relationships use explicit cardinality and an ownerSide to control foreign keys:

relationship ManyToMany {
  User{authority} to Authority{user}
}

Options apply globally or per-entity:

dto * with mapstruct
service * with serviceClass
paginate * with pagination

These three lines give you MapStruct mappers for every DTO, a service layer with interface + implementation, and Spring Data Pageable endpoints with frontend pagination components—no manual wiring.

Worked Example: User–Authority ManyToMany

Create a minimal JHipster project (monolith, Angular, Maven):

jhipster --blueprints=none --skip-client=false --skip-server=false

Save the following as model.jdl:

entity User {
  login String required unique minlength(2) maxlength(50)
  email String required unique maxlength(254)
  firstName String maxlength(50)
  lastName String maxlength(50)
  activated Boolean
}

entity Authority {
  name String required unique maxlength(50)
}

relationship ManyToMany {
  User{authority} to Authority{user}
}

dto * with mapstruct
service * with serviceClass
paginate * with pagination

Run the import:

jhipster import-jdl model.jdl

What gets generated (backend):

• User.java and Authority.java with JPA annotations, @ManyToMany, @JoinTable(name = "jhi_user_authority"), and bidirectional navigation.
• UserRepository.java extending JpaRepository with pagination methods.
• UserService.java (interface) and UserServiceImpl.java with transactional CRUD.
• UserMapper.java (MapStruct interface) converting between User and UserDTO.
• Liquibase changelog creating jhi_user, jhi_authority, and the join table jhi_user_authority with foreign keys.

What gets generated (frontend, Angular):

• user.model.ts and authority.model.ts TypeScript interfaces mirroring the JPA entities.
• user.service.ts with query(req?: any): Observable accepting pagination params.
• user-management.component.html with a multi-select for authorities bound to user.authorities.
• Routing, resolvers, and pagination directives wired automatically.

Add a field to User in the JDL (e.g., phoneNumber String pattern("^\+?[0-9\s-]{10,}$")), re-run import-jdl, and the field appears in the entity, DTO, mapper, changelog, TypeScript model, and form—while your custom code inside // jhipster-needle- protected regions stays untouched.

The Trade-off: Regeneration Discipline

JDL's power is also its risk. Re-running import-jdl after edits produces large diffs. The generator preserves code only inside marked protected regions (// jhipster-needle-entity-add-field, // jhipster-needle-service-add-method, etc.). If you move or delete those markers, your manual additions vanish.

Three practical guards:

1. Commit before every import. A clean baseline lets you diff generated changes vs. your edits.
2. Review Liquibase changelogs carefully. Column type changes (e.g., String → Long) generate drop/create columns—data loss in production. Write manual migration scripts for destructive changes.
3. Keep custom MapStruct logic outside generated mappers. Nested DTO mapping, conditional conversions, or custom value transformations belong in hand-written mapper classes that delegate to generated ones, not inside the generated interface.

Also note: JDL doesn't express complex business logic, custom queries, or security rules. Those live in your service/repository implementations. Switching frontend frameworks (Angular → React) later means regenerating the entire client from JDL—effectively a rewrite.

Closing: Adopt Incrementally

Start a new JHipster project, write a JDL for one bounded context (e.g., user management), run import-jdl, and inspect the output. Verify the join table, MapStruct mapper, and Angular multi-select exist. Then add a field, re-run, and confirm protected regions hold. Once the workflow feels solid, expand the JDL to cover more domains. The JDL Studio at start.jhipster.tech/jdl-studio lets you design and visualize (Mermaid ERD) before generating—useful for team reviews. JDL won't eliminate all boilerplate, but it makes the domain model the contract that keeps backend and frontend honest.