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.
user.rb defines the User class, backed by the users table, managed by UsersController, accessible at the /users/ routes.
Every Rails app generates config/initializers/inflections.rb to let you customise this behaviour. Most developers leave it empty. Then one day you namespace a controller under API and Rails starts generating Api::UsersController instead of API::UsersController.
…accepting the wrong casing in your class names:
# app/controllers/api/users_controller.rb
class Api::UsersController < ApplicationController
end
…inflect.acronym to teach Rails the correct casing:
# config/initializers/inflections.rb
ActiveSupport::Inflector.inflections(:en) do |inflect|
inflect.acronym "API"
end
Now Rails expects API::UsersController. The file path stays lowercase (app/controllers/api/), but the class name uses the acronym:
# app/controllers/api/users_controller.rb
class API::UsersController < ApplicationController
end
The acronym method tells ActiveSupport’s inflector to preserve the casing you specify. It affects camelize, underscore, classify, and titleize—which means it also affects autoloading and URL helpers.
"api".camelize #=> "API"
"API".underscore #=> "api"
"api/users".camelize #=> "API::Users"
Without the acronym declaration, you get Api instead:
"api".camelize #=> "Api"
Unlike irregular plurals and uncountable words, Rails ships with no built-in acronyms—every one you need, you have to declare yourself. Common ones worth adding: API, SMS, CSV, HTML, PDF. You need one call per term:
ActiveSupport::Inflector.inflections(:en) do |inflect|
inflect.acronym "API"
inflect.acronym "SMS"
inflect.acronym "CSV"
end
This also works for mixed-case words like GraphQL or GitHub. inflect.acronym "GraphQL" ensures "graphql".camelize returns "GraphQL" rather than "Graphql".
See the ActiveSupport::Inflector::Inflections documentation for details.
Note that because these changes are in an initializer, you’ll need to restart your Rails server after making changes.
Keep the list short. Every entry changes how camelize, titleize, humanize, and underscore behave for the specified words across your entire app. Only add acronyms you’re actively using—whether in class names, attribute labels, or view helpers.
This only affects casing, not pluralisation. For words with non-standard plurals like criterion/criteria, you’ll want inflect.irregular. For words that don’t pluralise at all, the method to look at is inflect.uncountable.