rails_server_hotkeys

Keyboard shortcuts for bin/rails server.

Press r to restart the server. No more touch tmp/restart.txt in another terminal.

=> Booting Puma
...
› Press r to restart, h for help

# Gemfile
gem "rails_server_hotkeys", group: :development

That's it. Run bin/rails s and press a key.

# config/initializers/hotkeys.rb
if defined?(RailsServerHotkeys)
  RailsServerHotkeys.register("m", "run db:migrations") { system("bin/rails db:migrate") }
  RailsServerHotkeys.register("t", "run custom task") { system("bin/rails myapp:do_something") }
  RailsServerHotkeys.register("e", "run system echo") { system("echo 'custom message'") }
end

Registering an existing key replaces it; RailsServerHotkeys.unregister("o") removes one.

# config/environments/development.rb
config.hotkeys.enabled = false               # turn it off
config.hotkeys.url = "https://myapp.test"    # URL opened by `o` (default: localhost on the port the server is listening on)

Or disable for a single run: RAILS_SERVER_HOTKEYS=false bin/rails s.

Messages are light blue by default. Change it in an initializer:

# config/initializers/hotkeys.rb
if defined?(RailsServerHotkeys)
  RailsServerHotkeys.color = :green       # black, red, green, yellow, blue, magenta, cyan, white,
                                          # or light_* of any of them (the default is :green)
  RailsServerHotkeys.color = 208          # 256-color palette (0-255)
  RailsServerHotkeys.color = "#ff8800"    # true color (hex)
  RailsServerHotkeys.color = nil          # no color
end

An invalid value raises ArgumentError at boot. Colors are skipped when the output isn't a terminal or NO_COLOR is set.

Only for rails server, in the development environment, when stdin is a terminal. Console, rake, tests, jobs and non-interactive runs (Docker without -it, CI) are untouched.

• Your config.ru must call Rails.application.load_server. Rails has generated it since 6.1; apps created on older versions may lack it, and then the gem does nothing. Add it after run Rails.application.
• Restart needs Puma's tmp_restart plugin. It's in the config/puma.rb generated by Rails; if yours lacks it, add plugin :tmp_restart.
• bin/dev (foreman) doesn't forward stdin, so hotkeys can't work there. Run bin/rails s directly, or use overmind and overmind connect web.
• Unix/macOS only (uses stty). On Windows the gem does nothing.

bundle install
bundle exec rake test

rake test:matrix boots a real bin/rails server in a pseudo-terminal for each Rails/Puma combination in gemfiles/ and checks the banner, r and q:

bundle exec rake test:matrix
bundle exec rake test:matrix GEMFILES=rails_8.1   # only matching gemfiles

The first run installs each bundle, so it takes a while. To add a combination, copy one of the files in gemfiles/.

The unit tests run without Rails, but hotkeys only show up for real under rails server in a terminal. To try your changes by hand, create a throwaway app next to the gem:

# Needs the rails and bundler gems (`gem install rails bundler`)
cd ..
rails new hotkeys-dummy --minimal --skip-git
cd hotkeys-dummy

# Point the app at your local copy of the gem
echo 'gem "rails_server_hotkeys", path: "../restart-rails-hotkeys", group: :development' >> Gemfile
bundle install

bin/rails s

Adjust the path: if your clone has a different folder name.

You should see this in green, right after Puma's Use Ctrl-C to stop:

› Press r to restart, h for help

Things to check:

• r prints * Restarting... and the server comes back up
• h lists the hotkeys, c clears the screen
• o opens the browser on the port the server is listening on (try bin/rails s -p 4000)
• q or Ctrl+C stops the server, and your shell echoes what you type again
• bin/rails s < /dev/null boots normally with no banner (no TTY, hotkeys off)

Because the gem is loaded through path:, edits to it take effect on the next restart: press r instead of stopping the server. You don't need to run bundle install again unless you change the gemspec.

Inspired by the keyboard shortcuts in Expo CLI.

If you find this useful, feel free to bring the idea into Rails itself.

MIT