Skip to content

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.

  1. Create the project.

    puerto nuevo --nombre tienda --sin-db --sin-demo
    output
    ├── 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-db keeps the data in memory, and --sin-demo leaves out the Saludo example entity. Leave both flags out and puerto nuevo asks.

  2. Scaffold an entity.

    cd tienda
    puerto 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 -- as name:Type. The ! makes sku unique: a second product with the same SKU is refused with 409 Conflict. Entities and fields lists every type.

  3. Run the API.

    make run

    The server starts on port 8080: the Swagger UI on /, the API under /api, and the health probes on /health and /health/ready.

  4. 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}
  5. Open the screens. In another terminal:

    make web/sync # export the OpenAPI spec, regenerate the frontend's types
    make web/install && make web/dev # http://localhost:5173

    /productos lists them, /productos/new creates one, and a rejected form shows the message next to the field it is about.

  6. Check it.

    make setup # once: cargo-nextest and cargo-audit
    make test # every generated test: model, use cases, routes, mappers, screens
    make lint # clippy -D warnings
    make format # rustfmt --check

    All three pass on a fresh scaffold. That is the baseline you keep while you build.

  • contextos/producto/dominio/src/modelo.rs holds Producto and its id type, IdProducto. The rules go in Producto::new: it already refuses an empty nombre and an empty sku.
  • contextos/producto/aplicacion/src/ holds the five use cases, one file each, with unit tests against a mocked repository.
  • contextos/producto/rest/src/rutas.rs holds the five endpoints. Their tests drive the real OpenApiService with mocked use cases.
  • presentacion/cableado/ and presentacion/api/src/generado/bootstrap.rs wire all of it. You never edit them.