thinkoodle/rails-skills

routing

Expert guidance for defining routes in Rails applications.

Vedi sorgente

Come usare

  1. Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
  2. Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
  3. Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/thinkoodle/rails-skills --skill routing

Prima di iniziare

  • L’installazione non include abbonamenti, quote API o accesso ai file.
  • Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale

Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.

Rails Routing Expert

Define clean, RESTful, minimal routes. Extra routes create unnecessary attack surface and confuse other developers reading routes.rb.

Philosophy

  1. RESTful by default — Use resources and resource. Custom routes are a smell.
  2. Minimal surface area — Always use only: or except: to expose just what's needed.
  3. Path helpers everywhere — Hardcoded URL strings break when routes change. Use _path and _url helpers.
  4. Shallow nesting only — Don't nest resources more than 1 level deep; deeper nesting creates painful URLs and helper names.
  5. New resource > custom action — If you're adding many custom actions, you need a new controller.

When To Use This Skill

  • Adding or modifying routes in config/routes.rb
  • Deciding between namespace, scope, and module
  • Nesting resources
  • Adding member or collection routes
  • Setting up API versioning
  • Debugging route conflicts
  • Testing routes

Instructions

Step 1: Check Existing Routes

Inspect current routes before adding new ones — duplicates and conflicts cause subtle bugs:

bash
# Show all routes
bin/rails routes

# Filter by controller
bin/rails routes -c users

# Search by path or helper name
bin/rails routes -g admin

# Find unused routes (clean these up!)
bin/rails routes --unused

Step 2: Use Resources Correctly

resources (plural) — For collections

Generates 7 routes: index, show, new, create, edit, update, destroy.

ruby
# Generates all 7 routes — unused routes create dead endpoints and confuse devs
resources :articles

# Better — only generate what the controller actually implements
resources :articles, only: [:index, :show, :create]

Ask: which actions does this controller actually implement? Only route those.

resource (singular) — For singletons

Use when there's only ONE of something per user/context. No index action. No :id in URLs.

ruby
# Current user's profile — there's only one
resource :profile, only: [:show, :edit, :update]

# Current user's session
resource :session, only: [:new, :create, :destroy]

# App-wide dashboard
resource :dashboard, only: :show

⚠️ CRITICAL: `resource` (singular) still routes to a PLURAL controller. resource :profile → ProfilesController (not ProfileController)

Path helpers are singular: profile_path (not profiles_path), edit_profile_path.

When to use singular vs plural:

  • Can the user have/see multiple? → resources (plural)
  • Is there exactly one in context? → resource (singular)
  • Does an index action make sense? → resources (plural)

Step 3: Nest Resources (Max 1 Level Deep)

Nest when a child resource only makes sense within its parent.

ruby
# GOOD — 1 level deep
resources :articles do
  resources :comments, only: [:index, :create, :destroy]
end
ruby
# Avoid — 2+ levels creates unwieldy URLs and painful helper names
resources :users do
  resources :articles do
    resources :comments  # ← /users/1/articles/2/comments/3
  end
end

Use shallow nesting when child has its own identity:

ruby
# GOOD — collection routes nested, member routes flat
resources :articles do
  resources :comments, shallow: true
end
# Creates:
#   /articles/:article_id/comments     (index, create, new)
#   /comments/:id                      (show, edit, update, destroy)

This gives you the parent context where it matters (creating/listing) and clean URLs for direct access.

Nested path helpers include the parent:

ruby
article_comments_path(@article)           # GET /articles/1/comments
article_comment_path(@article, @comment)  # GET /articles/1/comments/5
# With shallow:
comment_path(@comment)                    # GET /comments/5

Step 4: Namespace vs Scope vs Module

These three look similar but behave differently — mixing them up causes confusing routing bugs.

namespace — Changes EVERYTHING (path + module + helpers)

ruby
namespace :admin do
  resources :articles, only: [:index, :show]
end
  • Path: /admin/articles
  • Controller: Admin::ArticlesController (in app/controllers/admin/)
  • Helper: admin_articles_path

Use for: Admin panels, API versions, distinct sections with their own controllers.

scope module: — Changes MODULE only (not path)

ruby
scope module: :admin do
  resources :articles, only: [:index, :show]
end
  • Path: /articles (no prefix!)
  • Controller: Admin::ArticlesController
  • Helper: articles_path

Use for: Organizing controllers into subdirectories without changing URLs.

scope path: — Changes PATH only (not module)

ruby
scope "/admin" do
  resources :articles, only: [:index, :show]
end
  • Path: /admin/articles
  • Controller: ArticlesController (no module!)
  • Helper: articles_path

