Category: Ruby 3.0

Rails Encrypted Credentials: The Git Diff Feature You May Have Been Using Without Knowing

If you have been developing Rails applications for years, there’s a good chance you’ve used:

bin/rails credentials:edit

hundreds of times.

You probably know that Rails stores encrypted credentials in:

config/credentials.yml.enc

and keeps the encryption key separately in:

config/master.key

But did you know that Rails can make:

git diff

show the decrypted, human-readable changes to credentials.yml.enc?

I recently discovered this while working on a Rails 8.1.3.1 application and it was one of those:

“I’ve been using Rails every day for years, and I didn’t know Rails could do this!”

moments.

Let’s see how it works.

First: What is credentials.yml.enc?

Rails encrypted credentials allow us to keep secrets such as:

openai:
  api_key: ...

or:

aws:
  access_key_id: ...
  secret_access_key: ...

inside:

config/credentials.yml.enc

The file is encrypted.

The encryption key is stored separately in:

config/master.key

Rails documentation explicitly states that the encrypted credentials file can be stored in version control as long as the master key remains secure. (Ruby on Rails Guides)

So our repository can contain:

config/
├── credentials.yml.enc    ← encrypted, safe to commit
└── master.key             ← secret, NEVER commit

Editing Rails Credentials

Normally we edit credentials with:

bin/rails credentials:edit

Rails decrypts the credentials, opens them in your configured editor, and encrypts them again when you save.

Conceptually:

credentials.yml.enc
        │
        │ decrypt
        ▼
   Plain YAML
        │
        │ edit
        ▼
   Plain YAML
        │
        │ encrypt
        ▼
credentials.yml.enc

The plaintext credentials aren’t saved as a normal file.

But What Happens With git diff?

Here’s the interesting part.

If Git simply compared the encrypted files, we’d get something useless:

- 3d9Jx8...random-encrypted-data...
+ 7kP2mL...different-encrypted-data...

We wouldn’t know:

  • Which credential changed?
  • Was a key added?
  • Was a key removed?
  • Did the API key change?
  • Did somebody accidentally modify something?

This is where Rails’ credentials diff integration becomes useful.

Rails + Git textconv

Rails can configure Git to use a special diff driver:

[diff "rails_credentials"]
    textconv = bin/rails credentials:diff

In my Rails 8.1 application, I found exactly this in:

.git/config

Git therefore doesn’t simply compare the encrypted contents.

Instead:

git diff
    │
    ▼
Git sees credentials.yml.enc
    │
    ▼
rails_credentials diff driver
    │
    ▼
bin/rails credentials:diff
    │
    ▼
Rails decrypts the credentials
    │
    ▼
Git displays a readable diff

Git itself doesn’t understand Rails encryption.

Rails is providing the text conversion command. Git simply knows how to invoke it.

See It Yourself

Suppose our credentials originally contain:

openai:
  api_key: OLD_KEY

We change it to:

openai:
  api_key: NEW_KEY

Now:

git diff

can show a useful diff such as:

+
+openai:
+  api_key: 'sdsdssdsdsdwewewddvcfgfgth'

That’s much more useful than comparing encrypted bytes.

The Experiment That Makes This Obvious

This is what made the behavior click for me.

Run:

git diff -- config/credentials.yml.enc

You get the human-readable credentials diff.

Now bypass Git’s text conversion:

git diff --no-textconv -- config/credentials.yml.enc

Now you see the encrypted content.

Something like:

3d9Jx8...encrypted-data...

That’s the proof.

The file itself is still encrypted.

It’s only the diff representation that’s being transformed.

So What Exactly Does Git Know?

Git doesn’t know anything about:

Rails
credentials
master.key
AES
encryption
decryption

Git knows:

diff driver
textconv

Rails configures:

rails_credentials

and tells Git:

When displaying a diff for this file,
run:
bin/rails credentials:diff

That’s a very nice example of two independent tools cooperating:

             Rails
               │
               │ provides
               ▼
       credentials:diff
               │
               ▼
             Git
               │
               │ uses
               ▼
           textconv

How Does Rails Configure It?

Rails provides:

bin/rails credentials:diff --enroll

This enrolls the project in credentials diffing.

The Git attributes include:

