cleanstack-generator
v0.1.1
Published
A clean, maintainable Angular and Spring Boot project generator.
Maintainers
Readme
CleanStack Generator
CleanStack is a local project generator for Spring Boot + Angular applications. It creates a Spring Boot 4.1 / Java 21 backend and an Angular 22 frontend from one configuration, then keeps them maintainable with entity descriptors, safe regeneration, template overrides, and OpenAPI client generation.
The generated code is intentionally plain: constructor injection, explicit layers, manual DTO mapping, Flyway or Liquibase migrations, standalone Angular components, and signals. There is no CleanStack runtime dependency and no generated abstraction layer to learn.
Why CleanStack
- One command, two applications. Generate a Spring Boot service and an Angular app that already agree on the API shape and development proxy.
- Entities, not scaffolding exercises. Describe an entity once and get the JPA model, repository, service, controller, DTOs, mapper, migration, Angular model, HTTP service, and list/detail/form pages.
- Safe regeneration. Hand-written code lives inside protected regions with checksums. Re-running a generator updates the generated code without silently deleting your work.
- Template overrides. Replace one file or a whole template pack at the project or user level. Built-in templates remain the fallback.
- OpenAPI when you need it. Generate a typed Angular client from a running backend or a saved contract, optionally with Spring API interfaces.
- CLI and local Studio. CleanStack Studio is a local web UI over the same engine, not a second implementation.
- No telemetry, no hosted service. Everything runs on your machine and writes to the paths you choose.
Requirements
| Tool | Version |
| ----------------- | ------------------------------------------------------------- |
| Node.js | 22 or later for the generator |
| npm | Bundled with Node.js 22 or later |
| JDK | 21 or later for generated Spring Boot projects |
| Maven or Gradle | Maven 3.9+ or Gradle 8.14+, matching the generated project |
| Angular Node.js | ^22.22.3, ^24.15.0, or ^26.0.0 for the generated app |
| openapi-generator | Java 11+ when generating API clients (run locally or via npx) |
Run cleanstack doctor to check the tools on the current machine and get
suggested fixes for anything missing.
Quick start
Install the generator from npm:
npm install -g cleanstack-generator
cleanstack --versionOr run it without a global install:
npx cleanstack-generator --versionCreate a project:
cleanstack new demo --db h2 --auth none --no-entities --yes
cd demoStart the backend in one terminal (macOS or Linux):
cd demo-backend
./mvnw spring-boot:run -Dspring-boot.run.profiles=devOn Windows, run the batch wrapper from Command Prompt or PowerShell:
cd demo-backend
.\mvnw.cmd spring-boot:run -Dspring-boot.run.profiles=devStart the frontend in another terminal:
cd demo-ui
npm install
npm startOpen:
- Frontend: http://localhost:4200
- Backend API: http://localhost:8080/api/greetings
- Swagger UI: http://localhost:8080/swagger-ui.html
- Health check: http://localhost:8080/actuator/health
This quick start uses H2 and disables authentication so the first run needs no
database or identity provider. The defaults are PostgreSQL, JWT, Maven, and an
Angular frontend; run cleanstack new demo without --yes for an interactive
wizard, or pass flags explicitly.
If you prefer not to install globally, run the same commands through npx, for
example npx cleanstack-generator new demo --db h2 --auth none --no-entities --yes.
What you get
demo/
├── demo-backend/ Spring Boot 4.1 service
│ ├── mvnw Maven wrapper (Maven projects)
│ ├── pom.xml or build.gradle.kts for Gradle
│ └── src/main/java/...
├── demo-ui/ Angular 22 application (optional)
│ └── src/app/...
├── ARCHITECTURE.md Full-stack architecture for humans and AI agents
├── AGENTS.md Entry point for AI coding agents
├── .ai/ Architecture and naming rules for AI agents
└── .cleanstack/
└── project.json Generation metadata used by regenerationThe Spring Boot backend is always generated. Pass --frontend none to create
only the backend.
Backend
- Java 21 and Spring Boot 4.1.2 with Spring Web MVC, Spring Data JPA, and Bean Validation
- PostgreSQL, MySQL, or H2 configuration with Flyway or Liquibase migrations
- Layered packages:
controller,service,domain,repository,web/dto,web/mapper,config, andsecurity - CRUD endpoints for each entity with validation and consistent HTTP statuses
- JWT resource-server security, cookie-based sessions, OIDC (Keycloak/Auth0), or no authentication
- springdoc OpenAPI/Swagger UI and Actuator health endpoints
- Virtual threads enabled by default
- Optional Dockerfile and Docker Compose environment
Frontend
- Angular 22 standalone components, signals, and zoneless change detection
- Page-first structure with lazy-loaded routes and a responsive application shell
- Entity list, detail, and create/edit pages backed by typed HTTP services
- Development proxy from
/apitohttp://localhost:8080 - SCSS design tokens and no runtime UI framework dependency
Authenticated projects include a matching Angular login page, profile page, route guard, and HTTP interceptor. JWT mode accepts an access token for local development, session mode signs in with a username and password, and OIDC modes use the authorization-code flow with PKCE.
AI coding agents
Every project ships AGENTS.md, a workspace ARCHITECTURE.md, and a .ai/
folder of binding architecture and naming rules. Agents that read them produce
follow-up code that matches the generated conventions and survives
cleanstack regenerate. See AI-friendly conventions.
Commands
| Command | Purpose |
| ----------------------------------- | ---------------------------------------------------------- |
| cleanstack new <name> | Create a project skeleton and optionally its entities |
| cleanstack entity <name> | Add an entity to an existing generated project |
| cleanstack generate entity <name> | Alias for cleanstack entity |
| cleanstack g e <name> | Short alias for cleanstack entity |
| cleanstack regenerate | Re-render project files while preserving protected regions |
| cleanstack regenerate --all | Re-render the skeleton and every known entity |
| cleanstack openapi [spec] | Generate Angular and optionally Spring API artifacts |
| cleanstack api [spec] | Alias for cleanstack openapi |
| cleanstack templates ... | List, copy, diff, and reset template overrides |
| cleanstack config ... | Inspect and validate the resolved configuration |
| cleanstack doctor | Check tool versions, configuration, and built-in templates |
| cleanstack ui | Start CleanStack Studio on a local port |
Global flags work before or after a command: --verbose/-v, --quiet/-q,
--version/-V, and --help/-h. Run cleanstack <command> --help for the
full option list.
Entities in a minute
Add entities/Product.yaml in the workspace:
name: Product
fields:
- name: name
type: String
required: true
maxLength: 120
- name: price
type: BigDecimal
required: true
min: 0Then generate it:
cleanstack entity ProductCleanStack creates the backend model, persistence, service, HTTP layer,
migration, and the Angular model, service, and pages. Migrations get descriptive
names such as V2__create_products_table.sql. When a descriptor changes,
CleanStack adds an update migration (for example
V3__update_products_add_sku.sql) instead of editing migrations that already
ran. Descriptors can also be built inline with repeatable --field options:
cleanstack entity Product \
--field 'name:String:required:maxLength=120' \
--field 'price:BigDecimal:required:min=0' \
--seedChoose Liquibase when creating a project with --migrations liquibase; the
generated changelogs live under src/main/resources/db/changelog. Use --seed
to add a sample row, or define explicit seedData rows in the descriptor. See
Migrations and seed data.
See Entity descriptors for field types, validations, inline syntax, and relation ownership rules.
Safe regeneration
Generated files contain protected regions. Each region records a checksum of the template body it was generated from, so CleanStack can tell whether the template changed, whether you changed the region, or both.
cleanstack regenerate --dry-run # show what would change
cleanstack regenerate --all # skeleton plus every known entity
cleanstack regenerate --force # replace files completely, including regionsFiles without protected regions are preserved on rerun unless --force is
passed. Conflicts leave the file untouched and are reported with the region
ids; generation stops rather than writing a partially merged file. See
Protected regions for the full contract.
CleanStack Studio
cleanstack uiStudio opens on http://127.0.0.1:5173. It provides a four-step project wizard,
a visual entity editor with generated-code previews, and YAML save support. It
uses the same runNewCommand and runEntityCommand engine as the CLI, so the
wizard and terminal produce the same files.
cleanstack ui --workspace ~/projects --port 5180
cleanstack ui --host 0.0.0.0
cleanstack ui --static # built UI only, bundled demo data, no APIStudio is local-first: local generation is restricted to loopback clients, and ZIP downloads work without writing to the workspace. Static mode serves the built bundle and demo data without accessing project files.
Documentation
| Document | Contents |
| ------------------------------------------------- | ------------------------------------------------------------------------------- |
| User guide | Installation, project creation, entities, regeneration, Studio, troubleshooting |
| Architecture | Generator modules, pipelines, template engine, generated application design |
| Templates | Template catalog, context variables, helpers, manifests, overrides |
| Entity descriptors | YAML format, field types, validations, relations |
| Protected regions | Marker syntax, checksums, merge strategies, error codes |
| AI-friendly conventions | AGENTS.md, .ai/ rules, naming contract, customization for AI coding agents |
| OpenAPI integration | springdoc, client generation, contract-first workflows, manifests |
| Extensions | Adding field types and frontend frameworks without forking the core |
| Comparison | CleanStack versus JHipster, Spring Initializr, Bootify, and Seed4J |
| Contributing | Development setup, tests, conventions, pull request checklist |
Development
npm run build # compile the CLI and library to dist/
npm test # build, then run the Node test suite
npm run test:e2e # opt-in full-stack test; needs Java 21, Maven, network
npm run lint # ESLint
npm run format:check # Prettier check
npm run ui:check # type-check the Studio sources
npm run ui # build and start Studio with the local API
npm run ui:dev # Vite hot reload plus the local APISee Contributing for the test strategy, repository layout, and template authoring rules.
License
MIT. See LICENSE.
