define-routes

Use this skill when defining routes in Hanami 2.x.

Core principle: Routes map URLs to Actions. They are explicit, readable, and RESTful.

Core Rules

1. Define routes in config/routes.rb:

   # config/routes.rb
   module MyApp
     class Routes < Hanami::Routes
       root to: "home.index"
   
       get "/users", to: "users.index"
       get "/users/:id", to: "users.show"
       post "/users", to: "users.create"
       patch "/users/:id", to: "users.update"
       delete "/users/:id", to: "users.destroy"
     end
   end

2. Use resources for RESTful routes:

   resources :users do
     resources :posts
   end

   Generates:

   • GET /users → users.index
   • GET /users/:id → users.show
   • POST /users → users.create
   • PATCH /users/:id → users.update
   • DELETE /users/:id → users.destroy

3. Use resource for singular resources (no index):

   resource :profile

4. Name routes for URL generation:

   get "/users", to: "users.index", as: :users
   get "/users/:id", to: "users.show", as: :user

   Access in Views or Actions:

   routes.path(:user, id: 1)  # => "/users/1"
   routes.url(:users)          # => "http://example.com/users"

5. Scope routes for versioning or grouping:

   scope "api" do
     scope "v1" do
       resources :users
     end
   end

6. Mount slices at paths:

   slice :api, at: "/api" do
     resources :users
   end

7. Order matters: Hanami matches routes top-to-bottom. Put specific routes before general ones (wildcards):

   # CORRECT: specific first
   get "/users/new", to: "users.new"
   get "/users/:id", to: "users.show"

Verifying Routes

After defining routes, inspect all registered routes with the Hanami CLI:

bundle exec hanami routes

This lists every route with its HTTP method, path, and action target. Use it to confirm routes are correctly registered before running tests or the server.

Common pitfalls:

• A route returning a 404 unexpectedly often means the corresponding Action file does not exist or its path doesn't match the to: identifier.
• If a more general route (e.g. get "/users/:id") appears before a specific one (e.g. get "/users/new"), the specific route will never be reached — always check ordering with hanami routes.
• Forgetting to restart the server after changing config/routes.rb can cause stale routing behaviour.

Integration