config/credentials/*.yml.enc diff=rails_credentials
config/credentials.yml.enc diff=rails_credentials

Rails then ensures the Git diff driver is configured to use:

bin/rails credentials:diff

Rails’ application generator includes this credentials diff enrollment as part of application setup and Rails 7.0 already contained the credentials diffing implementation. (Gem)

So this isn’t actually an 8.1-only feature.

That’s an important distinction.

Is This New in Rails 8.1?

No – and this is an important correction.

The encrypted credentials diff functionality existed before Rails 8.1.

For example, Rails 7.0 already had the credentials:diff implementation, and Rails 7.2’s application generator also enrolled projects in credentials diffing. (Gem)

Rails has supported decrypted Git diffs for encrypted credentials for several versions and Rails 8.x continues to build on the credentials tooling.

Rails 8.1 does introduce other useful credentials functionality. For example, Rails 8.1 added command-line credential fetching, which can be useful for deployment tooling such as Kamal. (Ruby on Rails Guides)

Does This Make My Secrets Unsafe?

No – provided you protect the master key.

The important distinction is:

Git repository
│
├── credentials.yml.enc
│       ↓
│   encrypted
│
└── master.key
        ↓
     SECRET

The encrypted file can be committed.

The master key should not be committed. Rails’ security guide explicitly recommends keeping the master key safe and out of version control. (Ruby on Rails Guides)

One Thing to Remember

The decrypted content can appear in your local terminal output.

For example:

git diff

could display:

+
+openai:
+  api_key: 'sdsdssdsdsdwewewddvcfgfgth'

So don’t casually share terminal screenshots containing credential diffs.

Also be careful when copying terminal output into:

  • Slack
  • GitHub issues
  • Pull requests
  • screenshots
  • blog posts
  • AI assistants

NOTE: The encryption protects the file stored in Git, but a decrypted diff is plaintext.

Rails Developer Takeaway

There are three different things here:

1. Encrypted file

config/credentials.yml.enc

This is what is actually stored in Git.

2. Encryption key

config/master.key

This decrypts the credentials and must remain secret.

3. Git diff representation

bin/rails credentials:diff

This is what allows us to see meaningful changes locally.

So:

                 GitHub
                   │
                   │ encrypted
                   ▼
       credentials.yml.enc
                   ▲
                   │
             master.key
             stays secret


Local git diff:

credentials.yml.enc
        │
        ▼
credentials:diff
        │
        ▼
decrypted representation
        │
        ▼
human-readable diff

Try This Yourself

If you’re working on a Rails application, check:

git config --show-origin --get-regexp 'diff|textconv|filter'

You may find:

file:.git/config diff.rails_credentials.textconv bin/rails credentials:diff

Then:

git diff --no-textconv -- config/credentials.yml.enc

Compare that with:

git diff -- config/credentials.yml.enc

The difference is a great way to understand what’s really happening.

Quick Reference

# Edit credentials
bin/rails credentials:edit

# Enroll project in credential diffing
bin/rails credentials:diff --enroll

# Normal readable diff
git diff

# Show the actual encrypted file diff
git diff --no-textconv -- config/credentials.yml.enc

# Inspect Git's configuration
git config --show-origin --get-regexp 'diff|textconv|filter'

# Check Git attributes
git check-attr diff -- config/credentials.yml.enc

Security rule:

 Y config/credentials.yml.enc → commit it
 X config/master.key          → NEVER commit it

Rails’ official security guide confirms that encrypted credentials can be stored in version control while the master key must remain protected. (Ruby on Rails Guides)

📚 References

Happy Coding!

Ruby’s Mysterious Symbols: The Syntax Every Ruby Developer Should Truly Understand

Ruby is famous for making code expressive.

But that expressiveness comes with a side effect: Ruby contains quite a few symbols and syntax constructs that can look almost cryptic – even to experienced developers coming from other languages.

Consider this:

message = <<~TEXT
  Hello #{user.name},

  Your order has been shipped.

  Thanks!
TEXT

What exactly does <<~TEXT mean?

Or:

users.filter_map { _1.email if _1.active? }

What is _1?

Or:

case response
in { status: 200, body: String => body }
  puts body
end

Why does Ruby allow String =>>>> body inside a pattern?

These aren’t random pieces of syntax. They are examples of Ruby’s philosophy: make common programming operations concise without sacrificing readability.

This article explores some of Ruby 3.4’s most interesting “mysterious” syntax and more importantly explains what each construct means, why it exists, and when a senior developer should use it – or avoid it.

1. <<~ – The Squiggly Heredoc

Let’s start with one of the most useful Ruby syntax features.

message = <<~TEXT
  Hello World
    This is Ruby
  Goodbye
TEXT

The <<~ syntax is called a squiggly heredoc.

What is a heredoc?

A heredoc allows you to define a multiline string:

message = <<TEXT
Hello
World
TEXT

Ruby keeps the newlines inside the string.

The problem is indentation.

In real Ruby code, especially Rails applications, multiline strings are usually nested inside methods, classes, conditionals, etc.

Without squiggly heredoc:

def email_body
  <<TEXT
Hello,
Welcome to our application.
Thank you.
TEXT
end

The heredoc terminator often needs awkward indentation.

<<~ solves that

def email_body
  <<~TEXT
    Hello,
    Welcome to our application.
    Thank you.
  TEXT
end

Ruby removes the common leading indentation.

Conceptually:

source indentation
        ↓
    Hello
    Welcome
    Thank you

becomes:

Hello
Welcome
Thank you

Why is this useful in Rails?

Extremely useful for SQL:

sql = <<~SQL
  SELECT users.*
  FROM users
  INNER JOIN orders ON orders.user_id = users.id
  WHERE users.active = TRUE
SQL

Or HTML:

html = <<~HTML
  <div class="user">
    <h2>#{user.name}</h2>
  </div>
HTML

Or shell commands:

command = <<~BASH
  echo "Starting deployment"
  bundle exec rails db:migrate
  echo "Deployment complete"
BASH

The senior-level takeaway

<<~ isn’t merely a formatting convenience.

It lets the Ruby source code remain properly indented without contaminating the resulting string with that indentation.

2. <<- vs <<~ vs <<

Ruby actually has several heredoc variants.

<<TEXT
...
TEXT

Strict terminator placement.

<<-TEXT
...
  TEXT

Allows the terminator to be indented.

<<~TEXT
...
  TEXT

Allows indentation and removes common indentation from the resulting string.

So in modern Ruby code, <<~ is generally the most readable choice for indented multiline strings.

Read more here: https://railsdrop.com/ruby-more-about-ruby-hearedoc-questions-and-answers/

3. %i[...] – Creating Arrays of Symbols

This:

%i[admin editor viewer]

creates:

[:admin, :editor, :viewer]

Similarly:

%w[admin editor viewer]

creates:

["admin", "editor", "viewer"]

The % syntax is Ruby’s percent literal syntax.

Common forms

%w[one two three]     # strings
%i[one two three]     # symbols
%W[hello #{name}]     # interpolated strings
%I[hello #{name}]     # interpolated symbols

This:

%i[read write delete]

is often cleaner than:

[:read, :write, :delete]

Especially when the list becomes long:

ALLOWED_ROLES = %i[
  admin
  manager
  editor
  viewer
].freeze

Read more here: https://railsdrop.com/ruby-more-about-rubys-percent-literal-syntax/

4. &. – The Safe Navigation Operator

One of the most recognizable Ruby operators:

user&.profile&.address&.city

It means:

Call the next method only if the receiver isn’t nil.

Instead of:

if user
  if user.profile
    if user.profile.address
      user.profile.address.city
    end
  end
end

Ruby lets you write:

user&.profile&.address&.city

But don’t blindly use it

This is an important senior-level distinction.

If the business logic says:

A user must have a profile.

then this:

user&.profile&.address

may hide a data integrity problem.

Sometimes you actually want:

user.profile.address

so that invalid state fails loudly.

Good use

Optional data:

current_user&.avatar&.url

Potentially bad use

Required relationships:

order&.customer&.account&.billing_address

If all those associations are supposed to exist, safe navigation may simply hide broken application state.

Use &. when nil is genuinely expected – not merely because it prevents exceptions.

5. &:method – Symbol-to-Proc Conversion

You’ve probably seen:

users.map(&:email)

It looks strange initially.

It’s effectively shorthand for:

users.map { |user| user.email }

Ruby converts:

:email

into a callable block using &.

So:

users.map(&:email)

is approximately:

users.map { |user| user.email }

Another example

numbers.select(&:even?)

is equivalent to:

numbers.select { |number| number.even? }

Important distinction

These are not the same:

users.map(:email)

and:

users.map(&:email)

The & tells Ruby:

Convert this object into a Proc and pass it as the block.

6. _1, _2, _3 – Numbered Parameters

Modern Ruby provides implicit block parameters.

Instead of:

users.map { |user| user.email }

you can write:

users.map { _1.email }

_1 means:

The first block argument.

Similarly:

array.map { |value, index| ... }

can conceptually be accessed using:

_1
_2

For example:

[10, 20, 30].map { _1 * 2 }

produces:

[20, 40, 60]

Where it works well

Small transformations:

users.map { _1.email }
orders.select { _1.total >> 1000 }
names.map { _1.upcase }

Where it becomes bad

Complex blocks:

users.map { _1.orders.select { _2.paid? }.map { _1.total } }

At this point, explicit names are much easier to understand.

users.map do |user|
  user.orders.select { |order| order.paid? }
             .map { |order| order.total }
end

Senior Ruby code optimizes for comprehension, not character count.

7. ... – The Argument Forwarding Operator

Ruby’s ... is particularly useful when wrapping methods.

Consider:

def log(*args, **kwargs, &block)
  puts "Calling method"
  super
end

Modern Ruby allows forwarding arguments directly:

def log(...)
  puts "Calling method"
  super
end

The ... means:

Forward all positional arguments, keyword arguments, and the block.

For example:

def instrument(...)
  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)

  result = super

  duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
  puts "Took #{duration}s"

  result
end

This is particularly valuable for decorators, wrappers, instrumentation and delegation.

8. * – The Splat Operator

Ruby’s * has several important meanings.

Array expansion

numbers = [1, 2, 3]
puts(*numbers)

is effectively:

puts(1, 2, 3)

Collecting arguments

def sum(*numbers)
  numbers.sum
end

Now:

sum(1, 2, 3, 4)

works because numbers becomes:

[1, 2, 3, 4]

Array destructuring

first, *middle, last = [1, 2, 3, 4, 5]

results in:

first  # 1
middle # [2, 3, 4]
last   # 5

This makes * one of Ruby’s most versatile operators.

9. ** – Keyword Argument Splat

The double splat is the keyword-argument equivalent.

options = {
  timeout: 10,
  retries: 3
}
client.call(**options)

This expands the hash into keyword arguments.

And:

def connect(**options)
  options
end

collects arbitrary keyword arguments.

connect(timeout: 10, retries: 3)

gives:

{
  timeout: 10,
  retries: 3
}

This becomes particularly important when building APIs, service objects and forwarding methods in modern Ruby.

10. =>>>> Is More Than Hash Syntax

Most Ruby developers first encounter:

{ name: "Abhilash" }

But =>>>> has several meanings.

Hash rockets

{ "name" =>> "Abhilash" }

Pattern matching

Ruby pattern matching also uses =>>>>.

case response
in { status: 200, body: String =>> body }
  puts body
end

Here:

String =>> body

means roughly:

Match a String and bind the matched value to body.

This is part of Ruby’s increasingly powerful pattern matching system.

11. Ruby Pattern Matching with in

Ruby’s case statement can do structural matching.

case user
in { name:, role: "admin" }
  puts "#{name} is an admin"
else
  puts "Not an admin"
end

The pattern:

{ name:, role: "admin" }

means:

  • the object should have a name
  • role must equal "admin"
  • bind the name value to the local variable name

This is considerably more powerful than a traditional case comparison.

Array patterns

case coordinates
in [x, y]
  puts "Point: #{x}, #{y}"
end

Why senior developers should care

Pattern matching becomes useful when processing:

  • API responses
  • parsed JSON
  • AST structures
  • event payloads
  • command results
  • structured domain objects

Instead of writing nested conditionals, you can express the expected structure directly.

12. in vs if

Traditional Ruby:

if response.is_a?(Hash) &&
   response[:status] == 200
  ...
end

Pattern matching:

case response
in { status: 200 }
  ...
end

The second version communicates the shape of the data rather than manually checking each property.

That is the deeper value of pattern matching.

13. | – Destructuring and Pattern Alternatives

Ruby’s | isn’t only the bitwise OR operator.

In pattern matching:

case value
in 1 | 2 | 3
  puts "Small number"
end

means:

Match 1 OR 2 OR 3.

This makes pattern matching expressive:

case status
in 200 | 201 | 204
  puts "Success"
in 400 | 401 | 403
  puts "Client error"
end

14. =>>>> in Pattern Matching Can Bind Values

Consider:

case result
in Integer =>> value
  puts value
end

This performs a type match and binds the value.

For example:

result = 42

matches:

Integer =>> value

and:

value
# =>> 42

This becomes powerful when patterns become more complex.

15. ... in Ranges

Ruby’s range syntax has two forms:

1..10

and:

1...10

The difference:

1..10

includes 10.

1...10

excludes 10.

Therefore:

(1..10).to_a

gives:

[1,2,3,4,5,6,7,8,9,10]

while:

(1...10).to_a

gives:

[1,2,3,4,5,6,7,8,9]

This is especially useful for array slicing:

numbers[0...3]

returns the first three elements.

16. .. Can Be Used in Conditions

Ruby has another interesting use of ranges.

case number
when 1..10
  puts "Small"
when 11..100
  puts "Medium"
end

This is one reason Ruby ranges are more than simply “start/end values.”

17. =>>>> vs : in Hashes

These are both valid:

{ name: "Ruby" }

and:

{ :name =>> "Ruby" }

But modern Ruby generally prefers:

{ name: "Ruby" }

The hash rocket remains useful when keys aren’t symbols:

{
  "Content-Type" =>> "application/json",
  "X-Request-ID" =>> request_id
}

This is a good example of Ruby syntax evolving toward readability while retaining backwards compatibility.

18. ? and ! Are Part of Ruby’s API Design

Ruby method names can end with ?:

user.active?

This convention means:

The method answers a yes/no question.

Examples:

empty?
nil?
valid?
persisted?
published?

The ! convention usually communicates:

This method performs a more dangerous, mutating, or exceptional version of an operation.

Examples:

save!
update!
destroy!
compact!

But an important senior-level detail:

Ruby does not enforce the semantic meaning of !.

You can technically write:

def hello!
  "hello"
end

The meaning is a convention established by Ruby developers.

19. :: – Constant Lookup and Method Calls

Most developers know:

User::NAME

But :: can also invoke methods:

object::method

although the . form is overwhelmingly more idiomatic for method calls.

The primary modern use is constant/module navigation:

ActiveRecord::Base
Rails::Application
JSON::ParserError

It communicates namespace traversal.

20. @, @@ and $

Ruby has several variable scopes represented visually.

Local variable

name = "Ruby"

Instance variable

@name = "Ruby"

belongs to an object instance.

Class variable

@@name = "Ruby"

is shared across a class hierarchy.

Global variable

$name = "Ruby"

is globally accessible.

From a senior Rails perspective:

Prefer local and instance variables. Be extremely cautious with class variables and globals.

For example, Rails applications rarely need:

@@configuration

or:

$global_state

because they introduce difficult-to-control shared state.

21. ||= – Lazy Initialization

This is everywhere in Ruby:

@client ||= Client.new

It means roughly:

@client = @client || Client.new

If @client is already truthy, Ruby keeps it.

Otherwise, it creates the object.

This is commonly used for memoization:

def expensive_service
  @expensive_service ||= ExpensiveService.new
end

But remember

||= checks truthiness, not whether the variable has ever been assigned.

So if:

@value = false

then:

@value ||= calculate_value

will call calculate_value.

That distinction matters when memoizing boolean values.

22. &&= and ||= Are Assignment Operators

Ruby also supports:

value &&= other

and:

value ||= other

For example:

user.active &&= user.verified?

means approximately:

user.active = user.active && user.verified?

These are concise, but they should be used only when the resulting expression remains obvious.

23. +=, -=, *=, /=

Ruby supports compound assignment:

counter += 1

Conceptually:

counter = counter + 1

For object attributes:

user.score += 10

is conceptually equivalent to:

user.score = user.score + 10

Ruby’s expressive assignment syntax is one of the reasons its code can remain compact without introducing a separate statement syntax.

24. defined? – Ask Ruby Whether Something Exists

Ruby provides:

defined?(variable)

For example:

defined?(@user)

may return:

"instance-variable"

You can also inspect constants:

defined?(Rails)

This can be useful for metaprogramming and conditional loading, although it should not be used as a substitute for proper application design.

25. respond_to? – Duck Typing in Action

Ruby’s duck typing philosophy often appears as:

object.respond_to?(:call)

Instead of asking:

object.is_a?(SomeSpecificClass)

you ask:

Can this object perform the operation I need?

For example:

if logger.respond_to?(:info)
  logger.info("Processing started")
end

This is particularly useful when designing flexible Ruby APIs.

26. method(:foo) – Turn a Method into an Object

Ruby treats methods as objects through Method:

method = user.method(:email)

Then:

method.call

invokes it.

This is useful in metaprogramming and dynamic dispatch.

For example:

operation = object.method(:calculate)
operation.call

Ruby’s object model makes this possible without requiring a separate function-pointer concept.

27. public_send vs send

Ruby allows dynamic method invocation:

user.send(:email)

But send can invoke private methods.

For user-controlled or externally supplied method names, this can be dangerous.

Prefer:

user.public_send(:email)

when you intentionally want to restrict invocation to public methods.

This distinction becomes important when building generic service layers or DSLs.

28. then / yield_self – Pipeline-Style Ruby

Ruby provides:

object.then do |value|
  ...
end

For example:

result =
  User.new
      .then { |user| user.save! }
      .then { |user| user.email }

then passes the receiver into the block and returns the block’s result.

It can be useful when constructing transformations without introducing temporary variables.

But don’t turn everything into a pipeline merely because Ruby allows it.

29. _ – The Intentionally Ignored Variable

You’ll frequently see:

users.each do |user, _index|
  puts user.name
end

The _ communicates:

This value exists, but I intentionally don’t care about it.

Ruby also allows:

_ = expensive_result

although explicit naming is generally preferable unless you’re intentionally ignoring something.

30. Endless Method Definitions

Ruby allows:

def full_name = "#{first_name} #{last_name}"

instead of:

def full_name
  "#{first_name} #{last_name}"
end

This is called an endless method definition.

It’s excellent for very small methods:

def active? = status == "active"
def total = price * quantity

But don’t use it for complex logic.

This:

def process = validate && save && notify && publish

may be syntactically elegant but is much harder to maintain.

31. =>>>> – Rightward Assignment

Modern Ruby also supports rightward assignment:

value =>> variable

For example:

"hello" =>> message

Now:

message
# =>> "hello"

This becomes particularly interesting with pattern matching:

response =>> { status:, body: }

It allows destructuring and binding in a visually different direction.

The feature is useful, but like many Ruby syntactic conveniences, it should be used when it improves readability—not simply because it is available.

32. The Bigger Picture: Ruby Syntax Is a Language of Intent

After seeing all these operators, it is tempting to memorize them as a collection of Ruby tricks.

That would miss the important point.

Ruby’s syntax frequently tries to encode intent.

Compare:

users.map { |user| user.email }

with:

users.map(&:email)

The second says:

Transform each user using its email method.

Compare:

if user && user.profile && user.profile.avatar

with:

user&.profile&.avatar

The second says:

Traverse this optional object graph.

Compare:

message = <<~TEXT
  ...
TEXT

with manually concatenating strings.

The first says:

This is a multiline piece of text.

And:

case response
in { status: 200, body: String =>> body }

says:

I expect this particular structure.

That is the real power behind Ruby’s “mysterious symbols.”

33. Senior Ruby Developer Rule: Don’t Optimize for Cleverness

A senior Ruby developer should know all of these constructs.

But knowing them doesn’t mean using them everywhere.

For example:

users.map { _1.orders.select(&:paid?).sum(&:total) }

is valid Ruby.

But:

users.map do |user|
  user.orders
      .select(&:paid?)
      .sum(&:total)
end

may be more readable.

And sometimes the best version is:

users.map do |user|
  paid_orders = user.orders.select(&:paid?)
  paid_orders.sum(&:total)
end

Ruby gives you enormous freedom.

Good Ruby isn’t the shortest Ruby.

Good Ruby is code where another experienced developer can understand the intent quickly.

Final Takeaway

Ruby 3.4 contains a rich collection of compact syntax:

<<~TEXT       # squiggly heredoc
%i[...]       # symbol array
%w[...]       # string array
&.            # safe navigation
&:method      # symbol-to-proc
_1            # numbered parameter
*args         # positional splat
**kwargs      # keyword splat
...           # argument forwarding
1...10        # exclusive range
x ||= value   # conditional assignment
def foo = ... # endless method
case x; in... # pattern matching
=>            # hash rocket / pattern binding / rightward assignment

These aren’t merely Ruby “shortcuts.”

They represent Ruby’s broader design philosophy:

Make the code express what the programmer means, while keeping the syntax close to natural language.

For a senior Ruby/Rails developer, the goal isn’t to remember every symbol.

The goal is to recognize when a piece of Ruby syntax improves the expression of intent – and when it merely makes the code clever.

That distinction is what separates knowing Ruby syntax from writing idiomatic, maintainable Ruby.

Happy Rubying!~

Ruby’s Triple-Dot Operator: Argument Forwarding from 2.7 to 4.0

If you’ve ever written a method whose entire job is to pass its arguments straight through to another method, you’ve felt this pain:

class Repository
  def find(id, *args, **kwargs, &block)
    connection.find(id, *args, **kwargs, &block)
  end
end

Three parameter types, three splat operators, zero information conveyed. Ruby 2.7 solved this with a single token: ...

The problem it solves

... is Ruby’s argument forwarding shorthand. It captures everything passed to a method – positional args, keyword args, and a block – and lets you re-throw it at another method without naming a single one of them.

def find(...)
  connection.find(...)
end

Same behavior as the splat version above, minus the noise. It behaves like a bare super with parens: “take what I got, send it onward, unchanged.”

Ruby 2.7: the baseline

... shipped in Ruby 2.7 (Dec 2019) with one hard restriction: it has to be the only parameter in the definition, and the only argument in the call. You can’t mix it with named params, and you can’t inspect or transform the forwarded values.

def log_call(...)
  puts "calling..."
  perform(...)
end
def perform(*args, **kwargs, &block)
  block.call(args, kwargs)
end
log_call(1, 2, k: 3) { |a, k| p [a, k] }
# => [[1, 2], {k: 3}]

Clean, but rigid – useful only for pure pass-through wrappers (logging, memoization, decorators).

Ruby 3.0: leading arguments

Ruby 3.0 (Dec 2020) lifted the “must be alone” rule. You can now peel off one or more leading positional arguments before the ..., in both the definition and the call site:

def method_missing(name, ...)
  send(:"do_#{name}", ...)
end

This is the textbook use case – method_missing needs the method name for dispatch logic, but everything else should flow through untouched:

def transform(a, ...)
  process(a, ...)
end
def process(a, *args, **kwargs, &block)

[a, args, kwargs]

end transform(1) # => [1, [], {}] transform(1, 2, k: 3) # => [1, [2], {k: 3}]

This turned ... from a niche decorator trick into something you’d actually reach for in delegation-heavy code – Rails controllers forwarding to services, DSL builders, proxy objects.

Ruby 3.1: anonymous block forwarding

Ruby 3.1 (Dec 2021) split the block piece out on its own. If you only need to forward the block and want the positional/keyword args handled explicitly, use a bare &:

def perform(&)
  execute(&)
end

No name required on either side. This composes with regular named params:

def retry_with(times:, &)
  times.times { execute(&) }
end

Ruby 3.2: anonymous splat and double-splat

Ruby 3.2 (Dec 2022) completed the set, adding anonymous * and ** forwarding to match the anonymous & from 3.1:

def split_arguments(*, **)
  pass_positional(*)   # forwards only positional args
  pass_keywords(**)    # forwards only keyword args
end
split_arguments(1, 2, a: 3, b: 4)
# pass_positional(1, 2)
# pass_keywords(a: 3, b: 4)

This matters when a method needs to route positional and keyword args to different destinations – ... can’t do that, since it moves as one atomic bundle.

Ruby 3.3 / 3.4 / 4.0: no new syntax, better tooling

No further language changes landed for ... itself through 3.3, 3.4, or Ruby 4.0 (released Dec 2025). Two things worth knowing if you’re on current Ruby:

  • RBS gained first-class support for forwarding parameters in method type signatures in 2026 (def request: (...) -> Response), so type-checked codebases no longer have to erase forwarded signatures to untyped.
  • Ruby 4.0 changed splat semantics slightly: *nil no longer calls nil.to_a, and **nil no longer calls nil.to_hash. It’s not a ...-specific change, but if you forward keyword args that might legitimately be nil (e.g., **opts where opts defaults to nil), check this – it’ll raise instead of silently treating nil as {}.

Version cheat sheet

VersionReleasedAdds
2.7Dec 2019... – forwards all args + block, must be the sole parameter
3.0Dec 2020Leading arguments alongside ...: def foo(a, ...)
3.1Dec 2021Anonymous block forwarding: def foo(&); bar(&); end
3.2Dec 2022Anonymous splat/double-splat: def foo(*, **); bar(*); baz(**); end
3.3 – 4.02023 – 2025No new ... syntax; RBS forwarding types; *nil/**nil semantics changed in 4.0

If you’re targeting older runtimes: 2.7 and 3.0 are long past EOL, 3.1 EOL’d in 2025, and only 3.2+ receives active support as of this writing. Practically, any codebase forwarding arguments today should assume 3.2+ and use whichever granularity (..., &, *, **) fits the delegation.

Where I’d push back on using it

... is DRY, but it’s opaque. def foo(...) tells a reader nothing about the method’s actual contract – they have to chase the call chain to find out what foo accepts. For a pure pass-through utility (logging wrapper, method_missing dispatch, a thin repository shim), that opacity is the whole point and it’s the right call. For a public API boundary – a service object’s entry point, a gem’s documented interface – I’d argue explicit named parameters (or at minimum RBS/Sorbet signatures) win, because the signature is the documentation, and ... erases it at the exact place callers look first.

A second edge case: you can’t currently pass extra trailing arguments after a forwarded ... in a call (bar(extra, ...) is still restricted) – only leading ones. If you need to inject an argument after the forwarded set, you’re back to explicit *args, **kwargs, &block.

Rule of thumb: reach for ... (or &/*/**) at internal delegation boundaries where the wrapper genuinely adds no new arguments of its own. Keep explicit signatures at any boundary another engineer – or a type checker – needs to reason about without reading the delegate.

Happy Rubying!

Integrate AI with Rails: Day 8 – Production Hardening of the AI Integration, add AI Observablility

We have enough practical experience with SSE right now. We don’t need to perfect the transport layer, lets move on to improve our production error handling architecture.

