run-development

Use this skill when running Hanami 2.x development commands.

---

Quick Reference

---

Core Rules

1. Start the development server:

   hanami dev

   Verify: Once started, confirm the server is responding:

   curl http://localhost:2300

   A valid HTTP response (even a 404 or 200) confirms the server is running.

   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

2. 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

   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

3. Use the console for exploration:

   # Query the database
   Hanami.app["db.rom"].relations[:users].to_a
   
   # Access a Repository
   Hanami.app["repos.user_repo"].all
   
   # Access settings
   Hanami.app[:settings].database_url
   
   # Test a Relation query
   Hanami.app["relations.users"].active.to_a

4. Development server behavior:

   • Does not reload configuration files (requires restart)

5. Console environment:

   • Loads the full Hanami application
   • Uses development environment by default
   • Can override with HANAMI_ENV=test hanami console

6. List routes:

   hanami routes

7. List middleware:

   hanami middleware

---

Common Mistakes

• Config files don't reload: hanami dev reloads Ruby code, not configuration. Restart the server after editing config/app.rb or config/routes.rb.
• Missing DATABASE_URL: The console loads the full app and requires DATABASE_URL to connect. Run echo $DATABASE_URL before starting.
• Environment awareness: Always verify HANAMI_ENV before running destructive operations in the console — it defaults to development but is easy to misconfigure.

---

Integration