Use when running Hanami 2.x development commands — `hanami dev` with code reloading though config files require server restart, verify server responds via `curl http://localhost:2300` and recover from port conflicts and config syntax errors, `hanami console` requiring DATABASE_URL set with HANAMI_ENV awareness before destructive operations, using the container to explore slices/relations/repos, and `hanami routes`/`hanami middleware` for stack inspection. Covers hanami dev (starting the development server with code reloading), hanami console (REPL with full container loaded for exploring the app, accessing slices, inspecting registered components, querying relations, and testing repository methods), hanami routes (listing all routes), and hanami middleware (inspecting the middleware stack).
Use when running Hanami 2.x development commands — `hanami dev` with code reloading though config files require server restart, verify server responds via `curl http://localhost:2300` and recover from port conflicts and config syntax errors, `hanami console` requiring DATABASE_URL set with HANAMI_ENV awareness before destructive operations, using the container to explore slices/relations/repos, and `hanami routes`/`hanami middleware` for stack inspection. Covers hanami dev (starting the development server with code reloading), hanami console (REPL with full container loaded for exploring the app, accessing slices, inspecting registered components, querying relations, and testing repository methods), hanami routes (listing all routes), and hanami middleware (inspecting the middleware stack).
Use this skill when running Hanami 2.x development commands.
Quick Reference
Command
Purpose
hanami dev
Start development server with code reloading
hanami console
Start interactive REPL with full container loaded
hanami routes
List all routes
hanami middleware
List middleware stack
hanami version
Show Hanami version
Core Rules
Start the development server:
hanami dev
Verify: Once started, confirm the server is responding:
curl http://localhost:2300
Error recovery:
Port already in use: lsof -ti:2300 | xargs kill -9 or change port in config/app.rb
Server fails to start: Check config/app.rb and config/routes.rb for syntax errors
Does not reload configuration files (requires restart after editing config/app.rb or config/routes.rb)
Start the console:
Before starting, ensure DATABASE_URL is set if your app uses a database:
echo$DATABASE_URL
Then start the console:
hanami console
Uses development environment by default; override with HANAMI_ENV=test hanami console.
Access components directly:
app = Hanami.app
rom = app["db.rom"]
users = rom.relations[:users]
users.insert(email:"test@example.com")
Error recovery:
Database connection refused: Verify DATABASE_URL is set and database server is running
Boot errors: Check config/providers/ for missing dependencies or configuration issues
Use the console for exploration:
# Query the databaseHanami.app["db.rom"].relations[:users].to_a
# Access a RepositoryHanami.app["repos.user_repo"].all
# Access settingsHanami.app[:settings].database_url
# Test a Relation queryHanami.app["relations.users"].active.to_a
List routes and middleware:
hanami routes
hanami middleware
Common Mistakes
Config files don't reload: hanami dev reloads Ruby code only. Restart the server after editing configuration files.
Environment awareness: Always verify HANAMI_ENV before running destructive operations in the console — it defaults to development but is easy to misconfigure.