Step 12 – Production Hardening of the AI Integration

We’ll cover this as one compact step:

LLM request
 ├── timeout
 ├── rate limit
 ├── provider error
 ├── invalid response
 ├── logging
 └── token/cost tracking

12.1 Add a custom AI error

Create:

app/services/ai/error.rb
class Ai::Error < StandardError
end

class Ai::ProviderError < Ai::Error
end

class Ai::RateLimitError < Ai::Error
end

class Ai::TimeoutError < Ai::Error
end

This gives our application its own error vocabulary instead of exposing SDK/provider exceptions everywhere.

12.2 Wrap the provider call

In Ai::Client, wrap the API call.

Conceptually:

def chat(messages:)
  response = @client.chat.completions.create(
    model: MODEL,
    messages: messages
  )

  {
    content: response.choices.first.message.content,
    model: response.model,
    input_tokens: response.usage&.prompt_tokens,
    output_tokens: response.usage&.completion_tokens
  }
rescue Faraday::TooManyRequestsError => e
  raise Ai::RateLimitError, e.message
rescue Faraday::TimeoutError => e
  raise Ai::TimeoutError, e.message
rescue Faraday::Error => e
  raise Ai::ProviderError, e.message
end

The exact exception classes can depend on the SDK/version, so inspect the exception raised by your installed openai gem rather than blindly copying provider-specific classes.

The important architecture is:

OpenRouter/SDK error
        ↓
Ai::Client
        ↓
Ai::RateLimitError
Ai::TimeoutError
Ai::ProviderError
        ↓
Rails application

Your controllers don’t need to know OpenRouter’s exception hierarchy.

12.3 Add timeout thinking

Never allow an AI request to hang indefinitely.

A production system should have:

connection timeout
read/request timeout

and then either:

retry

or:

fail gracefully

depending on the failure.

A key int. answer:

Retry transient failures such as timeouts and 429s with bounded exponential backoff, but don’t blindly retry all errors.

12.4 Token tracking

We’re already storing:

input_tokens
output_tokens

in messages.

That gives us an important operational capability:

conversation.messages.sum(:input_tokens)

and:

conversation.messages.sum(:output_tokens)

Now we can answer:

How many tokens did this conversation consume?

Later we can add pricing:

input tokens  × input price
+
output tokens × output price
=
estimated cost

Don’t hard-code provider pricing into the model. Pricing changes.

12.5 Add request timing

For a production AI application, latency is valuable.

In Ai::Client:

started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)

response = ...

latency_ms =
  ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round

Then eventually store:

latency_ms

on the message or in a separate AI usage/event table.

This allows:

model
tokens
latency
errors

to be correlated.

12.6 Don’t log prompts blindly

Avoid:

Rails.logger.info(params)

for AI endpoints.

User prompts may contain:

  • PII
  • secrets
  • customer information
  • proprietary company data

Log metadata instead:

conversation_id
model
latency
token counts
error type

rather than dumping the entire conversation into logs.

12.7 Add application-level rate limiting

An expensive AI endpoint should never be unrestricted.

Conceptually:

User
 ↓
Rate limit
 ↓
AI endpoint
 ↓
LLM

For example:

10 requests/minute/user

The exact limit depends on your application.

This protects:

  • cost
  • provider quotas
  • abuse
  • system capacity

12.8 What about retries?

Use something like:

Timeout      → retry
429          → retry with backoff
5xx          → retry with backoff
400          → don't retry
401          → don't retry
invalid input → don't retry

The exact mapping depends on the provider.

A useful int. phrase:

“I distinguish transient failures from permanent failures. For transient failures, I use a bounded number of retries with exponential (delay: 1,2,4,8,16 seconds) backoff.”

Step 13: Add AI Observability with admin Dashboard

Instead of merely saying we support observability, let’s build an actual AI Admin / Observability dashboard into the app. This will make the project much stronger because you can demonstrate that we thought beyond “call the LLM.”

We will track:

AI Request
├── provider
├── model
├── operation
├── status
├── conversation
├── message
├── input tokens
├── output tokens
├── estimated cost
├── latency
├── started/completed timestamps
├── retry count
├── HTTP status
├── error class
├── error message
├── request ID
├── streamed?
└── metadata

And the admin UI will have:

/admin/ai_requests

AI Observability
-------------------------------------------------
Total Requests       127
Successful           119
Failed                 8
Total Input Tokens  45,230
Total Output Tokens 18,921
Avg Latency          2.34 sec
Estimated Cost       $0.00 / N/A
-------------------------------------------------

Recent AI Requests
-------------------------------------------------
Time | Model | Status | Tokens | Latency | Error
-------------------------------------------------
...

Then clicking a request gives the complete details.

Step 12A – Create AiRequest

We’ll call the model AiRequest.

This is not the AI message itself.

Remember:

Message
    ↓
What the user/assistant said

AiRequest
    ↓
What happened while talking to the LLM

That distinction is important.

1. Generate the model

Run:

bin/rails g model AiRequest \
  conversation:references \
  message:references \
  provider:string \
  model:string \
  operation:string \
  status:string \
  input_tokens:integer \
  output_tokens:integer \
  estimated_cost:decimal \
  latency_ms:integer \
  retry_count:integer \
  http_status:integer \
  request_id:string \
  error_class:string \
  error_message:text \
  started_at:datetime \
  completed_at:datetime \
  streamed:boolean \
  metadata:jsonb

You can also use one line:

bin/rails g model AiRequest conversation:references message:references provider:string model:string operation:string status:string input_tokens:integer output_tokens:integer estimated_cost:decimal latency_ms:integer retry_count:integer http_status:integer request_id:string error_class:string error_message:text started_at:datetime completed_at:datetime streamed:boolean metadata:jsonb

Step 12B – Migration

Open the generated migration.

Change it to:

class CreateAiRequests < ActiveRecord::Migration[8.1]
  def change
    create_table :ai_requests do |t|
      t.references :conversation, null: true, foreign_key: true
      t.references :message, null: true, foreign_key: true

      t.string :provider, null: false
      t.string :model, null: false
      t.string :operation, null: false
      t.string :status, null: false

      t.integer :input_tokens
      t.integer :output_tokens

      t.decimal :estimated_cost, precision: 12, scale: 8

      t.integer :latency_ms
      t.integer :retry_count, null: false, default: 0
      t.integer :http_status

      t.string :request_id

      t.string :error_class
      t.text :error_message

      t.datetime :started_at
      t.datetime :completed_at

      t.boolean :streamed, null: false, default: false

      t.jsonb :metadata, null: false, default: {}

      t.timestamps
    end

    add_index :ai_requests, :status
    add_index :ai_requests, :provider
    add_index :ai_requests, :model
    add_index :ai_requests, :created_at
    add_index :ai_requests, :request_id, unique: true
  end
end

Why are conversation and message nullable?

Because not every AI operation has to belong to a chat message.

Later we might have:

AI embedding request
AI summarization
AI classification
AI agent tool call

So:

conversation_id = NULL
message_id = NULL

can still be valid.

Step 12C – Run migration

bin/rails db:migrate

Then verify:

bin/rails dbconsole
\d ai_requests

Step 12D – Create the model

Open:

app/models/ai_request.rb

Use:

class AiRequest < ApplicationRecord
  belongs_to :conversation, optional: true
  belongs_to :message, optional: true

  enum :status, {
    pending: "pending",
    success: "success",
    failed: "failed",
    rate_limited: "rate_limited",
    timeout: "timeout"
  }, validate: true

  validates :provider, :model, :operation, :status, presence: true

  scope :recent, -> { order(created_at: :desc) }
  scope :successful, -> { where(status: :success) }
  scope :failed_requests, -> { where.not(status: :success) }

  def duration_seconds
    return unless latency_ms

    latency_ms / 1000.0
  end

  def total_tokens
    input_tokens.to_i + output_tokens.to_i
  end
end

Step 12E – Add reverse associations

Open:

app/models/conversation.rb

Add:

has_many :ai_requests, dependent: :nullify

So:

class Conversation < ApplicationRecord
  has_many :messages, dependent: :destroy
  has_many :ai_requests, dependent: :nullify
end

And in:

app/models/message.rb

add:

has_many :ai_requests, dependent: :nullify

So:

class Message < ApplicationRecord
  belongs_to :conversation

  has_many :ai_requests, dependent: :nullify

  enum :role, {
    user: "user",
    assistant: "assistant",
    system: "system"
  }, validate: true
end

Step 12F – Why AiRequest instead of putting everything in Message?

This is an important architectural decision.

A message answers:

What was said?

An AI request answers:

What happened while generating it?

For example:

Message
--------------------
role: assistant
content: "Ruby is..."

while:

AiRequest
--------------------
provider: openrouter
model: ...
status: success
input_tokens: 240
output_tokens: 120
latency_ms: 1840
retry_count: 0
http_status: 200

This separation is much cleaner.

Step 12G – Generate the Admin Controller

Run:

bin/rails g controller Admin::AiRequests index show

This creates:

app/controllers/admin/ai_requests_controller.rb

app/views/admin/ai_requests/index.html.erb
app/views/admin/ai_requests/show.html.erb

Step 12H – Admin routes

Open:

config/routes.rb

Add:

namespace :admin do
  resources :ai_requests, only: %i[index show]
end

So your routes become something like:

Rails.application.routes.draw do
  resources :conversations, only: [:create, :show] do
    resources :messages, only: [:create]
  end

  namespace :admin do
    resources :ai_requests, only: %i[index show]
  end

  root "conversations#new"
end

Check:

bin/rails routes | grep ai_requests

You should get:

/admin/ai_requests
/admin/ai_requests/:id

Step 12I – Admin Controller

Open:

app/controllers/admin/ai_requests_controller.rb

Use:

class Admin::AiRequestsController < ApplicationController
  before_action :authenticate_admin!

  def index
    @ai_requests = AiRequest
      .includes(:conversation, :message)
      .recent
      .limit(100)

    @total_requests = AiRequest.count

    @successful_requests =
      AiRequest.successful.count

    @failed_requests =
      AiRequest.failed_requests.count

    @total_input_tokens =
      AiRequest.sum(:input_tokens)

    @total_output_tokens =
      AiRequest.sum(:output_tokens)

    @average_latency =
      AiRequest.where.not(latency_ms: nil).average(:latency_ms)

    @estimated_cost =
      AiRequest.sum(:estimated_cost)
  end

  def show
    @ai_request = AiRequest.includes(
      :conversation,
      :message
    ).find(params[:id])
  end

  private

  def authenticate_admin!
    authenticate_or_request_with_http_basic("AI Admin") do |username, password|
      username == Rails.application.credentials.dig(:admin, :username) &&
        password == Rails.application.credentials.dig(:admin, :password)
    end
  end
end

This means the admin dashboard isn’t publicly accessible.

Step 12J – Configure Admin Credentials

Run:

bin/rails credentials:edit

Add:

admin:
  username: admin
  password: CHANGE_ME

Obviously use a proper password locally.

Then:

bin/rails c

Verify:

Rails.application.credentials.dig(:admin, :username)

and:

Rails.application.credentials.dig(:admin, :password)

Step 12K – Admin Index View

Open:

app/views/admin/ai_requests/index.html.erb

Use:

<h1>AI Observability</h1>

<section>
  <h2>Summary</h2>

  <dl>
    <dt>Total Requests</dt>
    <dd><%= @total_requests %></dd>

    <dt>Successful</dt>
    <dd><%= @successful_requests %></dd>

    <dt>Failed</dt>
    <dd><%= @failed_requests %></dd>

    <dt>Input Tokens</dt>
    <dd><%= number_with_delimiter(@total_input_tokens) %></dd>

    <dt>Output Tokens</dt>
    <dd><%= number_with_delimiter(@total_output_tokens) %></dd>

    <dt>Average Latency</dt>
    <dd>
      <%= @average_latency ? "#{@average_latency.round} ms" : "N/A" %>
    </dd>

    <dt>Estimated Cost</dt>
    <dd>
      <%= @estimated_cost ? number_to_currency(@estimated_cost) : "N/A" %>
    </dd>
  </dl>
</section>

<hr>

<h2>Recent Requests</h2>

<table>
  <thead>
    <tr>
      <th>ID</th>
      <th>Time</th>
      <th>Provider</th>
      <th>Model</th>
      <th>Operation</th>
      <th>Status</th>
      <th>Tokens</th>
      <th>Latency</th>
      <th>Retries</th>
      <th>HTTP</th>
    </tr>
  </thead>

  <tbody>
    <% @ai_requests.each do |request| %>
      <tr>
        <td>
          <%= link_to request.id,
              admin_ai_request_path(request) %>
        </td>

        <td>
          <%= request.created_at.strftime("%Y-%m-%d %H:%M:%S") %>
        </td>

        <td><%= request.provider %></td>

        <td><%= request.model %></td>

        <td><%= request.operation %></td>

        <td><%= request.status %></td>

        <td><%= number_with_delimiter(request.total_tokens) %></td>

        <td>
          <%= request.latency_ms ? "#{request.latency_ms} ms" : "N/A" %>
        </td>

        <td><%= request.retry_count %></td>

        <td><%= request.http_status || "N/A" %></td>
      </tr>
    <% end %>
  </tbody>
</table>

Step 12L – Request Detail View

Open:

app/views/admin/ai_requests/show.html.erb

Use:

<h1>AI Request #<%= @ai_request.id %></h1>

<p>
  <%= link_to "← Back to AI Requests",
      admin_ai_requests_path %>
</p>

<table>
  <tbody>
    <tr>
      <th>Provider</th>
      <td><%= @ai_request.provider %></td>
    </tr>

    <tr>
      <th>Model</th>
      <td><%= @ai_request.model %></td>
    </tr>

    <tr>
      <th>Operation</th>
      <td><%= @ai_request.operation %></td>
    </tr>

    <tr>
      <th>Status</th>
      <td><%= @ai_request.status %></td>
    </tr>

    <tr>
      <th>Streamed</th>
      <td><%= @ai_request.streamed? ? "Yes" : "No" %></td>
    </tr>

    <tr>
      <th>Input Tokens</th>
      <td><%= @ai_request.input_tokens || "N/A" %></td>
    </tr>

    <tr>
      <th>Output Tokens</th>
      <td><%= @ai_request.output_tokens || "N/A" %></td>
    </tr>

    <tr>
      <th>Total Tokens</th>
      <td><%= @ai_request.total_tokens %></td>
    </tr>

    <tr>
      <th>Estimated Cost</th>
      <td>
        <%= @ai_request.estimated_cost || "N/A" %>
      </td>
    </tr>

    <tr>
      <th>Latency</th>
      <td>
        <%= @ai_request.latency_ms ?
            "#{@ai_request.latency_ms} ms" :
            "N/A" %>
      </td>
    </tr>

    <tr>
      <th>Retries</th>
      <td><%= @ai_request.retry_count %></td>
    </tr>

    <tr>
      <th>HTTP Status</th>
      <td><%= @ai_request.http_status || "N/A" %></td>
    </tr>

    <tr>
      <th>Request ID</th>
      <td><%= @ai_request.request_id || "N/A" %></td>
    </tr>

    <tr>
      <th>Started At</th>
      <td><%= @ai_request.started_at || "N/A" %></td>
    </tr>

    <tr>
      <th>Completed At</th>
      <td><%= @ai_request.completed_at || "N/A" %></td>
    </tr>

    <tr>
      <th>Conversation</th>
      <td>
        <% if @ai_request.conversation %>
          <%= link_to(
            "##{@ai_request.conversation.id}",
            conversation_path(@ai_request.conversation)
          ) %>
        <% else %>
          N/A
        <% end %>
      </td>
    </tr>

    <tr>
      <th>Message</th>
      <td>
        <%= @ai_request.message_id || "N/A" %>
      </td>
    </tr>

    <tr>
      <th>Error Class</th>
      <td><%= @ai_request.error_class || "N/A" %></td>
    </tr>

    <tr>
      <th>Error Message</th>
      <td>
        <pre><%= @ai_request.error_message || "N/A" %></pre>
      </td>
    </tr>

    <tr>
      <th>Metadata</th>
      <td>
        <pre><%= JSON.pretty_generate(@ai_request.metadata) %></pre>
      </td>
    </tr>
  </tbody>
