Capitulo 4: Setup del Cargo Workspace

15 de febrero de 2026 Por: SiempreListo

rustwasmaxumleptos

Que es un Cargo Workspace

Un Cargo Workspace permite gestionar multiples crates (proyectos) en un solo repositorio. Comparten un unico Cargo.lock y directorio target/, lo que garantiza versiones consistentes y compilaciones mas rapidas por cache compartido.

Para nuestro Kanban, el workspace agrupa backend y frontend en un mismo repositorio pero como binarios independientes.

Cargo.toml raiz

El archivo raiz solo define los miembros del workspace:

[workspace]
resolver = "2"
members = [
    "apps/app-backend",
    "apps/app-frontend",
]

resolver = "2": usa el resolver de dependencias moderno de Cargo (requerido desde edition 2021)
members: lista de crates que componen el workspace

No hay dependencias aqui. Cada crate define las suyas.

Crear la estructura

# Crear el directorio raiz
mkdir rust-poc && cd rust-poc

# Crear los proyectos
mkdir -p apps
cargo new apps/app-backend
cargo new apps/app-frontend

# Crear directorio de migraciones
mkdir -p apps/app-bbdd/migrations

El directorio app-bbdd no es un crate de Rust: es simplemente una carpeta con archivos SQL y la base de datos SQLite.

Dependencias del Backend

apps/app-backend/Cargo.toml

[package]
name = "app-backend"
version = "0.1.0"
edition = "2021"

