Quick start
This page builds a small catalogue: a Producto (product) with a name, a price and a unique SKU,
served as a REST API with its own React screens. It runs in memory, so you need nothing but Rust
and, for the screens, Bun. Every output on this page was captured from a real
run.
-
Create the project.
puerto nuevo --nombre tienda --sin-db --sin-demooutput ├── nucleo/ (shared value objects)├── contextos/ (one crate per context and layer)├── presentacion/ (the binaries and their wiring)├── web/ (React frontend)└── Cargo.toml✓ Project 'tienda' created.--sin-dbkeeps the data in memory, and--sin-demoleaves out theSaludoexample entity. Leave both flags out andpuerto nuevoasks. -
Scaffold an entity.
cd tiendapuerto generar scaffold Producto -- nombre:String precio:i64 sku:String!output ✓ contextos/producto/dominio/ — model, errors, repository port, MadreProducto✓ contextos/producto/aplicacion/ — create, get, list, update, delete✓ contextos/producto/infraestructura/ — RepositorioProductoEnMemoria✓ contextos/producto/rest/ — routes, dto, responses, errors✓ web/ — list, detail and form screens, HTTP repository✓ Done. Zero manual wiring.The API changed. Next: make web/sync (exports the spec, regenerates the web types)Fields come after
--asname:Type. The!makesskuunique: a second product with the same SKU is refused with409 Conflict. Entities and fields lists every type. -
Run the API.
make runThe server starts on port 8080: the Swagger UI on
/, the API under/api, and the health probes on/healthand/health/ready. -
Call it.
curl -X POST localhost:8080/api/productos \-H 'content-type: application/json' \-d '{"nombre":"Lampara","precio":4900,"sku":"LMP-01"}'201 Created {"id":"1f1d2bb9-a92d-48c4-ab78-f56cfcccdcd7","nombre":"Lampara","precio":4900,"sku":"LMP-01"}The same SKU again, then an empty name:
409 Conflict {"codigo":"producto.duplicado","mensaje":"producto.duplicado"}422 Unprocessable Entity {"codigo":"producto.validacion.nombre_vacio","mensaje":"producto.validacion.nombre_vacio"}Errors are machine-readable codes in
codigo, and domain validation is a 422. That is the error contract, the same in every Puerto project. Lists are paged:curl 'localhost:8080/api/productos?limite=10'200 OK {"desplazamiento":0,"elementos":[{"id":"1f1d2bb9-a92d-48c4-ab78-f56cfcccdcd7","nombre":"Lampara","precio":4900,"sku":"LMP-01"}],"limite":10,"total":1} -
Open the screens. In another terminal:
make web/sync # export the OpenAPI spec, regenerate the frontend's typesmake web/install && make web/dev # http://localhost:5173/productoslists them,/productos/newcreates one, and a rejected form shows the message next to the field it is about. -
Check it.
make setup # once: cargo-nextest and cargo-auditmake test # every generated test: model, use cases, routes, mappers, screensmake lint # clippy -D warningsmake format # rustfmt --checkAll three pass on a fresh scaffold. That is the baseline you keep while you build.
What you have now
Section titled “What you have now”contextos/producto/dominio/src/modelo.rsholdsProductoand its id type,IdProducto. The rules go inProducto::new: it already refuses an emptynombreand an emptysku.contextos/producto/aplicacion/src/holds the five use cases, one file each, with unit tests against a mocked repository.contextos/producto/rest/src/rutas.rsholds the five endpoints. Their tests drive the realOpenApiServicewith mocked use cases.presentacion/cableado/andpresentacion/api/src/generado/bootstrap.rswire all of it. You never edit them.
- Keep the data: Database and migrations (
puerto nuevo --db). - Add a rule that is not CRUD: Use cases.
- React to writes: Domain events.
- Understand why it is laid out this way: The architecture.