</table>

Step 12M – Create some test data

Before wiring the real AI request into this table, let’s verify the admin UI independently.

Run:

bin/rails c

Create:

AiRequest.create!(
  provider: "openrouter",
  model: "openrouter/free",
  operation: "chat",
  status: :success,
  input_tokens: 120,
  output_tokens: 80,
  latency_ms: 1530,
  retry_count: 0,
  http_status: 200,
  request_id: SecureRandom.uuid,
  started_at: 2.seconds.ago,
  completed_at: Time.current,
  streamed: true
)

Then open:

http://localhost:3000/admin/ai_requests

Browser authentication should ask for:

Username:
Password:

Use your configured admin credentials.

You should see:

AI Observability

Total Requests      1
Successful          1
Failed              0
Input Tokens        120
Output Tokens        80
Average Latency    1530 ms

Click the request ID and you’ll see the complete details.

Step 12N – Now connect this to the real AI request

This is the important part.

We don’t want:

AI request
     ↓
nothing stored

We want:

ChatService
     ↓
AiRequest.pending
     ↓
Ai::Client
     ↓
LLM
     ↓
AiRequest.success

Eventually:

                 AiRequest
                    │
       ┌────────────┼─────────────┐
       ▼            ▼             ▼
    Message    Conversation      LLM
       │                          │
       └──────────────┬───────────┘
                      ▼
                Admin Dashboard

We’ll modify Ai::ChatService to create and update the record around the provider call.

For the non-streaming path first, use this structure:

class Ai::ChatService
  def initialize(
    ai_client: Ai::Client.new,
    prompt_builder_class: Ai::PromptBuilder
  )
    @ai_client = ai_client
    @prompt_builder_class = prompt_builder_class
  end

  def call(conversation:, user_message:)
    conversation.transaction do
      user_message_record = conversation.messages.create!(
        role: :user,
        content: user_message
      )

      messages = @prompt_builder_class
        .new(conversation: conversation)
        .build

      ai_request = conversation.ai_requests.create!(
        message: user_message_record,
        provider: "openrouter",
        model: Ai::Client::MODEL,
        operation: "chat",
        status: :pending,
        streamed: false,
        started_at: Time.current,
        request_id: SecureRandom.uuid
      )

      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)

      begin
        result = @ai_client.chat(messages: messages)

        latency_ms =
          (
            Process.clock_gettime(Process::CLOCK_MONOTONIC) -
            started_at
          ) * 1000

        assistant_message = conversation.messages.create!(
          role: :assistant,
          content: result[:content],
          model: result[:model],
          input_tokens: result[:input_tokens],
          output_tokens: result[:output_tokens]
        )

        ai_request.update!(
          message: assistant_message,
          status: :success,
          input_tokens: result[:input_tokens],
          output_tokens: result[:output_tokens],
          latency_ms: latency_ms.round,
          completed_at: Time.current,
          http_status: 200
        )

        assistant_message
      rescue => e
        ai_request.update!(
          status: :failed,
          error_class: e.class.name,
          error_message: e.message,
          completed_at: Time.current
        )

        raise
      end
    end
  end
end

One important architecture note

I used:

rescue => e

here only to demonstrate recording unexpected failures.

In the final production version, we’ll distinguish:

timeout
rate limit
provider error
invalid response
unexpected application bug

and map them to the proper AiRequest.status.

That’s coming immediately after this.

Why this dashboard is worth having

You now have a tangible answer to questions like:

How would you monitor an AI application?

You can say:

“I record each AI invocation separately from the conversation message itself. I track provider, model, status, latency, token consumption, retries, HTTP status and error information, then expose that through an internal observability dashboard.”

Then show page:

/admin/ai_requests

That’s much stronger than saying:

“I would use logging.”

One thing I deliberately did NOT add

I don’t recommend storing the complete prompt by default in AiRequest.

Why?

Because prompts can contain:

PII
customer data
confidential company information
secrets

Instead we can later store safe metadata such as:

{
  "message_count": 8,
  "prompt_tokens": 1200,
  "temperature": 0.2
}

and keep sensitive content under the normal conversation access controls.

Issue 1:Fix AI Response: User Safety

Currently when I tested I get the AI Response like:
User Safety: safeResponse Safety: safe

This is a model-selection problem, not a Rails problem.

The response:

User Safety: safeResponse Safety: safe

is characteristic of a content-safety/guardrail model, not a normal conversational model. OpenRouter currently lists Nemotron 3.5 Content Safety (free) as a moderation model whose intended output is exactly safety classifications such as User Safety and Response Safety. (OpenRouter)

Because we’re using:

MODEL = "openrouter/free"

OpenRouter is free to route that request to an available free model. The free-model router is explicitly designed to select among available free models, so you shouldn’t use it when you need a stable application behavior. (OpenRouter)

Fix: choose an actual chat model

For our course, let’s use a specific free conversational model instead of:

MODEL = "openrouter/free"

A good current option is:

MODEL = "openai/gpt-oss-20b:free"

OpenRouter lists free models separately, including general-purpose models; the exact free catalog changes over time.

Change Ai::Client

Open:

app/services/ai/client.rb

Change:

MODEL = "openrouter/free"

to:

MODEL = "openai/gpt-oss-20b:free"

Then test:

bin/rails c
client = Ai::Client.new
result = client.chat(
  messages: [
    {
      role: "user",
      content: "Why Node.js as a backend?"
    }
  ]
)
puts result[:content]

We should now get an actual explanatory answer rather than the safety classification.

Why I want a specific model for our project

This is actually a valuable AI engineering lesson.

Current approach

Ai::Client
    ↓
openrouter/free
    ↓
??? model

The model can change depending on routing.

Better application architecture

Ai::Client
    ↓
specific model
    ↓
predictable behavior

For production systems, model choice should generally be deliberate rather than an accidental consequence of a router.

The openrouter/free router is useful for experimentation, but for our course we’ll use an explicit free model so our behavior stays understandable. OpenRouter itself recommends openrouter/free as a convenient way to sample available free models, which is precisely why it shouldn’t be treated as a fixed model identity.

One more thing: our RAG work needs an embedding model

Don’t use the chat model for embeddings.

We’ll have:

Chat:
openai/gpt-oss-20b:free
Embeddings:
separate embedding model

OpenRouter currently lists free embedding models as well, including NVIDIA’s Nemotron 3 Embed 1B, which is specifically intended for retrieval/RAG. (OpenRouter)

We’ll choose the embedding model separately when we implement Ai::EmbeddingService.

For now

Make this one-line change:

MODEL = "openai/gpt-oss-20b:free"

After that, we’ll continue with Step 13 – generating embeddings and storing the first real vector in document_chunks.

Issue 2: OpenAI::Errors::NotFoundError

Our server Log:

