class_names helper does this cleanly.
…interpolating conditional classes with ternaries or post-statement conditionals:
<div class="p-4 rounded <%= @error ? 'bg-red-50 border-red-500' : '' %> <%= 'opacity-50 cursor-not-allowed' if @disabled %>">
<%= @message %>
</div>
…the class_names helper:
<%= tag.div class: class_names(
"p-4 rounded",
"bg-red-50 border-red-500": @error,
"opacity-50 cursor-not-allowed": @disabled
) do %>
<%= @message %>
<% end %>
String arguments are always applied; trailing keyword-style entries are included when their value is truthy and silently dropped otherwise.
Better still — Rails tag helpers (tag.*, link_to, form builders) already run the class: argument through the process implicitly, so you can drop the wrapper and hand it an array directly. The trailing key: value pairs don’t need their own {} either; Ruby wraps them into a Hash for you:
<%= tag.div class: [
"p-4 rounded",
"bg-red-50 border-red-500": @error,
"opacity-50 cursor-not-allowed": @disabled
] do %>
<%= @message %>
<% end %>
An active nav link:
<%= link_to "Home", root_path,
class: ["nav-link px-3 py-2",
"text-blue-700 font-semibold": current_page?(root_path)] %>
A form field with errors:
<%= f.text_field :email,
class: ["field", "field--error": @user.errors[:email].any?] %>
A flash message:
<% flash.each do |type, message| %>
<%= tag.p message, class: ["flash",
notice: type == "notice",
alert: type == "alert"] %>
<% end %>
An active tab:
<%= link_to "Overview", project_path(@project),
class: ["tab", "tab--active": current_page?(project_path(@project))] %>
Or wrap a repeated pattern in a helper. Helpers often return Strings, which would be a case where you call class_names directly:
def class_names_for_project(project)
class_names("status-badge",
"status-badge--primary": project.active?,
"status-badge--muted": project.archived?)
end
<%= tag.span @project.status, class: class_names_for_project(@project) %>
The unsophisticated approach ends up with extra whitespace in the rendered HTML with ERB tags inside an HTML attribute (which I’m not a fan of visually), plus it’s hard to scan which classes are always present and which are conditional.
The tag helpers call token_list on whatever you pass to class:, which is aliased as class_names. It splits whitespace-separated tokens, deduplicates them, and returns an HTML-safe string. So ["p-4", "p-4 rounded"] collapses to "p-4 rounded" rather than repeating p-4.
You have to call class_names directly when you’re not inside a tag helper — building a string in a helper method, or interpolating into raw HTML. It’s available in all views and helpers in Rails since it’s defined in ActionView::Helpers::TagHelper. You might also see it referred to as token_list, which is the original method name.
If you’ve only got a single conditional class, plain ERB is readable enough:
<div class="p-4 <%= 'font-bold' if @important %>">
Though the array form does avoid the awkward whitespace issue when the condition is false:
<%= tag.div class: ["p-4", "font-bold": @important] do %>
html_safe on the result. This bypasses Rails’s built-in XSS protection entirely: any user input in that string goes straight to the browser unescaped.
The good news is you almost never need html_safe. Rails provides three underappreciated tools that handle escaping for you.
…calling html_safe on strings you’ve built by hand:
def status_badge(label, color)
"<span class=\"badge badge-#{color}\">#{label}</span>".html_safe
end
def formatted_address(user)
[user.street, user.city, user.postcode].compact.join("<br>").html_safe
end
def render_comment(comment)
comment.body_html.html_safe
end
…the right tool for each situation.
When you need to build HTML elements, use tag helpers:
def status_badge(label, color)
tag.span(label, class: "badge badge-#{color}")
end
The tag helper escapes the content and attributes automatically. It returns an HTML-safe string without you having to think about it.
When you need to join fragments that mix safe HTML with potentially unsafe text, use safe_join:
def formatted_address(user)
safe_join([user.street, user.city, user.postcode].compact, tag.br)
end
safe_join escapes any unsafe strings in the array and returns an HTML-safe result. It’s Array#join with protection built in.
When you need to accept user-provided HTML but strip dangerous tags, use sanitize:
def render_comment(comment)
sanitize(comment.body_html)
end
sanitize keeps safe tags like <p>, <strong>, and <em> while stripping <script>, event handlers, and other XSS vectors. You can customise the allowed tags and attributes, but beware of straying past the defaults — they are battle-tested and loosening them is a footgun.
Each of these tools lets Rails manage HTML safety for you. You describe what you want — an element, a joined list, sanitised content — and the framework handles the escaping.
html_safe does the opposite. It tells Rails “trust this string, don’t escape it”. That’s a promise you have to keep, and it’s easy to break when the inputs change or a future developer doesn’t realise user data flows through that path. Ask your friendly security consultant or penetration testing organisation why this is a bad idea.
The mental model is simple. Need an HTML element? tag. Joining fragments? safe_join. Accepting rich text? sanitize. If none of those fit, you probably need a partial or a component, not a string.
There are legitimate uses of html_safe. Some gems, like pagy, return pre-built HTML strings that are safe by construction. Calling html_safe on their output is fine because the gem controls the content.
You might also see html_safe on strings that are genuinely static with no user input, like " ".html_safe. That’s harmless, but you can include the actual Unicode character instead — "\u00A0" gives you a non-breaking space without needing html_safe at all. That is ugly as hell though, so it’s your call!
The key question is always: could user input end up in this string? If the answer is yes, or even maybe, reach for tag, safe_join, or sanitize instead.
ENV.fetch calls and credentials.dig lookups throughout the codebase, depending on where each secret lives.
Rails edge — and the upcoming 8.2 — fixes this.
…mixing ENV and credential lookups:
class StripeChargeService
def initialize
@api_key = ENV.fetch("STRIPE_API_KEY")
@webhook_secret = Rails.application.credentials.dig(:stripe, :webhook_secret)
@price_id = ENV.fetch("STRIPE_PRICE_ID") { Rails.application.credentials.dig(:stripe, :price_id) }
end
end
…the combined credentials API:
class StripeChargeService
def initialize
@api_key = Rails.app.creds.require(:stripe, :api_key)
@webhook_secret = Rails.app.creds.require(:stripe, :webhook_secret)
@price_id = Rails.app.creds.require(:stripe, :price_id)
end
end
require raises a KeyError if the key is missing from all backends. For optional values, use option:
Rails.app.creds.option(:appsignal, :push_api_key, default: nil)
# Returns nil if missing — AppSignal just won't report
To keep production secrets separate, run bin/rails credentials:edit --environment production. This creates a separate encrypted file with its own key:
config/credentials.yml.enc ← shared (dev/test)
config/master.key ← decrypts the shared file
config/credentials/production.yml.enc ← production only
config/credentials/production.key ← decrypts production
If production.yml.enc exists, Rails uses it exclusively in production — there’s no inheritance from the shared file, so duplicate any keys you need. To decrypt in production, set RAILS_MASTER_KEY in your hosting provider to the contents of production.key.
Rails.app.creds checks ENV first, then falls back to encrypted credentials. You don’t need to know or care where a value is stored.
Nested keys like :stripe, :api_key map to double-underscored ENV names (STRIPE__API_KEY). A single key like :postmark_api_token checks ENV["POSTMARK_API_TOKEN"].
This means you can move secrets between ENV and encrypted credentials without changing application code. Deploying to a provider that injects secrets via ENV? It just works. Want to move a key into the encrypted file instead? Remove the ENV variable and add it to your credentials. Your code stays the same.
I’ve previously recommended wrapping ENV in a custom Settings object. This built-in approach is better — the same clean interface with the added fallback to encrypted credentials.
This isn’t in a released version of Rails yet — you need Rails edge (main), and it’s expected in Rails 8.2. If you’re on 8.1 or older, a custom Settings wrapper still works well.
You can also create development.yml.enc and test.yml.enc, but I think the shared file plus a production override is clearer — and you shouldn’t be calling real APIs in your test environment anyhow.
Keep separate encryption keys for each environment. You could share one, but a leaked development key shouldn’t expose production secrets.
I originally published this post saying Rails.app.creds had shipped in Rails 8.1. It hasn’t — it’s on Rails main and is expected in 8.2. I’ve been running Rails edge on a couple of projects and assumed this had already been released. Apologies for the confusion, and thanks to everyone who pointed it out.
…accepting Rails’s best guess at a plural:
"criterion".pluralize #=> "criterions"
"matrix".pluralize #=> "matrices" # this one Rails knows!
…inflect.irregular to teach Rails the correct pair:
# config/initializers/inflections.rb
ActiveSupport::Inflector.inflections(:en) do |inflect|
inflect.irregular "criterion", "criteria"
end
Now:
"criterion".pluralize #=> "criteria"
"criteria".singularize #=> "criterion"
Give irregular the singular and plural forms and Rails handles both directions—pluralize and singularize both work correctly.
A Criterion model will look for a criteria table. resources :criteria will route to CriteriaController. Association names, fixtures, and factory names all follow suit.
class Criterion < ApplicationRecord
# table: criteria
end
class Survey < ApplicationRecord
has_many :criteria # works as expected
end
You can declare as many as you need:
ActiveSupport::Inflector.inflections(:en) do |inflect|
inflect.irregular "criterion", "criteria"
inflect.irregular "goose", "geese"
end
Although, unless you’re building some kind of flighted animal tracker, you probably won’t need that second one.
Rails already knows a handful of irregular plurals: person/people, man/men, child/children, sex/sexes, move/moves, and—crucially—zombie/zombies are built in. Rails’s pluralisation rules are regex-based, so the (m)an → (m)en pattern also covers woman/women. But that’s it—words like tooth/teeth, foot/feet, mouse/mice, and goose/geese are not handled by default. Check the default inflections to see what’s already covered.
See the ActiveSupport::Inflector::Inflections documentation for details.
Before adding an irregular inflection, check whether Rails already knows the word. Try it in a console:
"person".pluralize #=> "people" — already works
"axis".pluralize #=> "axes" — already works
If it’s already correct, adding it to your initialiser is just noise.
If the word never appears as a model or resource name, there’s no reason to declare it.
For words that don’t change between singular and plural (like “sheep” or “metadata”), you need inflect.uncountable. For casing issues with acronyms like API or CSV, look at inflect.acronym.
staffs table or a metadatas route if you let it.
…fighting Rails when it pluralises words that shouldn’t change:
"staff".pluralize #=> "staffs"
"metadata".pluralize #=> "metadatas"
"feedback".pluralize #=> "feedbacks"
…inflect.uncountable to tell Rails these words stay the same:
# config/initializers/inflections.rb
ActiveSupport::Inflector.inflections(:en) do |inflect|
inflect.uncountable %w[staff metadata feedback]
end
Now:
"staff".pluralize #=> "staff"
"metadata".pluralize #=> "metadata"
"staff".singularize #=> "staff"
Table names, route helpers, association names, and autoloading all depend on correct inflection. When Rails gets it wrong, you end up with a staffs table or metadatas_path route helpers.
Declaring a word as uncountable fixes this everywhere at once. The Staff model maps to the staff table. resources :staff generates the routes you’d expect.
Words worth declaring uncountable: staff, metadata, feedback, analytics, aircraft, software. You only need to add ones you’re actually using as model or resource names. You can pass a single string or an array.
Rails already handles some common uncountable words—equipment, information, rice, money, species, series, fish, sheep, jeans, and police work out of the box. Check the default inflections to see the full list before adding your own.
See the ActiveSupport::Inflector::Inflections documentation for details.
Uncountable words make associations slightly less intuitive. has_many :staff reads naturally, but Staff.all returning multiple records from a staff table can briefly confuse developers expecting a staffs table.
If the word is domain-specific jargon your team invented, a regular plural might actually be clearer. Reserve uncountable for genuinely uncountable English words, not as a shortcut to avoid a table name you don’t like.
This only affects pluralisation. For casing issues with acronyms like API or CSV, that’s inflect.acronym. For words with non-standard plurals like criterion/criteria, that’s inflect.irregular.