Use for: URL prefixes without separate controller namespaces.

Quick Reference

MethodURL prefixController moduleHelper prefix
namespace :admin/adminAdmin::admin_
scope module: :adminnoneAdmin::none
scope "/admin"/adminnonenone

When in doubt, use `namespace`. It's the most explicit and least surprising.

Step 5: Member vs Collection Routes

When you need routes beyond the standard 7 RESTful actions.

Member routes — Act on ONE specific record (requires :id)

ruby
resources :articles, only: [:index, :show] do
  member do
    patch :publish      # PATCH /articles/:id/publish
    patch :archive      # PATCH /articles/:id/archive
  end
end

Generates: publish_article_path(@article), archive_article_path(@article)

Collection routes — Act on the collection (no :id)

ruby
resources :articles, only: [:index, :show] do
  collection do
    get :search         # GET /articles/search
    get :drafts         # GET /articles/drafts
    delete :clear_all   # DELETE /articles/clear_all
  end
end

Generates: search_articles_path, drafts_articles_path

Shorthand (single route)

ruby
resources :photos do
  get :preview, on: :member       # GET /photos/:id/preview
  get :search, on: :collection    # GET /photos/search
end

⚠️ STOP — Do you actually need a custom action?

If you're adding more than 2 custom actions, you probably need a new resource:

ruby
# BAD — too many custom actions on one resource
resources :articles do
  member do
    patch :publish
    patch :unpublish
    patch :archive
    patch :unarchive
    patch :feature
  end
end

# GOOD — extract a new resource
resources :articles, only: [:index, :show]
resources :article_publications, only: [:create, :destroy]  # publish/unpublish
resources :article_archives, only: [:create, :destroy]      # archive/unarchive

Step 6: Route Concerns (DRY Shared Patterns)

When multiple resources share the same nested routes:

ruby
concern :commentable do
  resources :comments, only: [:index, :create, :destroy]
end

concern :taggable do
  resources :tags, only: [:index, :create, :destroy]
end

resources :articles, concerns: [:commentable, :taggable]
resources :photos, concerns: [:commentable]
resources :videos, concerns: [:commentable, :taggable]

Step 7: Constraints

Segment constraints (validate params)

ruby
resources :users, constraints: { id: /\d+/ }

Request constraints (subdomain, format, etc.)

ruby
constraints subdomain: "api" do
  namespace :api do
    resources :articles, only: [:index, :show]
  end
end

Advanced constraints (custom logic)

ruby
# Lambda
get "*path", to: "errors#not_found",
  constraints: lambda { |req| !req.path.start_with?("/admin") }

# Object (responds to matches?)
class ApiConstraint
  def matches?(request)
    request.headers["Accept"]&.include?("application/json")
  end
end

constraints ApiConstraint.new do
  resources :articles, only: [:index, :show]
end

Step 8: Root Route

Always define a root route:

ruby
root "pages#home"

Namespaced roots:

ruby
namespace :admin do
  root "dashboard#show"  # /admin → Admin::DashboardController#show
end

Step 9: Redirects

ruby
# Simple redirect (301 by default)
get "/old-path", to: redirect("/new-path")

# With status code
get "/old-path", to: redirect("/new-path", status: 302)

# Dynamic redirect
get "/articles/:id", to: redirect("/posts/%{id}")

Step 10: Mount Engines

ruby
mount Sidekiq::Web => "/sidekiq"
mount ActionCable.server => "/cable"

Step 11: API Routes

ruby
namespace :api do
  namespace :v1 do
    resources :articles, only: [:index, :show, :create, :update, :destroy]
    resources :users, only: [:show]
  end
end

For API-only controllers, use defaults: { format: :json }:

ruby
namespace :api, defaults: { format: :json } do
  namespace :v1 do
    resources :articles, only: [:index, :show]
  end
end

Step 12: Direct and Resolve (Custom URL Helpers)

direct — Create custom URL helpers

ruby
direct :homepage do
  "https://example.com"
end
# homepage_url => "https://example.com"

direct :cdn_image do |model|
  "https://cdn.example.com/#{model.image_path}"
end
# cdn_image_url(@photo) => "https://cdn.example.com/photos/1.jpg"

resolve — Customize polymorphic routing for models

Required when using resource (singular) with form_with:

ruby
resource :basket, only: [:show, :update]
resolve("Basket") { [:basket] }

# Now form_with(model: @basket) generates /basket (not /baskets/:id)

Route File Organization

Order your config/routes.rb like this:

ruby
Rails.application.routes.draw do
  # 1. Root
  root "pages#home"

  # 2. Authentication / sessions
  resource :session, only: [:new, :create, :destroy]
  resources :registrations, only: [:new, :create]

  # 3. Core resources (most used first)
  resources :articles do
    resources :comments, only: [:index, :create], shallow: true
  end

  # 4. Namespaced sections
  namespace :admin do
    root "dashboard#show"
    resources :users
  end

  namespace :api, defaults: { format: :json } do
    namespace :v1 do
      resources :articles, only: [:index, :show]
    end
  end

  # 5. Utility routes
  get "up", to: "rails/health#show", as: :rails_health_check

  # 6. Catch-all (if needed — put LAST)
  get "*path", to: "errors#not_found"
end

Testing Routes

ruby
# test/routing/articles_routing_test.rb
class ArticlesRoutingTest < ActionDispatch::IntegrationTest
  test "routes to articles#index" do
    assert_routing "/articles", controller: "articles", action: "index"
  end

  test "routes to articles#show" do
    assert_routing "/articles/1", controller: "articles", action: "show", id: "1"
  end

  test "generates correct path" do
    assert_generates "/articles/1", controller: "articles", action: "show", id: "1"
  end

  test "recognizes route" do
    assert_recognizes(
      { controller: "articles", action: "create" },
      { path: "/articles", method: :post }
    )
  end
end

Anti-Patterns

  1. Generating all 7 routes when you need 2 — Always use only: or except:
  2. Nesting deeper than 1 level — Flatten with shallow or separate resources
  3. Hardcoding paths — Hardcoded strings break when routes change; use article_path(@article) instead of "/articles/#{@article.id}"
  4. Using `match ... via: :all` — Exposing all HTTP verbs creates security surface; be explicit
  5. Too many custom member/collection actions — Extract a new resource instead
  6. Confusing namespace/scope/module — Check the table in Step 4
  7. `resource` when you mean `resources` — Singular = one thing, no index, no :id
  8. Missing `only:`/`except:` on nested resources — Nested routes bloat fast
  9. Forgetting `resolve` with singular `resource` — form_with will break without it
  10. Route order bugs — More specific routes go above general ones (Rails matches top-down, first match wins)

Debugging

bash
# See what a specific URL maps to
bin/rails routes -g "GET /articles"

# Check for conflicts
bin/rails routes | grep articles

# In rails console
Rails.application.routes.url_helpers.articles_path
app.edit_article_path(Article.first)

For detailed patterns, examples, and edge cases, see reference.md in this skill directory.

dallo stesso repository

Altri Skills

Tutti gli Skills
thinkoodle
Community

action-cable

Expert guidance for implementing real-time features with Action Cable in Rails applications. Use when working with websockets, channels, subscriptions, broadcasting, live updates, push notifications, or Solid Cable. Covers connection authentication, channel creation, streaming, client-side JS, testing, and deployment. Clarifies when to use Action Cable directly vs Turbo Streams broadcasting.

Installazioni / 1h
1
GitHub Stars
7
Aggiornato
8 set
thinkoodle
Community

action-controller

Expert guidance for writing Rails controllers with Action Controller. Use when writing controller actions, strong parameters, beforeaction filters, rendering responses, redirects, flash messages, sessions, cookies, rescuefrom error handling, streaming, CSRF protection, or HTTP authentication. Covers params permitting (especially nested params — the 1 source of agent bugs), callbacks, request/response objects, and security. Trigger on "controller", "action", "strong parameters", "params", "before

Installazioni / 1h
1
GitHub Stars
7
Aggiornato
8 set
thinkoodle
Community

action-mailbox

Expert guidance for receiving and processing inbound emails with Action Mailbox in Rails. Use when setting up inbound email processing, routing emails to mailboxes, configuring ingress providers (Mailgun, SendGrid, Postfix, etc.), handling attachments, bouncing emails, or testing with fixtures. Covers "action mailbox", "inbound email", "receive email", "process email", "email routing", "mailbox", "incoming email", "email processing", "ingress", "InboundEmail".

Installazioni / 1h
1
GitHub Stars
7
Aggiornato
8 set
thinkoodle
Community

active-model

Build plain Ruby objects that integrate with Rails forms, validations, serialization, and Action Pack — without a database. Use when building form objects, search forms, API wrappers, configuration objects, virtual models, or any PORO that needs model-like behavior. Triggers on "active model", "form object", "plain Ruby object", "non-database model", "ActiveModel", "PORO", "service object validation", "virtual model", "tableless model", "search form", "ActiveModel::API", "ActiveModel::Model".

Installazioni / 1h
1
GitHub Stars
7
Aggiornato
8 set