OpenAI::Errors::NotFoundError ({url: "https://openrouter.ai/api/v1/chat/completions", status: 404, body: {error: {message: "This model is unavailable for free. The paid version is available now - use this slug instead: openai/gpt-oss-20b", code: 404}, user_id: ...

Since we’re using the openai Ruby SDK, our rescue layer should use OpenAI::Errors::*, not Faraday exceptions. The SDK maps HTTP status codes such as 400, 401, 403, 404, 409, 422, 429 and 500+ into its own typed exceptions, and it has separate APIConnectionError / APITimeoutError classes. (https://github.com/openai/openai-ruby/blob/main/lib/openai/errors.rb)

Also, our 404 message tells us something important:

OpenRouter’s current free catalog does include openai/gpt-oss-20b:free, but free endpoints can change availability. (OpenRouter)

Our earlier 404 specifically said that the endpoint was unavailable for free at that moment and suggested the paid slug. Since OpenRouter currently lists the :free variant as free, this looks like provider/availability inconsistency, not that our slug was fundamentally wrong. OpenRouter also notes that free variants are rate-limited and availability can vary. (OpenRouter)

1. Fix the model

Let’s use the explicit free model again:

MODEL = "openai/gpt-oss-20b:free"

OpenRouter currently lists that exact slug as free with zero input/output pricing. (OpenRouter)

If that endpoint temporarily fails, we can switch to another currently listed free model rather than using openrouter/free.

2. Fix Ai::Client error handling

Also change our Ai::Client chat rescues from: Faraday::TooManyRequestsError 
Faraday::TimeoutError 
Faraday::Error 
to: similar to: OpenAI::Errors::NotFoundError etc, 

check: https://github.com/openai/openai-ruby/blob/main/lib/openai/errors.rb

Let’s use the actual SDK error hierarchy.

The important classes are:

OpenAI::Errors::BadRequestError
OpenAI::Errors::AuthenticationError
OpenAI::Errors::PermissionDeniedError
OpenAI::Errors::NotFoundError
OpenAI::Errors::ConflictError
OpenAI::Errors::UnprocessableEntityError
OpenAI::Errors::RateLimitError
OpenAI::Errors::InternalServerError
OpenAI::Errors::APIConnectionError
OpenAI::Errors::APITimeoutError

The current SDK maps HTTP 404 → NotFoundError, 429 → RateLimitError, and 500+ → InternalServerError. (GitHub)

So replace our old Faraday rescues entirely.

app/services/ai/client.rb

Use:

class Ai::Client
  MODEL = "openai/gpt-oss-20b:free"
  BASE_URL = "https://openrouter.ai/api/v1"

  def initialize
    api_key = Rails.application.credentials.dig(:openrouter, :api_key)

    raise "OpenRouter API key is missing" if api_key.blank?

    @client = OpenAI::Client.new(
      api_key: api_key,
      base_url: BASE_URL
    )
  end

  def chat(messages:)
    response = @client.chat.completions.create(
      model: MODEL,
      messages: messages
    )

    {
      content: response.choices.first.message.content,
      model: response.model,
      input_tokens: response.usage&.prompt_tokens,
      output_tokens: response.usage&.completion_tokens
    }
  rescue OpenAI::Errors::RateLimitError => e
    raise Ai::RateLimitError, e.message

  rescue OpenAI::Errors::APITimeoutError => e
    raise Ai::TimeoutError, e.message

  rescue OpenAI::Errors::APIConnectionError => e
    raise Ai::ProviderError, e.message

  rescue OpenAI::Errors::BadRequestError,
          OpenAI::Errors::AuthenticationError,
          OpenAI::Errors::PermissionDeniedError,
          OpenAI::Errors::NotFoundError,
          OpenAI::Errors::ConflictError,
          OpenAI::Errors::UnprocessableEntityError,
          OpenAI::Errors::InternalServerError,
          OpenAI::Errors::APIStatusError => e
    raise Ai::ProviderError, e.message
  end
end

The specific NotFoundError you just encountered will therefore be caught here:

rescue OpenAI::Errors::NotFoundError => e

and converted into our application-level:

Ai::ProviderError

3. Why keep Ai::*Error?

This is the architecture we want:

OpenRouter / OpenAI SDK
          ↓
OpenAI::Errors::NotFoundError
          ↓
      Ai::Client
          ↓
    Ai::ProviderError
          ↓
     ChatService
          ↓
 Rails application

Your Rails code shouldn’t care whether the provider throws:

OpenAI::Errors::NotFoundError

or some completely different exception tomorrow.

That’s precisely why our abstraction exists.

4. But don’t catch everything as ProviderError

There’s an important distinction.

We should not do:

rescue StandardError => e
  raise Ai::ProviderError
end

because a programming bug such as:

NoMethodError

would then masquerade as an LLM provider failure.

Keep provider/API exceptions mapped, but let genuine application bugs surface.

5. Our current custom errors are good

We already created:

class Ai::Error < StandardError
end
class Ai::ProviderError < Ai::Error
end
class Ai::RateLimitError < Ai::Error
end
class Ai::TimeoutError < Ai::Error
end

That’s still a good design.

Now the relationship is:

OpenAI::Errors::RateLimitError
             ↓
Ai::RateLimitError
OpenAI::Errors::APITimeoutError
             ↓
Ai::TimeoutError
OpenAI::Errors::NotFoundError
             ↓
Ai::ProviderError

6. Test the actual exception

Since we currently have a 404 issue, this is a useful test.

In Rails console:

bin/rails c

Then, Try the request with the unavailable model if you want to verify the mapping:

client = Ai::Client.new

client.chat(
  messages: [
    {
      role: "user",
      content: "Why Node.js as a backend?"
    }
  ]
)

You should now receive:

Ai::ProviderError

rather than:

OpenAI::Errors::NotFoundError

That proves our abstraction is working.

Happy Rails AI Integration!

Integrate AI with Rails: AI bootcamp for Developers – Day 4 -Practical Course – Part 3

Great. Now we can make the first real LLM request.

We’ll keep this step deliberately small. Our goal is not to build the complete AI assistant yet.

The goal is simply:

Rails
  ↓
Ai::Client
  ↓
OpenAI API
  ↓
LLM
  ↓
Response

Once this works, we’ll build the Rails service layer around it.

Step 5.11 – Add the OpenAI Ruby SDK

Rather than manually constructing HTTP requests, we’ll start with the official Ruby SDK.

1. Add the gem

Open our Gemfile and add:

gem "openai"

Then run:

bundle install

Verify:

bundle info ruby-openai

You should see where Bundler installed the gem.

Why use an SDK?

We could use Ruby’s Net::HTTP ourselves:

Ruby
  ↓
Net::HTTP
  ↓
HTTP request
  ↓
OpenAI

But then we’d have to manually handle:

  • authentication headers
  • JSON encoding
  • HTTP errors
  • response parsing
  • request formatting

The SDK gives us:

Ruby
  ↓
OpenAI Ruby SDK
  ↓
HTTP
  ↓
OpenAI

Important point: An SDK doesn’t eliminate the HTTP API. It is an abstraction over it.

Step 5.12 – Verify the gem

Run:

bin/rails console

Then:

require "openai"

It should return:

=> true

or possibly:

=> "openai"

depending on the gem’s load behavior.

Then:

OpenAI

should resolve without a NameError.

Exit:

exit

Step 5.13 – Let’s inspect the SDK before using it

This is something I want you to develop as a senior Ruby developer habit.

Instead of blindly copying code from a blog, let’s see what API the installed gem exposes.

Run:

bundle info ruby-openai

Then:

bin/rails console

Inside console:

require "openai"

Then:

OpenAI::Client.instance_method(:initialize).parameters

This tells us what the client’s constructor expects.

Also try:

OpenAI::Client.instance_methods(false)

We’re learning to inspect a Ruby library rather than treating it as magic.

Step 5.14 – Create the OpenAI client

Now let’s modify:

app/services/ai/client.rb

We’ll start with:

class Ai::Client
  def initialize
    @api_key = Rails.application.credentials.dig(:openai, :api_key)

    raise "OpenAI API key is missing" if @api_key.blank?

    @client = OpenAI::Client.new(api_key: @api_key)
  end
end

Now we have:

Ai::Client
   │
   ├── reads Rails credentials
   │
   └── creates OpenAI SDK client

Step 5.15 – Test initialization

Run:

bin/rails console

Then:

client = Ai::Client.new

It should return something similar to:

#<Ai::Client:0x...>

No request has happened yet.

That’s important.

We’ve only done:

Rails credentials
       ↓
API key
       ↓
OpenAI::Client

Stop here

Don’t call the LLM yet.

I want you to complete these steps first:

1. Gemfile

gem "openai"

2. Install

bundle install

3. Verify

bundle info ruby-openai

4. Update

app/services/ai/client.rb

with the code above.

5. Test

bin/rails c
client = Ai::Client.new

One note

The Ruby OpenAI SDK’s API can change between versions, so don’t blindly copy the exact request syntax from older tutorials. That’s why we’re checking the version we’ve actually installed before writing the API call.

Now we’ve:

“OpenAI client initialized.”

We’ll make our first actual LLM request and inspect the complete response, including:

response
model
output
usage
input tokens
output tokens

That will lead directly into why we added those fields to our Message model.

@client = OpenAI::Client.new(api_key: @api_key)

We’ll use our installed SDK’s API, not older ruby-openai examples. The current official openai Ruby SDK documents OpenAI::Client.new(api_key: ...) and the Responses API as the current interface. (GitHub)

Step 5.16 – Make the First Real LLM Request

For this step, we’ll do one simple request and inspect the response.

We are not integrating it with Conversation or Message yet.

Our goal is:

Rails console
    ↓
Ai::Client
    ↓
OpenAI Responses API
    ↓
LLM
    ↓
Response

1. Add a chat method

Open:

app/services/ai/client.rb

Change it to:

class Ai::Client
  def initialize
    @api_key = Rails.application.credentials.dig(:openai, :api_key)

    raise "OpenAI API key is missing" if @api_key.blank?

    @client = OpenAI::Client.new(api_key: @api_key)
  end

  def chat(message)
    @client.responses.create(
      model: "gpt-5.2",
      input: message
    )
  end
end

The SDK’s current Responses API accepts model and input for creating a response. (GitHub)

Why input: message?

We’re deliberately starting with the simplest possible request:

input: "Explain Ruby blocks in simple terms"

Later we’ll send structured conversation history:

input: [
  { role: :system, content: "..." },
  { role: :user, content: "..." }
]

The Responses API supports both simple input and structured message input. (GitHub)

2. Start Rails console

bin/rails c

Create the client:

client = Ai::Client.new

Now make the request:

response = client.chat(
  message: "Explain Ruby blocks in simple terms."
)

This is the moment our application makes an actual network request.

3. Inspect the response

First:

response.class

Then:

response

Don’t worry if the output is large.

The current official Ruby SDK returns typed response objects and the response contains the generated output plus metadata such as usage. (GitHub)

But if you get the following output, we can change the model which has free API calls:

ai-assistant(dev):013> client = Ai::Client.new
ai-assistant(dev):003> res = ai.chat('I want to be a expert in Ruby language')
app/services/ai/client.rb:11:in 'Ai::Client#chat': {url: "https://api.openai.com/v1/responses", status: 429, body: {error: {message: "You have no credits remaining. Add credits to continue using the API at https://platform.openai.com/settings/organization/billing/.", type: "insufficient_quota", param: nil, code: "credit_balance_exhausted"}}} (OpenAI::Errors::RateLimitError)
        from (ai-assistant):3:in '<compiled>'

Yes – the error makes sense and there is an important distinction here:

Our ChatGPT subscription and OpenAI API billing are separate.

So even if you can use ChatGPT normally, that does not give your Ruby application free API calls. OpenAI explicitly says ChatGPT and API billing are managed separately. (OpenAI Help Center)

Why you’re seeing You have no credits remaining

Your Rails code is calling the OpenAI API, not ChatGPT:

Rails app
   ↓
OpenAI API
   ↓
API billing / credits

The API account associated with your key currently has no usable credits. OpenAI’s current prepaid-billing documentation says API requests stop once the available credit balance is exhausted. (OpenAI Help Center)

“But aren’t basic models free?”

Not generally for the API.

There may be specific free/trial allocations or products with included usage, but you should not assume that a model being available in ChatGPT means the API is free.

For our Rails application, we’re using:

OpenAI::Client

which consumes API usage and is metered separately.

What I recommend for our course

I don’t think we should spend money just to continue learning unless you’re comfortable doing so.

We have three practical paths:

Option 1 – Add a small API balance

Open your OpenAI API billing overview and check your balance. New API users currently use prepaid billing and the documented minimum purchase is $5, with $10 as the default purchase amount. (OpenAI Help Center)

For this course a small balance should be plenty for experimentation because our prompts will be tiny.

Option 2 – Use another provider with a free tier

We could temporarily use a provider that offers some free API usage, while keeping the same architecture:

Ai::Client
    ↓
Provider
    ↓
LLM

This is actually useful because later we’ll make our architecture provider-agnostic.

Option 3 – Run a local model

We can install something like Ollama and run an LLM locally:

Rails
 ↓
Ai::Client
 ↓
localhost
 ↓
Local LLM

Advantages:

  • no API credits
  • no network dependency
  • no per-token cost
  • great for development

The downside is that the model quality may differ from hosted models, and local inference requires reasonable hardware.

One important thing for our architecture

Don’t change this:

Ai::Client

The fact that OpenAI isn’t currently usable doesn’t mean we should redesign the application.

We specifically created:

Rails
  ↓
Ai::Client
  ↓
Provider

so that later we can switch:

Ai::Client
    ↓
OpenAI

to:

Ai::Client
    ↓
Anthropic

or:

Ai::Client
    ↓
Ollama

without rewriting our Rails application.

That’s actually an important senior-level design lesson.

What we can do now?

Since our objective is learning AI engineering, not spending money on API calls, first check your API billing page.

If it shows:

Free trial credit remaining: $0.00

then the error is fully explained. OpenAI’s billing documentation uses exactly this sort of balance indicator. (OpenAI Help Center)

We can then decide between a small API credit or a local/free-tier provider.

For this course, I slightly prefer keeping OpenAI as the first provider so you learn the real production API flow, then later we’ll add a second provider/local model to demonstrate the abstraction properly.

4. Get the generated text

Try:

response.output_text

You should get a normal answer such as:

A Ruby block is a chunk of code that can be passed to a method...

This is the first important distinction:

response
    ↓
entire API response
response.output_text
    ↓
just the model's text

Don’t immediately throw away the full response. We need the metadata later.

5. Inspect the model

Try:

response.model

This tells you which model actually generated the response.

That’s relevant to our messages.model column.

6. Inspect usage

Now:

response.usage

You should see token-related information.

Inspect it:

response.usage.input_tokens

and:

response.usage.output_tokens

These are directly related to the fields we added earlier:

messages
-------------------
input_tokens
output_tokens

So our database design is now connected to a real API response.

LLM response
     │
     ├── model
     ├── output text
     └── usage
          ├── input_tokens
          └── output_tokens

The SDK’s response models expose usage information as part of the response. (GitHub)

7. One very important experiment

Ask a second question:

response2 = client.chat(
  message: "What is my name?"
)

You’ll probably notice the model doesn’t know your name from the previous request.

That’s intentional.

We made two independent requests:

Request 1
"Explain Ruby blocks"
Request 2
"What is my name?"

The LLM does not automatically receive our previous request.

This is going to become extremely important when we implement:

Conversation
    ↓
Messages
    ↓
Prompt Builder
    ↓
LLM

Our Rails application will be responsible for providing the appropriate conversation context.

8. One thing to notice

We’ve built:

app/services/ai/client.rb

and now:

Ai::Client.new.chat(...)

works.

That’s already a valuable architectural boundary:

Rails application
       │
       ▼
   Ai::Client
       │
       ▼
OpenAI SDK
       │
       ▼
OpenAI API

Our controllers won’t need to know:

  • how authentication works,
  • how the SDK works,
  • which API endpoint is used,
  • how OpenAI responses are represented.

That’s why we created the abstraction.

Check our code in this repo: https://github.com/abhilashak/ai_assistant

Stop Here

Run these commands one by one:

bin/rails c
client = Ai::Client.new
response = client.chat(
  message: "Explain Ruby blocks in simple terms."
)

Then inspect:

response.output_text
response.model
response.usage
response.usage.input_tokens
response.usage.output_tokens

Don’t paste our API key or any sensitive output anywhere.

Now: “Our First LLM request works.”

Then we’ll do the next important step: inspect the raw response structure and improve Ai::Client so it returns a clean Ruby object to the rest of our Rails application.

Integrate AI with Rails: AI bootcamp for Developers – Day 4 -Practical Course – Part 2

Now let’s move to the next step: make the Message model production-friendly.

We’ll start with the most important field: role.

Step 3 – Design Message.role

Currently our database allows:

role = anything

For example:

"user"
"assistant"
"system"
"foo"
"hello"
"something-invalid"

That’s not what we want.

Our AI application has a defined set of roles:

user
assistant
system

Later, when we introduce tool calling, we may also need to represent tool messages depending on the provider/API design. But for our current application, we’ll keep the persisted roles to these three.

Why use a string instead of an integer?

You may remember our previous discussion about Rails enums.

We could store:

0 = user
1 = assistant
2 = system

But for an AI application, I prefer a string-backed enum.

Database:

role
---------
user
assistant
system

instead of:

role
---------
0
1
2

Why?

1. Database is self-describing

When you run:

SELECT role FROM messages;

you immediately see:

user
assistant
assistant
user
system

2. Easier debugging

When you’re debugging an AI conversation, the actual value is obvious.

3. Safer for external APIs

LLM APIs already use strings such as:

{
  "role": "user"
}

So our database representation matches the domain.

Step 3A – Add the Rails enum

Open:

app/models/message.rb

Currently you should have something like:

class Message < ApplicationRecord
  belongs_to :conversation
end

Change it to:

class Message < ApplicationRecord
  belongs_to :conversation
  enum :role, {
    user: "user",
    assistant: "assistant",
    system: "system"
  }, validate: true
end

Understand this carefully

This:

enum :role, {
  user: "user",
  assistant: "assistant",
  system: "system"
}, validate: true

doesn’t mean PostgreSQL has an enum type. We’re using a Rails enum backed by a string column.

PostgreSQL still has:

role character varying

Rails gives us a domain API on top of it.

Step 3B – Test the enum

Start Rails console:

bin/rails console

Find our message:

message = Message.first

Check:

message.role

You should get:

"user"

Now:

message.user?

Expected:

true

And:

message.assistant?

Expected:

false

Step 3C – Test the scopes

Rails also gives us useful scopes.

Try:

Message.user

and:

Message.assistant

and:

Message.system

For example:

Message.user

roughly translates to:

SELECT *
FROM messages
WHERE role = 'user';

This is one of the benefits of using an enum.

Step 3D – Test invalid values

Now try:

Message.new(
  conversation: Conversation.first,
  role: "something_else",
  content: "test"
)

Because we specified:

validate: true

Rails should treat the role as invalid.

Check:

message = Message.new(
  conversation: Conversation.first,
  role: "something_else",
  content: "test"
)
message.valid?

Expected:

false

Then:

message.errors.full_messages

You should see an error indicating that the role is not included in the allowed values.

Why validate: true?

This is worth understanding: Without validation, Rails enum behavior can raise an ArgumentError when assigning an invalid value.

With:

validate: true

we get normal ActiveRecord validation behavior:

message.valid?
→ false

and:

message.errors

contains the validation error.

That’s generally more convenient when the model is receiving user/application input.

Step 3E – One more important layer: Database constraint

There is a subtle issue here.

Rails validation protects you when data enters through Rails.

But PostgreSQL doesn’t know that only these values are valid:

user
assistant
system

Someone could execute:

INSERT INTO messages (conversation_id, role, content)
VALUES (1, 'invalid', '...');

directly against PostgreSQL.

The database would currently allow it.

This leads to an important senior-engineering principle:

Application-level validation and database-level integrity are complementary.

We’ll add a database constraint.

But don’t do that yet. First make sure the Rails enum works.

After that, we’re finally ready for the exciting part:

Rails
  ↓
Ai::Client
  ↓
LLM API
  ↓
Real AI response

Now let’s strengthen the model at the database level.

You currently have Rails validation:

enum :role, {
  user: "user",
  assistant: "assistant",
  system: "system"
}, validate: true

That’s good, but a senior Rails application shouldn’t rely only on model validation for important data integrity.

Step 4 – Add Database Constraints

We want PostgreSQL itself to enforce:

role MUST be:
  user
  assistant
  system

and:

content MUST NOT be NULL
role MUST NOT be NULL

This gives us two layers:

Rails
  ↓
Model validation
PostgreSQL
  ↓
Database constraint

4.1 Why NULL matters

Currently this is possible at the database level:

role = NULL

But an AI message without a role doesn’t make sense.

Likewise:

content = NULL

doesn’t represent a meaningful message.

So we’ll make both required.

4.2 Create a new migration

Don’t modify the old migration because it has already been executed and committed.

Generate a new migration:

bin/rails generate migration AddMessageConstraints

Rails should create:

db/migrate/XXXXXXXXXXXXXX_add_message_constraints.rb

Open that file.

4.3 Add NOT NULL constraints

Put this inside change:

class AddMessageConstraints < ActiveRecord::Migration[8.1]
  def change
    change_column_null :messages, :role, false
    change_column_null :messages, :content, false
  end
end

So conceptually:

def change
  change_column_null :messages, :role, false
  change_column_null :messages, :content, false
end

4.4 Add PostgreSQL CHECK constraint

Now we want PostgreSQL to enforce:

role IN ('user', 'assistant', 'system')

Add:

add_check_constraint(
  :messages,
  "role IN ('user', 'assistant', 'system')",
  name: "messages_role_check"
)

Our migration becomes:

class AddMessageConstraints < ActiveRecord::Migration[8.1]
  def change
    change_column_null :messages, :role, false
    change_column_null :messages, :content, false
    add_check_constraint(
      :messages,
      "role IN ('user', 'assistant', 'system')",
      name: "messages_role_check"
    )
  end
end

4.5 Run the migration

Execute:

bin/rails db:migrate

You should see Rails successfully applying the migration.

4.6 Inspect PostgreSQL

This is worth doing because understand what’s actually happening underneath Rails.

Run:

bin/rails dbconsole

Then:

\d messages

Look toward the bottom.

You should see a check constraint similar to:

messages_role_check
CHECK ((role)::text = ANY (...))

The exact display can vary by PostgreSQL version.

Also check:

\d+ messages

4.7 Test the database constraint

Now let’s prove that PostgreSQL protects us even if Rails is bypassed.

Inside psql, try:

INSERT INTO messages
  (conversation_id, role, content, created_at, updated_at)
VALUES
  (1, 'invalid', 'This should fail', NOW(), NOW());

You should get an error similar to:

ERROR: new row for relation "messages" violates check constraint "messages_role_check"

That’s exactly what we want.

The database is now protecting the data.

Why is this important?

Suppose an int. asks:

“Why do you have both Rails validation and a PostgreSQL constraint?”

A strong senior-level answer would be:

“Rails validations provide application-level feedback and are useful for normal model operations, but they’re not a database integrity guarantee because data can enter through other paths. For important invariants such as message roles, I also enforce the constraint at the PostgreSQL level.”

That’s a much stronger answer than:

“Because Rails has validations.”

4.8 One more design question: content

We’re making:

change_column_null :messages, :content, false

But should an AI message be allowed to contain an empty string?

For example:

content: ""

NOT NULL allows that.

So:

NULL       NO
""         technically allowed
"Hello"    YES

Whether empty content should be allowed is an application-level business rule.

We can later decide whether to add:

validates :content, presence: true

But don’t add that yet.

There are legitimate AI API situations where a message may not have ordinary text content – for example, tool-related or structured content. We’ll revisit our message representation when we implement tool calling.

4.9 Test a valid message

Exit psql:

\q

Then:

bin/rails c

Run:

conversation = Conversation.first

Then:

message = conversation.messages.create(
  role: :user,
  content: "What is Ruby?"
)

Check:

message.persisted?

You should get:

true

And:

message.role

should return:

"user"

Stop Here

Please do these in order:

bin/rails generate migration AddMessageConstraints

Edit the migration with the constraints above.

Then:

bin/rails db:migrate

Verify with:

bin/rails dbconsole
\d messages

Then test the invalid role directly in PostgreSQL.

Finally:

git add app/models/message.rb db/migrate
git commit -m "feat: validate message roles"
git push

NOW: “Message constraints are done.”

Then we move to the big milestone: Our First Real LLM API Call

Excellent. We now have a clean foundation:

Ruby 3.4.1
Rails 8.1
PostgreSQL
Conversation
    │
    └── Message
          ├── role
          ├── content
          ├── model
          ├── input_tokens
          └── output_tokens
Ai::Client

Now we reach the first real AI step.

Step 5 – Make Our First LLM API Call

We’re going to do this in a deliberately controlled way.

Don’t build the Chat UI yet.

First, we need to understand:

Ruby
  ↓
Ai::Client
  ↓
HTTP request
  ↓
LLM provider
  ↓
HTTP response
  ↓
Ruby

Once we understand this, we’ll wrap it nicely into Rails architecture.

5.1 First decision – which provider?

For this practical course, let’s start with OpenAI.

Not because you must use OpenAI in production, but because it gives us a straightforward API to understand the fundamentals.

Later we’ll discuss:

Rails
  │
  ├── OpenAI
  ├── Anthropic
  └── Gemini

and how to design our Ai::Client so that we’re not tightly coupled to one provider.

5.2 Before writing code – understand the request

Conceptually, we’re going to send something like:

POST /v1/responses
{
  "model": "...",
  "input": "Explain Ruby blocks in simple terms."
}

The provider’s server processes the request:

Rails
   │
   │ HTTPS
   ▼
OpenAI API
   │
   ▼
LLM
   │
   ▼
Response

The important thing to understand is:

An LLM API is an HTTP API.

The Ruby SDK is just a convenient abstraction around HTTP.

5.3 Check our Ai::Client

You already created:

app/services/ai/client.rb

Open it.

If it currently contains nothing useful, that’s completely fine.

For now, make it:

# app/services/ai/client.rb

class Ai::Client
end

Don’t add API code yet.

5.4 Configure the API key securely

Do not put our API key in Ruby source code.

We have two common approaches:

Environment variables

or:

Rails encrypted credentials

For this project, I’m going to use Rails encrypted credentials because it’s a good opportunity to understand how Rails handles secrets.

5.5 Create Rails encrypted credentials

Run:

➜  ai_assistant git:(main) ✗ VISUAL="code --wait" rails credentials:edit

Rails will open our configured editor.

Add:

openai:
  api_key: OUR_OPENAI_API_KEY

For example:

openai:
  api_key: sk-xxxxxxxxxxxxxxxx

Use our actual API key locally, but never paste it into this conversation or commit it to GitHub.

Save and close the editor

What’s actually happening?

Rails creates/uses:

config/credentials.yml.enc

This file is encrypted.

Our encryption key is stored separately in:

config/master.key

The important rule is:

config/credentials.yml.enc
        ↓
       COMMIT
        ↓
      GitHub

is okay.

But:

config/master.key

should never be committed to GitHub.

Check:

git status

You should not see:

config/master.key

as a file to commit.

5.6 Verify Rails can read the key

Run:

bin/rails console

Then:

Rails.application.credentials.dig(:openai, :api_key)

You should get our key back, just verify that it returns a string rather than nil.

Then:

exit

5.7 Why use dig?

Our credentials structure is:

openai:
  api_key: ...

which Rails exposes approximately as:

{
  openai: {
    api_key: "..."
  }
}

So:

Rails.application.credentials.dig(:openai, :api_key)

means:

credentials
    ↓
openai
    ↓
api_key

This is cleaner than accessing nested values manually.

5.8 Now configure Ai::Client

Open:

app/services/ai/client.rb

Change it to:

class Ai::Client
  def initialize
    @api_key = Rails.application.credentials.dig(:openai, :api_key)
  end
end

Now the client knows how to retrieve its secret.

5.9 Add a safety check

We don’t want the application to fail mysteriously later.

Add:

class Ai::Client
  def initialize
    @api_key = Rails.application.credentials.dig(:openai, :api_key)

    raise "OpenAI API key is missing" if @api_key.blank?
  end
end

Now:

Ai::Client.new

will fail immediately if the key isn’t configured. This is called fail-fast configuration.

5.10 Test the client

Run:

bin/rails console

Then:

client = Ai::Client.new

If everything is configured correctly, it should return:

#<Ai::Client:0x...>

No API request has happened yet.

We’re only testing:

Rails credentials
       ↓
Ai::Client

Check our code in this repo: https://github.com/abhilashak/ai_assistant

Stop Here

Don’t make the API request yet.

complete only these steps first:

1. Configure credentials

bin/rails credentials:edit

with:

openai:
  api_key: OUR_KEY

2. Verify:

bin/rails console
Rails.application.credentials.dig(:openai, :api_key)

Don’t show me the key.

3. Update:

app/services/ai/client.rb

to:

class Ai::Client
  def initialize
    @api_key = Rails.application.credentials.dig(:openai, :api_key)
    raise "OpenAI API key is missing" if @api_key.blank?
  end
end

4. Test:

client = Ai::Client.new

Now: “Ai::Client credentials is done.”

Next topic: Step 5.11: install/configure the OpenAI Ruby client and make the first actual LLM request.

to be continued ..

Rails 7+ API error handling that scales ⚖️

A solid API error strategy gives you:

  • Consistent JSON error shapes
  • Correct HTTP status codes
  • Separation of concerns (domain vs transport)
  • Observability without leaking internals

Below is a practical, production-ready approach that covers controller hooks, controllers, models/libs, background jobs, and more—illustrated with a real scenario from Session::CouponCode.

Core principles

  • Keep transport (HTTP, JSON) in controllers; keep domain logic in models/libs.
  • Map known, expected failures to specific HTTP statuses.
  • Log unexpected failures; return a generic message to clients.
  • Centralize API error rendering in a base controller.

1) A single error boundary for all API controllers

Create a base Error::ApiError and rescue it (plus a safe catch‑all) in your ApiController.

# lib/error/api_error.rb
module Error
  class ApiError < StandardError
    attr_reader :status, :details
    def initialize(message, status = :unprocessable_entity, details: nil)
      super(message)
      @status  = status
      @details = details
    end
  end
end

# app/controllers/api_controller.rb
class ApiController < ActionController::Base
  include LocaleConcern
  skip_forgery_protection

  impersonates :user,
               ......

  # Specific handlers first
  rescue_from Error::ApiError,                          with: :handle_api_error
  rescue_from ActionController::ParameterMissing,       with: :handle_bad_request
  rescue_from ActiveRecord::RecordNotFound,             with: :handle_not_found
  rescue_from ActiveRecord::RecordInvalid,              with: :handle_unprocessable
  rescue_from ActiveRecord::RecordNotUnique,            with: :handle_conflict

  # Catch‑all last
  rescue_from StandardError,                            with: :handle_standard_error

  private

  def handle_api_error(e)
    render json: { success: false, error: e.message, details: e.details }, status: e.status
  end

  def handle_bad_request(e)
    render json: { success: false, error: e.message }, status: :bad_request
  end

  def handle_not_found(_e)
    render json: { success: false, error: 'Not found' }, status: :not_found
  end

  def handle_unprocessable(e)
    render json: { success: false, error: e.record.errors.full_messages }, status: :unprocessable_entity
  end

  def handle_conflict(_e)
    render json: { success: false, error: 'Conflict' }, status: :conflict
  end

  def handle_standard_error(e)
    Rollbar.error(e, path: request.fullpath, client_id: try(:current_client)&.id)
    render json: { success: false, error: 'Something went wrong' }, status: :internal_server_error
  end
end
  • Order matters. Specific rescue_from before StandardError.
  • This pattern avoids duplicating rescue_from across controllers and keeps HTML controllers unaffected.

2) Errors in before actions

Because before_action runs inside controllers, the same rescue_from handlers apply.

Two patterns:

  • Render in the hook for simple guard clauses:
before_action :require_current_client

def require_current_client
  return if current_client
  render json: { success: false, error: 'require_login' }, status: :unauthorized
end
  • Raise a domain/auth error and let rescue_from handle JSON:
# lib/error/unauthorized_error.rb
module Error
  class UnauthorizedError < Error::ApiError
    def initialize(message = 'require_login') = super(message, :unauthorized)
  end
end

before_action :require_current_client

def require_current_client
  raise Error::UnauthorizedError unless current_client
end

Prefer raising if you want consistent global handling and logging.

3) Errors inside controllers

Use explicit renders for happy-path control flow; raise for domain failures:

def create
  form = CreateThingForm.new(params.require(:thing).permit(:name))
  result = CreateThing.new(form: form).call

  if result.success?
    render json: { success: true, thing: result.thing }, status: :created
  else
    # Known domain failure → raise an ApiError to map to 422
    raise Error::ApiError.new(result.message, :unprocessable_entity, details: result.details)
  end
end

Common controller exceptions (auto-mapped above):

  • ActionController::ParameterMissing → 400
  • ActiveRecord::RecordNotFound → 404
  • ActiveRecord::RecordInvalid → 422
  • ActiveRecord::RecordNotUnique → 409

4) Errors in models, services, and libs