[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sqlx = { version = "0.8", features = ["runtime-tokio", "sqlite"] }
tower-http = { version = "0.6", features = ["cors"] }
thiserror = "2"
anyhow = "1"
uuid = { version = "1", features = ["v4", "serde"] }
tracing = "0.1"
tracing-subscriber = "0.3"
dotenvy = "0.15"
chrono = { version = "0.4", features = ["serde"] }

[dev-dependencies]
mockall = "0.13"
tower = { version = "0.5", features = ["util"] }
http-body-util = "0.1"

Explicacion de cada dependencia

Framework y runtime:

Crate	Version	Para que sirve
`axum`	0.8	Framework HTTP. Define rutas, extractors y handlers
`tokio`	1 (full)	Runtime async. `full` habilita IO, timers, macros, multithreading
`tower-http`	0.6 (cors)	Middleware HTTP. Usamos `CorsLayer::permissive()` para permitir requests del frontend WASM

Serializacion:

Crate	Version	Para que sirve
`serde`	1 (derive)	Serializar/deserializar structs. `derive` habilita `#[derive(Serialize, Deserialize)]`
`serde_json`	1	Convertir entre structs Rust y JSON

Base de datos:

Crate	Version	Para que sirve
`sqlx`	0.8	Queries SQL async. `runtime-tokio` integra con nuestro runtime, `sqlite` habilita el driver SQLite

Manejo de errores:

Crate	Version	Para que sirve
`thiserror`	2	Macro `#[derive(Error)]` para crear enums de error con mensajes. Usado en `DomainError`
`anyhow`	1	Error generico para `main()` y situaciones donde no necesitas un tipo especifico

Utilidades:

Crate	Version	Para que sirve
`uuid`	1 (v4, serde)	Genera UUIDs v4 para `CardId`. `serde` permite serializar/deserializar UUIDs
`chrono`	0.4 (serde)	Manejo de fechas (`DateTime<Utc>`). `serde` para serializar timestamps
`tracing`	0.1	Logging estructurado. `tracing::info!("Servidor en http://localhost:{port}")`
`tracing-subscriber`	0.3	Configura la salida de logs (formato, nivel)
`dotenvy`	0.15	Carga variables de entorno desde `.env`

Dev dependencies (solo para tests):

Crate	Version	Para que sirve
`mockall`	0.13	Genera mocks automaticos desde traits con `#[cfg_attr(test, mockall::automock)]`
`tower`	0.5 (util)	Utilidades para testear servicios Tower/Axum
`http-body-util`	0.1	Helpers para leer bodies HTTP en tests

Dependencias del Frontend

apps/app-frontend/Cargo.toml

[package]
name = "app-frontend"
version = "0.1.0"
edition = "2021"

[dependencies]
leptos = { version = "0.7", features = ["csr"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
uuid = { version = "1", features = ["v4", "serde", "js"] }
gloo-net = { version = "0.6", features = ["http"] }
web-sys = { version = "0.3", features = [
    "DragEvent",
    "DataTransfer",
    "HtmlElement",
    "Element",
] }
wasm-bindgen = "0.2"

Explicacion de cada dependencia

Crate	Version	Para que sirve
`leptos`	0.7 (csr)	Framework UI reactivo. `csr` = Client-Side Rendering, compila a WASM sin servidor
`serde`	1 (derive)	Deserializar las respuestas JSON del backend a structs Rust
`serde_json`	1	Construir bodies JSON para enviar al backend
`uuid`	1 (v4, serde, js)	UUIDs en el frontend. `js` usa `crypto.getRandomValues()` del navegador en vez de `/dev/urandom`
`gloo-net`	0.6 (http)	Cliente HTTP para WASM. Wrapper sobre la Fetch API del navegador
`web-sys`	0.3	Bindings a las Web APIs del navegador. Cada feature habilita una API especifica
`wasm-bindgen`	0.2	Puente entre Rust/WASM y JavaScript. Requerido por web-sys y gloo

Features de web-sys detalladas

web-sys es modular: solo incluyes las APIs que necesitas. Para el drag & drop:

DragEvent: eventos dragstart, dragover, drop
DataTransfer: getData()/setData() para transferir el ID de la tarjeta
HtmlElement y Element: manipulacion basica del DOM

Archivo .env

DATABASE_URL=sqlite:apps/app-bbdd/kanban.db?mode=rwc
PORT=22000

DATABASE_URL: ruta relativa al archivo SQLite. ?mode=rwc significa Read-Write-Create (crea el archivo si no existe)
PORT: puerto donde escucha Axum. Elegimos 22000 para no colisionar con puertos comunes

Migracion SQL

apps/app-bbdd/migrations/001_create_cards.sql

CREATE TABLE IF NOT EXISTS cards (
    id TEXT PRIMARY KEY,
    title TEXT NOT NULL,
    description TEXT NOT NULL DEFAULT '',
    lane TEXT NOT NULL DEFAULT 'todo',
    position INTEGER NOT NULL DEFAULT 0,
    completed BOOLEAN NOT NULL DEFAULT FALSE,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL
);

La migracion se ejecuta al iniciar el backend con include_str!:

sqlx::query(include_str!("../../app-bbdd/migrations/001_create_cards.sql"))
    .execute(&pool)
    .await?;

include_str! embebe el contenido del archivo SQL en el binario en tiempo de compilacion. CREATE TABLE IF NOT EXISTS es idempotente: se puede ejecutar multiples veces sin error.

Compilacion WASM con Trunk

Para compilar el frontend a WASM necesitas Trunk, un bundler para aplicaciones Rust/WASM:

# Instalar Trunk
cargo install trunk

# Agregar el target WASM
rustup target add wasm32-unknown-unknown

Trunk busca un archivo index.html en la raiz del crate frontend:

<!-- apps/app-frontend/index.html -->
<!DOCTYPE html>
<html>
<head>
    <link data-trunk rel="css" href="style.css" />
</head>
<body></body>
</html>

Trunk automaticamente detecta que es un proyecto Rust, compila a WASM, genera los archivos JS de pegamento (glue code), e inyecta los scripts en el HTML.

Verificar que todo compila

# Compilar todo el workspace (backend nativo)
cargo build --workspace

# Compilar solo el frontend a WASM
cd apps/app-frontend && trunk build

# Ejecutar el backend
cargo run -p app-backend

# Servir el frontend con hot-reload
cd apps/app-frontend && trunk serve

Si cargo build --workspace compila sin errores, la estructura esta correcta. El backend compila a binario nativo y el frontend se compila por separado a WASM con Trunk.

Resumen

La configuracion del workspace es minimalista:

1 archivo Cargo.toml raiz con la lista de miembros
2 crates: backend (binario nativo) y frontend (compila a WASM)
1 directorio app-bbdd con migraciones SQL
1 archivo .env con configuracion

El Cargo Workspace permite que ambos crates compartan Cargo.lock (versiones consistentes) y target/ (cache de compilacion), mientras cada uno define sus propias dependencias especificas para su plataforma.

← Anterior: Arquitectura Hexagonal | Siguiente: Dominio - Entidades y Value Objects →