Modular Routes

Dedicated controllers for each of your Rails route actions.

If you've ever used Hanami routes or already use dedicated controllers for each route action, this gem might be useful.

Disclaimer: There's no better/worse nor right/wrong approach, it's up to you to decide how you prefer to organize the controllers and routes of your application.

Docs: Unreleased, v0.3.0, v0.2.0, v0.1.1

Let's imagine that you have to design a full RESTful resource named articles with some custom routes like the table below

How would you organize the controllers and routes of this application?

The most common approach is to have all the actions (RESTful and customs) in the same controller.

# routes.rb

resources :articles do
  get  :stats,   on: :collection
  post :archive, on: :member
end

# articles_controller.rb

class ArticlesController
  def index
    # ...
  end

  def create
    # ...
  end

  # other actions...

  def stats
    # ...
  end

  def archive
    # ...
  end
end

The reason I don't like this approach is that you can end up with a lot of code that are not related to each other in the same file. You can still have it all organized but I believe that it could be better.

DHH prefers to keep the RESTful actions (index, new, edit, show, create, update, destroy) inside the same controller and the custom ones in dedicated controllers but represented as RESTful actions.

One way of representing that would be

# routes.rb

resources :articles do
  get  :stats,   on: :collection, to: 'articles/stats#show'
  post :archive, on: :member,     to: 'articles/archive#create'
end

# articles_controller.rb

class ArticlesController
  def index
    # ...
  end

  def create
    # ...
  end

  # other actions...
end

# articles/archive_controller.rb

class Articles::ArchiveController
  def create
  end
end

# articles/stats_controller.rb

class Articles::StatsController
  def show
  end
end

This approach is better than the previous one because it restricts the main controller file to contain only the RESTful actions. Additional routes would require you to create a dedicated controller to handle that individually.

Another approach (and what I personally prefer) is to have one controller per route. What it was done for archive and stats routes would also be applied to all the RESTful routes.

The files would be organized inside articles/ folder that would act as a namespace

app/
└── controllers/
    └── articles/
        ├── archive_controller.rb
        ├── create_controller.rb
        ├── destroy_controller.rb
        ├── edit_controller.rb
        ├── index_controller.rb
        ├── new_controller.rb
        ├── show_controller.rb
        ├── stats_controller.rb
        └── update_controller.rb

And the controllers would have one single action named call like

# articles/index_controller.rb

class Articles::IndexController
  def call
  end
end

# articles/archive_controller.rb

class Articles::ArchiveController
  def call
  end
end

Here are two ways of representing what was explained above:

scope module: :articles, path: '/articles' do
  get    '/',        to: 'index#call', as: 'articles'
  post   '/',        to: 'create#call'

  get    'new',      to: 'new#call',  as: 'new_article'
  get    ':id/edit', to: 'edit#call', as: 'edit_article'
  get    ':id',      to: 'show#call', as: 'article'
  patch  ':id',      to: 'update#call'
  put    ':id',      to: 'update#call'
  delete ':id',      to: 'destroy#call'

  post 'stats',       to: 'stats#call',   as: 'stats_articles'
  post ':id/archive', to: 'archive#call', as: 'archive_article'
end

or

resources :articles, module: :articles, only: [] do
  collection do
    get  :index,  to: 'index#call'
    post :create, to: 'create#call'
    post :stats,  to: 'stats#call'
  end

  new do
    get :new, to: 'new#call'
  end

  member do
    get    :edit,    to: 'edit#call'
    get    :show,    to: 'show#call'
    patch  :update,  to: 'update#call'
    put    :update,  to: 'update#call'
    delete :destroy, to: 'destroy#call'
    post   :archive, to: 'archive#call'
  end
end

This is the best approach in my opinion because your controller will contain only code related to that specific route action. It will also be easier to test and maintain the code.

If you've decided to go with the last approach, unless you organize your routes in separated files, your config/routes.rb might get really messy as your application grows due to verbosity.

So, what if we had a simpler way of doing all of that? Let's take a look at how modular routes can help us.

Add this line to your application's Gemfile:

gem "modular_routes"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install modular_routes

modular_routes uses Rails route helpers behind the scenes. So you can pretty much use everything except for a few limitations that will be detailed later.

For the same example used in the motivation, using modular routes we now have

# routes.rb

modular_routes do
  resources :articles do
    collection do
      post :stats
    end

    member do
      post :archive
    end
  end
end

or to be shorter

# routes.rb

modular_routes do
  resources :articles do
    post :stats,   on: :collection
    post :archive, on: :member
  end
end

The output routes for the code above would be

You can restrict resource RESTful routes with :only and :except similar to what you can do in Rails.

modular_routes do
  resources :articles, only: [:index, :show]

  resources :comments, except: [:destroy]
end

As in Rails you can use :path to rename route paths.

modular_routes do
  resources :articles, path: 'posts'
end

is going to produce

As of version 0.2.0, modular routes supports nesting just like Rails.

modular_routes do
  resources :books, only: [] do
    resources :reviews
  end
end

The output routes for that would be

Sometimes you want to declare a non-resourceful routes and its straightforward without modular routes:

  get :about, to: "about/show#call"

Even being pretty simple, with modular routes you can omit the #call action like

modular_routes do
  get :about, to: "about#show"
end

It expects About::IndexController to exist in controllers/about/index_controller.rb.

If to doesn't match controller#action pattern, it falls back to Rails default behavior.

scope falls back to Rails default behavior, so you can use it just like you would do it outside modular routes.

modular_routes do
  scope :v1 do
    resources :books
  end

  scope module: :v1 do
    resources :books
  end
end

In this example it recognizes /v1/books and /books expecting BooksController and V1::BooksController respectively.

As scope, namespace also falls back to Rails default behavior:

modular_routes do
  namespace :v1 do
    resources :books
  end
end

When you want to reuse route declarations that are usually associated with a common behavior, you can use concerns declaring blocks like:

concern :commentable do
  resource :comments
end

concern :activatable do
  member do
    put :activate
    put :deactivate
  end
end

To use it you can pass it through resource(s) options or calling concerns helper inside of a resource(s) block:

resources :articles, concerns: :commentable

resources :articles, concerns: [:activatable]

# or

resources :articles, concerns: :activatable do
  concerns :commentable
end

The output of that would be:

When config.api_only is set to true, :edit and :new routes won't be applied for resources.

• constraints are supported via scope :constraints and options
• concerns are not supported inside modular_routes block but can be declared outside and used as options

Let us know more limitations by creating a new issue.

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/vitoravelino/modular_routes. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

Everyone interacting in the ModularRoutes project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Modular Routes is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.