Do not call render here. Either:

  • Return a result object (Success/Failure), or
  • Raise a domain‑specific exception that the controller maps to an HTTP response.

Example from our scenario, Session::CouponCode:

# lib/error/session/coupon_code_error.rb
module Error
  module Session
    class CouponCodeError < Error::ApiError; end
  end
end

# lib/session/coupon_code.rb
class Session::CouponCode
  def discount_dollars
    # ...
    case
    when coupon_code.gift_card?
      # ...
    when coupon_code.discount_code?
      # ...
    when coupon_code.multiorder_discount_code?
      # ...
    else
      raise Error::Session::CouponCodeError, 'Unrecognized discount code'
    end
  end
end

Then, in ApiController, the specific handler (or the Error::ApiError handler) renders JSON with a 422.

This preserves separation: models/libs raise; controllers decide HTTP.

5) Other important surfaces

  • ActiveJob / Sidekiq
  • Prefer retry_on, discard_on, and job‑level rescue with logging.
  • Return no HTTP here; jobs are async.
class MyJob < ApplicationJob
  retry_on Net::OpenTimeout, wait: 10.seconds, attempts: 3
  discard_on Error::ApiError
  rescue_from(StandardError) { |e| Rollbar.error(e) }
end
  • Mailers
  • Use rescue_from to avoid bubble‑ups crashing deliveries:
class ApplicationMailer < ActionMailer::Base
  rescue_from Postmark::InactiveRecipientError, Postmark::InvalidEmailRequestError do
    # no-op / log
  end
end
  • Routing / 404
  • For APIs, keep 404 mapping at the controller boundary with rescue_from ActiveRecord::RecordNotFound.
  • For HTML, config.exceptions_app = routes + ErrorsController.
  • Middleware / Rack
  • For truly global concerns, use middleware. This is rarely necessary for controller-scoped API errors in Rails.
  • Validation vs. Exceptions
  • Use validations (ActiveModel/ActiveRecord) for expected user errors.
  • Raise exceptions for exceptional conditions (invariants violated, external systems fail unexpectedly).

6) Observability

  • Always log unexpected errors in the catch‑all (StandardError).
  • Add minimal context: client_id, request.fullpath, feature flags.
  • Avoid leaking stack traces or internal messages to clients. Send generic messages on 500s.

7) Testing

  • Unit test domain services to ensure they raise Error::ApiError (or return Failure).
  • Controller/request specs: assert status codes and JSON shapes for both happy path and error path.
  • Ensure before_action guards either render or raise as intended.

Applying this to our scenario

  • /lib/session/coupon_code.rb raises Error::Session::CouponCodeError on unknown/invalid discount values.
  • /app/controllers/api_controller.rb rescues that error and returns JSON:
  • { success: false, error: e.message } with a 422 (or via Error::ApiError base).

This converts prior 500s into clean API responses and keeps error handling centralized.

When to generalize vs. specialize

  • Keep a catch‑all rescue_from StandardError in ApiController to prevent 500s from leaking internals.
  • Still add specific handlers (or subclass Error::ApiError) for known cases to control the correct status code and message.
  • Do not replace everything with only StandardError—you’ll lose semantics and proper HTTP codes.

—

  • Key takeaways
  • Centralize API‐wide error handling in ApiController using specific handlers + a safe catch‑all.
  • Raise domain errors in models/libs; render JSON only in controllers.
  • Map common Rails exceptions to correct HTTP statuses; log unexpected errors.
  • Prefer Error::ApiError as a base for consistent message/status handling across the API.

Rails 8 + ActiveAdmin: The Propshaft vs Sprockets Dilemma 😵‍💫

ActiveAdmin traditionally requires Sprockets, but there are actually several alternatives and modern approaches. Let me break down your options:

ActiveAdmin Asset Pipeline Options:

Current Status (2025):

  • ActiveAdmin 3.x still primarily designed for Sprockets
  • It has SCSS files with imports, mixins, and variables that need preprocessing
  • The gem’s CSS compilation expects Sprockets’ asset compilation pipeline

Alternative Approaches:

1. Keep Sprockets (Current Choice)

Pros:

  • ✅ Fully supported, zero configuration issues
  • ✅ All ActiveAdmin features work out-of-the-box
  • ✅ Stable and well-tested

Cons:

  • ❌ Older, slower asset pipeline
  • ❌ More complex than Propshaft
  • ❌ Goes against Rails 8 defaults

2. Hybrid: Propshaft + Manual CSS for ActiveAdmin

We could try keeping Propshaft for our main app and handling ActiveAdmin CSS manually:

ActiveAdmin traditionally requires Sprockets, but the landscape is evolving. Here are your realistic options in 2025:

Current Situation:

ActiveAdmin 3.x: Requires Sprockets (stable)
ActiveAdmin 4.0 beta: Propshaft support is experimental/problematic
Rails 8 default: 🆕 Propshaft (faster, simpler)

https://github.com/activeadmin/activeadmin/releases

Our Options:

Option 1: Stay with Sprockets ⭐ (Recommended for now)

Pros:

  • ✅ Zero configuration issues
  • ✅ All ActiveAdmin features work perfectly
  • ✅ Battle-tested and stable

Cons:

  • ❌ Slower than Propshaft
  • ❌ More complex asset pipeline
  • ❌ Goes against Rails 8 defaults

Option 2: ActiveAdmin Assets Gem (Simplest alternative)

The activeadmin_assets gem was mentioned as a simple solution! Let me add this option:

# Add to Gemfile
gem 'activeadmin_assets'

Pros:

  • ✅ Zero Node.js dependency
  • ✅ Works with Propshaft
  • ✅ Pre-compiled ActiveAdmin assets
  • ✅ Simple one-line installation

Cons:

  • ❌ Can’t customize ActiveAdmin styles
  • ❌ Community-maintained (not official)

Option 3: ActiveAdmin 4.0 Beta + Propshaft ⚠️ (Experimental)

Based on the GitHub discussions, this is possible but complex:

# Rails 8 setup with Propshaft + ActiveAdmin v4 beta
rails new myapp -a propshaft
bundle add activeadmin -v=4.0.0beta15
bundle add cssbundling-rails -v "1.4.1"
bundle add tailwindcss-ruby -v "~> 3.4.17"
yarn add tailwindcss@^3.4.17  # ActiveAdmin uses TailwindCSS v3
rails generate active_admin:install
rails css:install:tailwind
yarn add @activeadmin/activeadmin@4.0.0-beta15
npm pkg set scripts.build:css="tailwindcss -i ./app/assets/stylesheets/active_admin.css -o ./app/assets/builds/active_admin.css --minify -c tailwind-active_admin.config.js"
./bin/dev  # Instead of rails server

Pros:

  • ✅ Modern asset pipeline (Propshaft)
  • ✅ ActiveAdmin v4 features

Cons:

  • ❌ Complex setup with many steps
  • ❌ Requires Node.js/Yarn (defeats the purpose)
  • ❌ Beta software (unstable)
  • ❌ TailwindCSS v3/v4 compatibility issues

Option 4: 🔄 Alternative Admin Gems

If you want to avoid the ActiveAdmin complexity entirely:

RailsAdmin:

gem 'rails_admin'
  • ✅ No asset pipeline issues
  • ✅ Works with Propshaft out of the box
  • ❌ Less customizable than ActiveAdmin

Trestle:

gem 'trestle'
  • ✅ Modern Bootstrap-based admin
  • ✅ Better Rails 8 compatibility
  • ❌ Smaller community

Adminterface (Deprecated):

  • 🚫 No longer maintained (as shown in search results)

🏆 My Recommendation:

For our production app: Stick with Sprockets + ActiveAdmin 3.x

Why?

  1. Stability – Battle-tested combination
  2. Zero configuration issues
  3. Full feature set available
  4. Easy maintenance

The performance difference between Propshaft and Sprockets won’t significantly impact your admin interface, which is typically used by a small number of internal users.

🔮 Future Outlook:

  • ActiveAdmin v4 will eventually have better Propshaft support
  • Rails community is working on solutions
  • Node.js dependency trend for complex CSS is becoming standard anyway

Bottom Line: Don’t let the asset pipeline take over the application preferences. Our current Sprockets setup is perfectly fine for an admin interface! 🎯

The Reality Check:

We completely replaced Propshaft with Sprockets for the entire application.

Current State:

  • ❌ Propshaft: Completely removed
  • ✅ Sprockets: Handles ALL assets (main app + admin)
  • ✅ Importmaps: Still working (unaffected)
  • ✅ Hotwire/Turbo: Still working (unaffected)

🏗️ How ActiveAdmin Works:

ActiveAdmin is NOT a Rails Engine. It integrates directly into your app:

  1. Routes: ActiveAdmin.routes(self) adds /admin routes to your app
  2. Assets: ActiveAdmin’s CSS/JS becomes part of your asset pipeline
  3. Controllers: ActiveAdmin generates controllers in your app’s namespace

It’s tightly coupled to your application, not isolated.

🤷‍♂️ So What Are Our Real Options?

Option 1: Accept Current Setup

What we have:

  • Modern Rails 8 with Importmaps + Hotwire ✅
  • Sprockets instead of Propshaft ❌ (but works fine)
  • Full-featured admin interface ✅

Option 2: Use activeadmin_assets Gem 

# Replace current ActiveAdmin setup
gem 'activeadmin_assets'  # Pre-compiled assets
gem 'propshaft'           # Back to Rails 8 default
  • ✅ Get Propshaft back
  • ✅ Keep Rails 8 defaults
  • ❌ Can’t customize admin styles

Option 3: Build Custom Admin

Keep your Rails 8 purity but build admin from scratch:

  • ✅ Pure Rails 8
  • ❌ Weeks of development time

🔍 What activeadmin_assets Actually Does:

The activeadmin_assets gem doesn’t replace ActiveAdmin – it provides pre-compiled static assets for ActiveAdmin to work with Propshaft.

But here’s the critical issue for you:

🚨 activeadmin_assets = NO Customization

If you use activeadmin_assets, you get:

  • ✅ ActiveAdmin functionality
  • ✅ Propshaft compatibility
  • ❌ ZERO ability to customize styles/interface

The assets are pre-compiled and frozen – you can’t modify colors, layouts, or styling.

Since We Want Customization:

We’re actually in the BEST setup possible right now!

Our Current Setup Gives You:

  • ✅ Full ActiveAdmin customization (styles, layouts, themes)
  • ✅ Modern Rails 8 (Importmaps, Hotwire, Turbo)
  • ✅ All ActiveAdmin features (filters, actions, forms)
  • ❌ Sprockets instead of Propshaft (minor trade-off)

Customization Examples We Can Do:

  • Custom CSS themes and colors
  • Layout modifications
  • Custom JavaScript behaviors
  • Brand styling and logos
  • Advanced form customizations

🎯 Reality Check:

There’s no solution that gives us:

  1. Full ActiveAdmin customization AND
  2. Propshaft AND
  3. Zero complexity

We have to pick 2 out of 3.

💡 My Honest Last Decision:

Keep our current setup! We’re already using:

  • Modern Rails 8 patterns (95% of your codebase)
  • Importmaps and Hotwire (exactly as intended)
  • Sprockets only affects asset serving (invisible to users)

The Propshaft vs Sprockets difference won’t affect your product’s success, but losing admin customization will limit our UX.

Guide: Integrating React ⚛️ into a Rails 8 Application – Part 3 | Start developing react

Let’s move on to quick development of more react components now. Before that let’s check what we have now and understand it very clear.

📄 File 1:

Our app/javascript/components/App.jsx file:

import React from 'react';

function App() {
  return (
    <div>
      <h1>React is working fine!</h1>
      <p>Welcome to Rails + React App</p>
    </div>
  );
}

export default App;

Let’s examine this React component step by step:

Line 1: Import React

import React from 'react';
  • import – ES6 module syntax to bring in external code
  • React – The main React library
  • from 'react' – Importing from the npm package named “react”
  • Why needed? Even though we use --jsx=automatic, we still import React for any hooks or React features we might use.

Function Component: Line 3-9

A React function component is a simple JavaScript function that serves as a building block for user interfaces in React applications. These components are designed to be reusable and self-contained, encapsulating a specific part of the UI and its associated logic.

function App() {
  return (
    <div>
      <h1>React is working fine!</h1>
      <p>Welcome to Rails + React App</p>
    </div>
  );
}

🔍 Breaking this down:

Line 3: Component Declaration

function App() {
  • function App() – This is a React Function Component
  • Component naming – Must start with capital letter (App, not app)
  • What it is – A JavaScript function that returns JSX (user interface)

Line 4-8: JSX Return

return (
  <div>
    <h1>React is working fine!</h1>
    <p>Welcome to Rails + React App</p>
  </div>
);
  • return – Every React component must return something
  • JSX – Looks like HTML, but it’s actually JavaScript
  • <div> – Must have one parent element (React Fragment rule)
  • <h1> & <p> – Regular HTML elements, but processed by React

Line 11: Export

export default App;
  • export default – ES6 syntax to make this component available to other files
  • App – The component name we’re exporting
  • Why needed? So application.js can import and use this component

📄 File 2:

Our app/javascript/application.js file:

// Entry point for the build script in your package.json
import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './components/App';

document.addEventListener('DOMContentLoaded', () => {
  const container = document.getElementById('react-root');

  if(container) {
    const root = createRoot(container);
    root.render(<App />);
  }
});

This is the entry point that connects React to your Rails app:

    Imports: Line 2-4

    import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './components/App';

    🔍 Breaking down each import:

    Line 2:

    import React from 'react';
    • Same as before – importing the React library

    Line 3:

    import { createRoot } from 'react-dom/client';
    • { createRoot } – Named import (notice the curly braces)
    • react-dom/client – ReactDOM library for browser/DOM manipulation
    • createRoot – New React 18+ API for rendering components to DOM

    Line 4:

    import App from './components/App';
    • App – Default import (no curly braces)
    • ./components/App – Relative path to our App component
    • Note: We don’t need .jsx extension, esbuild figures it out

    DOM Integration: Line 6-12

    document.addEventListener('DOMContentLoaded', () => {
  const container = document.getElementById('react-root');

  if(container) {
    const root = createRoot(container);
    root.render(<App />);
  }
});

    🔍 Step by step breakdown:

    Line 6:

    document.addEventListener('DOMContentLoaded', () => {
    • document.addEventListener – Standard browser API
    • 'DOMContentLoaded' – Wait until HTML is fully loaded
    • () => { – Arrow function (ES6 syntax)
    • Why needed? Ensures the HTML exists before React tries to find elements

    Line 7:

    const container = document.getElementById('react-root');
    • const container – Create a variable to hold the DOM element
    • document.getElementById('react-root') – Find HTML element with id="react-root"
    • Where is it? In your Rails view file: app/views/home/index.html.erb

    Line 9:

    if(container) {
    • Safety check – Only proceed if the element exists
    • Prevents errors – If someone visits a page without react-root element

    Line 10-11:

    const root = createRoot(container);
root.render(<App />);
    • createRoot(container) – Create a React “root” at the DOM element
    • root.render(<App />) – Render our App component inside the container
    • <App /> – JSX syntax for using our component (self-closing tag)

    🎯 Key React Concepts You Just Learned:

    1. Components

    • Functions that return JSX
    • Must start with capital letter
    • Reusable pieces of UI

    2. JSX

    • Looks like HTML, actually JavaScript
    • Must return single parent element
    • Processed by esbuild into regular JavaScript

    3. Import/Export

    • Default exports: export default App → import App from './App'
    • Named exports: export { createRoot } → import { createRoot } from 'package'

    4. React DOM

    • createRoot() – Modern way to mount React apps (React 18+)
    • render() – Display components in the browser

    5. Rails Integration

    • Rails serves the HTML page
    • React takes over the #react-root element
    • esbuild bundles everything together

    🚀 This pattern is the foundation of every React app! We create components, import them, and render them to the DOM.

    📚 Step-by-Step React Learning with Todo List

    Now let’s build a Todo List app step by step. I’ll explain each React concept thoroughly as we go. Here’s our learning roadmap:

    Step 1: Understanding JSX and Basic Component Structure

    First, let’s update our App.jsx to create the basic structure of our Todo app:

    import React from 'react';

function App() {
  return (
    <div className="todo-app">
      <h1>My Todo List</h1>
      <p>Let's learn React by building a todo app!</p>

      {/* This is a JSX comment */}
      <div className="todo-container">
        <h2>Add a new todo</h2>
        <input type="text" placeholder="Enter a todo..." />
        <button>Add Todo</button>

        <h2>My Todos</h2>
        <ul>
          <li>Learn React basics</li>
          <li>Build a todo app</li>
          <li>Master React hooks</li>
        </ul>
      </div>
    </div>
  );
}

export default App;

    🎯 Key Concepts Explained:

    JSX (JavaScript XML):

    • JSX lets you write HTML-like syntax directly in JavaScript
    • It’s a syntax extension for JavaScript, not actual HTML
    • JSX gets compiled to JavaScript function calls
    • You can use {} to embed JavaScript expressions inside JSX

    Important JSX Rules:

    • Use className instead of class (because class is a reserved word in JavaScript)
    • You can use single quotes for className values in JSX. Both work perfectly fine:
    // Both of these are valid:
<div className='todo-app'>    // Single quotes ✅
<div className="todo-app">    // Double quotes ✅

    Quote Usage in JSX/JavaScript:

    Single quotes vs Double quotes:

    • JavaScript treats them identically
    • It’s mostly a matter of personal/team preference
    • The key is to be consistent throughout your project

    Common conventions:

    // Option 1: Single quotes for JSX attributes
<div className='todo-app'>
  <input type='text' placeholder='Enter todo...' />
</div>

// Option 2: Double quotes for JSX attributes  
<div className="todo-app">
  <input type="text" placeholder="Enter todo..." />
</div>

// Option 3: Mixed (but stay consistent within each context)
const message = 'Hello World';  // Single for JS strings
<div className="todo-app">      // Double for JSX attributes

    When you MUST use specific quotes:

    // When the string contains the same quote type
<div className="It's a great day">        // Double quotes needed
<div className='He said "Hello"'>        // Single quotes needed

// Or use escape characters
<div className='It\'s a great day'>       // Escaping single quote
<div className="He said \"Hello\"">      // Escaping double quote

    💡 Tip: Many teams use tools like Prettier or ESLint to automatically format and enforce consistent quote usage across the entire project.

    • All tags must be closed (self-closing tags need / at the end)
    • JSX comments use {/* */} syntax
    • Return a single parent element (or use React Fragment <>...</>)

    Try updating our App.jsx with this code and see it in your browser!

    Step 2: Introduction to State with useState

    Now let’s add state to make our app interactive. State is data that can change over time.

    import React, { useState } from 'react';

function App() {
  // useState Hook - creates state variable and setter function
  const [todos, setTodos] = useState([
    { id: 1, text: 'Learn React basics', completed: false },
    { id: 2, text: 'Build a todo app', completed: false },
    { id: 3, text: 'Master React hooks', completed: true }
  ]);

  const [inputValue, setInputValue] = useState('');

  return (
    <div className="todo-app">
      <h1>My Todo List</h1>

      <div className="todo-container">
        <h2>Add a new todo</h2>
        <input 
          type="text" 
          placeholder="Enter a todo..." 
          value={inputValue}
          onChange={(e) => setInputValue(e.target.value)}
        />
        <button>Add Todo</button>

        <h2>My Todos ({todos.length})</h2>
        <ul>
          {todos.map(todo => (
            <li key={todo.id}>
              {todo.text} {todo.completed ? '✅' : '⏳'}
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
}

export default App;

    🎯 Key Concepts Explained:

    useState Hook:

    • useState is a React Hook that lets you add state to functional components
    • It returns an array with two elements: [currentValue, setterFunction]
    • const [todos, setTodos] = useState([]) creates a state variable todos and a function setTodos to update it
    • The initial value is passed as an argument to useState

    Controlled Components:

    • The input field is now “controlled” by React state
    • value={inputValue} makes the input show what’s in state
    • onChange={(e) => setInputValue(e.target.value)} updates state when user types

    Array.map() for Rendering Lists:

    • todos.map() transforms each todo into a JSX element
    • Each list item needs a unique key prop for React’s optimization
    • {todo.text} embeds the todo text using JSX expressions

    Try this code and notice how the input field now responds to typing!

    Step 3: Event Handling and Adding Todos

    Let’s make the “Add Todo” button work:

    import React, { useState } from 'react';

function App() {
  const [todos, setTodos] = useState([
    { id: 1, text: 'Learn React basics', completed: false },
    { id: 2, text: 'Build a todo app', completed: false },
    { id: 3, text: 'Master React hooks', completed: true }
  ]);

  const [inputValue, setInputValue] = useState('');

  // Function to add a new todo
  const addTodo = () => {
    if (inputValue.trim() !== '') {
      const newTodo = {
        id: Date.now(), // Simple ID generation
        text: inputValue,
        completed: false
      };

      setTodos([...todos, newTodo]); // Spread operator to add new todo
      setInputValue(''); // Clear the input field
    }
  };

  // Function to handle Enter key press
  const handleKeyPress = (e) => {
    if (e.key === 'Enter') {
      addTodo();
    }
  };

  return (
    <div className="todo-app">
      <h1>My Todo List</h1>

      <div className="todo-container">
        <h2>Add a new todo</h2>
        <input 
          type="text" 
          placeholder="Enter a todo..." 
          value={inputValue}
          onChange={(e) => setInputValue(e.target.value)}
          onKeyPress={handleKeyPress}
        />
        <button onClick={addTodo}>Add Todo</button>

        <h2>My Todos ({todos.length})</h2>
        <ul>
          {todos.map(todo => (
            <li key={todo.id}>
              {todo.text} {todo.completed ? '✅' : '⏳'}
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
}

export default App;

    🎯 Key Concepts Explained:

    Event Handlers:

    • onClick={addTodo} – function runs when button is clicked
    • onKeyPress={handleKeyPress} – function runs when key is pressed
    • Event handlers receive an event object (e) with information about the event

    State Updates:

    • setTodos([...todos, newTodo]) – creates a new array with all existing todos plus the new one
    • Important: Always create new arrays/objects instead of mutating existing ones
    • React compares old and new state to determine if re-render is needed

    Spread Operator (...):

    • ...todos spreads out all elements of the todos array
    • This is the React way to add items to an array in state

    Try adding new todos now!

    🎯 Function Syntax Options in JavaScript:

    const addTodo = () => {} is a function syntax – specifically an arrow function. Let me explain why it’s declared as const and the different ways to write functions in JavaScript.

    1. Function Declaration (Traditional)
    function addTodo() {
  // function body
}
    2. Function Expression with Arrow Function
    const addTodo = () => {
  // function body
};
    3. Function Expression (Traditional)
    const addTodo = function() {
  // function body
};

    🤔 Why use const for functions?

    Arrow functions are expressions, not declarations:

    // This is a DECLARATION - creates a function named addTodo
function addTodo() { }

// This is an EXPRESSION - creates a function and assigns it to a variable
const addTodo = () => { };

    Why const specifically?

    // ❌ Could be reassigned accidentally
let addTodo = () => { };
addTodo = "oops"; // Function is now gone!

// ❌ Could be reassigned accidentally  
var addTodo = () => { };
addTodo = null; // Function is now gone!

// ✅ Cannot be reassigned - prevents bugs
const addTodo = () => { };
addTodo = "something"; // ERROR: Assignment to constant variable

    📚 Key Differences:

    Function Declaration vs Arrow Function:

    // Function Declaration
function addTodo() {
  console.log("Adding todo");
}

// Arrow Function (assigned to const)
const addTodo = () => {
  console.log("Adding todo");
};

    Hoisting Behavior:

    // ✅ This works - function declarations are "hoisted"
sayHello(); // "Hello!"

function sayHello() {
  console.log("Hello!");
}

// ❌ This doesn't work - arrow functions are not hoisted
sayGoodbye(); // Error: Cannot access 'sayGoodbye' before initialization

const sayGoodbye = () => {
  console.log("Goodbye!");
};

    this Binding:

    // Function declaration has its own 'this'
function regularFunction() {
  console.log(this); // 'this' can change based on how it's called
}

// Arrow function inherits 'this' from surrounding scope
const arrowFunction = () => {
  console.log(this); // 'this' is inherited from parent scope
};

    🚀 In React Context:

    In React functional components, we typically use arrow functions with const because:

    1. Prevents accidental reassignment – our function won’t get overwritten
    2. Consistent with modern JavaScript – ES6+ standard
    3. Cleaner syntax – less verbose than traditional function expressions
    4. Better for event handlers – this behavior is more predictable

    All these are equivalent in React:

    // Option 1: Arrow function with const (most common)
const addTodo = () => {
  if (inputValue.trim() !== '') {
    // ... logic
  }
};

// Option 2: Traditional function declaration
function addTodo() {
  if (inputValue.trim() !== '') {
    // ... logic  
  }
}

// Option 3: Function expression with const
const addTodo = function() {
  if (inputValue.trim() !== '') {
    // ... logic
  }
};

    💡 Why React developers prefer arrow functions:

    1. Shorter syntax for simple functions
    2. Consistent variable declaration (everything uses const)
    3. No hoisting confusion – functions are defined before they’re used
    4. Better with modern tooling – ESLint, Prettier handle them well

    So yes, const addTodo = () => {} is definitely a function! It’s just a modern way to write functions that prevents accidental reassignment and has cleaner syntax.

    🎯 What is Hoisting?

    Hoisting is a fundamental JavaScript concept that can be confusing at first. Let me explain it clearly with examples.

    Hoisting is JavaScript’s behavior of moving declarations to the top of their scope during the compilation phase, before the code is executed.

    Think of it like JavaScript “hoists” (lifts up) your variable and function declarations to the top of their scope.

    📚 How Hoisting Works:

    Function Declarations are Hoisted:

    // This works even though we call the function before declaring it!
sayHello(); // Outputs: "Hello!"

function sayHello() {
  console.log("Hello!");
}

    Behind the scenes, JavaScript treats it like this:

    // JavaScript internally reorganizes it like this:
function sayHello() {
  console.log("Hello!");
}

sayHello(); // Now it makes sense!

    Variable Declarations (with var) are Hoisted:

    console.log(myVar); // Outputs: undefined (not an error!)
var myVar = "Hello";
console.log(myVar); // Outputs: "Hello"

    Behind the scenes:

    // JavaScript internally treats it like this:
var myVar; // Declaration is hoisted to the top
console.log(myVar); // undefined (declared but not assigned)
myVar = "Hello"; // Assignment stays in place
console.log(myVar); // "Hello"

    🚫 What is NOT Hoisted:

    let and const variables:

    // ❌ This throws an error!
console.log(myLet); // ReferenceError: Cannot access 'myLet' before initialization
let myLet = "Hello";

// ❌ This also throws an error!
console.log(myConst); // ReferenceError: Cannot access 'myConst' before initialization
const myConst = "Hello";

    Arrow Functions (Function Expressions):

    // ❌ This throws an error!
sayGoodbye(); // ReferenceError: Cannot access 'sayGoodbye' before initialization

const sayGoodbye = () => {
  console.log("Goodbye!");
};

    Function Expressions:

    // ❌ This throws an error!
myFunc(); // TypeError: myFunc is not a function

var myFunc = function() {
  console.log("Hello!");
};

    🎭 Visual Examples:

    Example 1: Function Declaration Hoisting

    // What you write:
console.log("1. Start");
myFunction(); // This works!
console.log("3. End");

function myFunction() {
  console.log("2. Inside function");
}

// Output:
// 1. Start
// 2. Inside function  
// 3. End

    Example 2: Variable Hoisting with var

    // What you write:
console.log("Value is:", myVar); // undefined
var myVar = 42;
console.log("Value is:", myVar); // 42

// What JavaScript internally does:
var myVar; // Hoisted to top
console.log("Value is:", myVar); // undefined
myVar = 42; // Assignment stays here
console.log("Value is:", myVar); // 42

    Example 3: Why let and const are different

    // Temporal Dead Zone
console.log("Before declaration");

// ❌ This area is the "Temporal Dead Zone" for myLet
console.log(myLet); // ReferenceError!

let myLet = "Hello"; // Declaration and initialization
console.log(myLet); // "Hello"

    🎯 Practical Implications:

    Why Function Declarations work everywhere:

    // This is valid JavaScript
function main() {
  helper(); // Can call helper before it's defined

  function helper() {
    console.log("Helper function");
  }
}

    Why Arrow Functions must be defined first:

    // ❌ This doesn't work
const main = () => {
  helper(); // Error! helper is not defined yet

  const helper = () => {
    console.log("Helper function");
  };
};

// ✅ This works
const main = () => {
  const helper = () => {
    console.log("Helper function");
  };

  helper(); // Now it works!
};

    💡 Best Practices:

    1. Use const and let instead of var to avoid hoisting confusion
    2. Define functions before using them (even though function declarations are hoisted)
    3. Use arrow functions for consistency and to avoid hoisting surprises
    4. Initialize variables when you declare them

    🔗 Back to Our React Example:

    // This is why we use const for arrow functions
const App = () => {
  // ✅ Good: Function defined before use
  const addTodo = () => {
    // function logic
  };

  // ❌ Bad: Would cause error if we tried to call it here
  // deleteTodo(); // Error!

  const deleteTodo = () => {
    // function logic
  };

  return (
    <div>
      <button onClick={addTodo}>Add</button>
      <button onClick={deleteTodo}>Delete</button>
    </div>
  );
};

    Hoisting is JavaScript’s way of making function declarations available throughout their scope, but it doesn’t apply to modern variable declarations (let, const) or arrow functions. That’s why we define our functions with const and make sure to declare them before we use them!

    Step 4: Toggling Todo Completion

    Let’s add the ability to mark todos as complete/incomplete:

    import React, { useState } from 'react';

function App() {
  const [todos, setTodos] = useState([
    { id: 1, text: 'Learn React basics', completed: false },
    { id: 2, text: 'Build a todo app', completed: false },
    { id: 3, text: 'Master React hooks', completed: true }
  ]);

  const [inputValue, setInputValue] = useState('');

  const addTodo = () => {
    if (inputValue.trim() !== '') {
      const newTodo = {
        id: Date.now(),
        text: inputValue,
        completed: false
      };

      setTodos([...todos, newTodo]);
      setInputValue('');
    }
  };

  // Function to toggle todo completion
  const toggleTodo = (id) => {
    setTodos(todos.map(todo => 
      todo.id === id 
        ? { ...todo, completed: !todo.completed } // Toggle completed status
        : todo // Keep todo unchanged
    ));
  };

  const handleKeyPress = (e) => {
    if (e.key === 'Enter') {
      addTodo();
    }
  };

  return (
    <div className="todo-app">
      <h1>My Todo List</h1>

      <div className="todo-container">
        <h2>Add a new todo</h2>
        <input 
          type="text" 
          placeholder="Enter a todo..." 
          value={inputValue}
          onChange={(e) => setInputValue(e.target.value)}
          onKeyPress={handleKeyPress}
        />
        <button onClick={addTodo}>Add Todo</button>

        <h2>My Todos ({todos.length})</h2>
        <ul>
          {todos.map(todo => (
            <li key={todo.id}>
              <span 
                onClick={() => toggleTodo(todo.id)}
                style={{ 
                  textDecoration: todo.completed ? 'line-through' : 'none',
                  cursor: 'pointer',
                  color: todo.completed ? '#888' : '#000'
                }}
              >
                {todo.text}
              </span>
              {todo.completed ? ' ✅' : ' ⏳'}
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
}

export default App;

    🎯 Key Concepts Explained:

    Array.map() for Updates:

    • todos.map() creates a new array where each todo is either updated or kept the same
    • todo.id === id ? { ...todo, completed: !todo.completed } : todo
    • This pattern is very common in React for updating items in arrays

    Conditional Rendering:

    • todo.completed ? '✅' : '⏳' – ternary operator for conditional display
    • textDecoration: todo.completed ? 'line-through' : 'none' – conditional styling

    Arrow Functions in JSX:

    • onClick={() => toggleTodo(todo.id)} – arrow function to pass arguments to event handlers
    • Without the arrow function, toggleTodo(todo.id) would execute immediately

    Now you can click on todos to toggle their completion status!

    🤔 What we’ve learned so far:

    1. ✅ JSX syntax and rules
    2. ✅ useState hook for state management
    3. ✅ Event handling (onClick, onChange, onKeyPress)
    4. ✅ Controlled components
    5. ✅ Array mapping for rendering lists
    6. ✅ Conditional rendering
    7. ✅ State updates with spread operator

    Next Steps: In the following steps, we’ll cover:

    • Deleting todos
    • Component composition (breaking into smaller components)
    • Props passing
    • Filtering todos
    • More advanced state management

    Let’s see in Part 4. Happy React Development! 🚀

    📦 Sprockets vs 🧵 Propshaft in Ruby on Rails 7/8 – What’s the Difference?

    When working with asset pipelines in Ruby on Rails 7 and 8, you might encounter Sprockets and Propshaft—two asset handling libraries. While both aim to serve static assets like JavaScript, CSS, images, and fonts, they do so in different ways.

    This post will walk you through what each does, how they differ, and when you might want to use one over the other.

    📦 What is Sprockets?

    Sprockets is the original Rails asset pipeline system, introduced way back in Rails 3.1. It allows developers to:

    • Concatenate and minify JavaScript and CSS
    • Preprocess assets using things like SCSS, CoffeeScript, ERB, etc.
    • Fingerprint assets for cache busting
    • Compile assets at deploy time

    It works well for traditional Rails applications where the frontend and backend are tightly coupled.

    Pros:

    • Mature and stable
    • Rich preprocessing pipeline (SCSS, CoffeeScript, ERB, etc.)
    • Supports advanced directives like //= require_tree .

    Cons:

    • Complex internal logic
    • Slower compilation times
    • Relies on a manifest file that can get messy
    • Tightly coupled with older Rails asset practices

    🧵 What is Propshaft?

    Propshaft is the newer asset pipeline introduced by the Rails team as an alternative to Sprockets. It focuses on simplicity and modern best practices. Propshaft was added as an optional asset pipeline starting in Rails 7 and is included by default in some new apps.

    Design Philosophy:
    Propshaft aims to work like a static file server with fingerprinting and logical path mapping, rather than a full asset compiler.

    Key Features:

    • Uses logical paths (e.g., /assets/application.css)
    • No preprocessing pipeline by default (but supports it via extensions like Tailwind or Sass)
    • Supports digesting (fingerprinting) of assets
    • Leaner and faster than Sprockets
    • Easier to integrate with modern JavaScript bundlers (like importmaps, esbuild, or webpack)

    Pros:

    • Lightweight and fast
    • Easier to debug
    • Works great with importmaps and Hotwire
    • Modern, forward-looking approach

    Cons:

    • No advanced preprocessing by default
    • Limited plugin ecosystem (still maturing)
    • Doesn’t support old Sprockets directives

    🔍 Key Differences at a Glance

    FeatureSprocketsPropshaft
    Introduced InRails 3.1Rails 7
    Default in RailsRails 6 and earlierOptional from Rails 7+
    Preprocessing SupportYes (SCSS, ERB, CoffeeScript, etc.)No (only raw assets by default)
    SpeedSlowerFaster
    Configuration ComplexityHigherMinimal
    Plugin EcosystemLarge and matureNew and growing
    Use With Importmaps/HotwireCan work, but heavierIdeal
    DebuggingHarder due to complexityEasier

    🧰 When Should You Use Sprockets?

    Choose Sprockets if:

    • You are upgrading a legacy Rails app
    • Your project already relies on Sprockets
    • You use heavy asset preprocessing
    • You need compatibility with gems that depend on Sprockets

    ⚡ When Should You Use Propshaft?

    Choose Propshaft if:

    • You are starting a new Rails 7/8 project
    • You use Importmaps or Hotwire/Turbo
    • You prefer faster and simpler asset handling
    • You don’t need complex preprocessing

    Propshaft pairs particularly well with modern frontend workflows like Tailwind CSS (via build tools) or StimulusJS (with importmaps).

    🛠️ Switching from Sprockets to Propshaft

    If you’re migrating, here are basic steps:

    1. Remove sprockets-rails gem from your Gemfile: # Gemfile # gem "sprockets-rails"
    2. Add propshaft: gem "propshaft"
    3. Update config/application.rb: config.assets.resolver = Propshaft::Resolver.new( paths: [Rails.root.join("app/assets")] )
    4. Remove app/assets/config/manifest.js (used by Sprockets)
    5. Move all assets to the correct logical paths under app/assets
    6. Use digested URLs as needed (asset_path("application.css") etc.)

    🧪 Real Example in Rails 8

    Here’s how your application.html.erb might look using Propshaft:

    <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
<%= javascript_include_tag "application", "data-turbo-track": "reload", defer: true %>

    And your app/assets/builds/application.css could be compiled via Tailwind or SCSS using a toolchain.

    🧠 Final Thoughts

    Sprockets has served Rails well for over a decade, but Propshaft is the new lightweight future. If you’re starting fresh, Propshaft is a strong choice, especially when used alongside Hotwire, Importmaps, or modern JS bundlers.

    However, don’t feel pressured to switch if your current Sprockets setup works fine—Rails continues to support both.

    ✨ TL;DR

    • Sprockets = older, feature-rich, best for legacy apps
    • Propshaft = newer, minimal, better for modern workflows

    Choose based on your app’s needs and complexity. Cheers! 🚀