[Rendering] Custom renderer support #234

[anuj-pal27]

Design Proposal: Custom Renderers

Public API

I'll keep the interface as proposed in the issue. The one addition I'd make is an optional status: keyword on every generated render_<name> method, to stay consistent with how render json: and render plain: already work.

Registration looks like this:

Rage.configure do
  config.renderer(:phlex) do |object, **options|
    headers["content-type"] = "text/html"
    object.new(**options).call
  end

  config.renderer(:csv) do |object, delimiter: ","|
    headers["content-type"] = "text/csv"
    CSV.generate(object, col_sep: delimiter)
  end
end

And usage in a controller:

class ArticlesController < RageController::API
  def index
    render_phlex MyComponent, articles: Article.all
  end

  def export
    render_csv my_csv_data, delimiter: ";", status: :ok
  end
end

The status: keyword is handled by the generated method itself — it never gets passed into the renderer block. So your renderer block stays clean and focused, and you can still set a custom status code whenever you need one.

---

How renderer procs will be stored

A @renderers hash on Rage::Configuration, keyed by renderer name (as a symbol), holding the generated dynamic method name:

def initialize
  # ...existing init...
  @renderers = {}
end

attr_reader :renderers

def renderer(name, &block)
  raise ArgumentError, "renderer requires a block" unless block_given?
  name = name.to_sym
  if @renderers.key?(name)
    raise ArgumentError, "a renderer named :#{name} is already registered"
  end
  dynamic_method_name = RageController::API.define_dynamic_method(block)
  @renderers[name] = dynamic_method_name
end

---

How controller methods will be defined

At the end of Rage.configure, the framework calls config.__finalize. That's where we loop through the registered renderers and define the corresponding methods on RageController::API.

Instead of using instance_exec on every request, we follow the same pattern Rage already uses for before_action, after_action, and rescue_from — convert the block into a named method once at boot time using define_dynamic_method, then generate the render_<name> method as a string using class_eval that just calls that named method directly:

# already exists in lib/rage/controller/api.rb
def define_dynamic_method(block)
  name = @@__dynamic_name_seed.next.join
  define_method("__rage_dynamic_#{name}", block)
end

# inside __finalize in lib/rage/configuration.rb
@renderers.each do |name, dynamic_method_name|
  method_name = :"render_#{name}"

  if RageController::API.method_defined?(method_name)
    raise ArgumentError,
      "cannot register renderer :#{name} — `#{method_name}` is already defined"
  end

  RageController::API.class_eval <<~RUBY
    def render_#{name}(*args, status: nil, **kwargs)
      raise "Render was called multiple times in this action" if @__rendered

      result = #{dynamic_method_name}(*args, **kwargs)

      unless @__rendered
        @__rendered = true
        @__body << result.to_s
        @__status = if status.is_a?(Symbol)
          ::Rack::Utils::SYMBOL_TO_STATUS_CODE[status]
        else
          status || 200
        end
      end
    end
  RUBY
end

This follows the exact same pattern that render json: and render plain: use — guard against double renders via @__rendered, append to @__body, resolve status symbols through Rack::Utils::SYMBOL_TO_STATUS_CODE, and default to 200.

---

Execution context

Since we use define_dynamic_method to convert the block into a named method on RageController::API, the block naturally runs with self being the controller instance. So inside any renderer block, you have access to:

• headers — to set content type
• request — to inspect incoming headers (important for Inertia's X-Inertia detection)
• params, cookies, session — if you ever need them

This is the same approach the codebase already uses for before_action and after_action blocks, so there's nothing new here mechanically.

---

Return value semantics

Whatever the renderer block returns becomes the response body by default. The generated method checks @__rendered after the block runs — not before. This means two cases are supported naturally:

Simple case (Phlex, CSV) — block just returns a string:

config.renderer(:phlex) do |object|
  headers["content-type"] = "text/html"
  object.call  # returns a string, framework puts it in body
end

Advanced case (SSE) — block calls render directly:

config.renderer(:sse) do |stream|
  render sse: stream  # render handles everything itself
end

Both cases handled by this pattern:

result = dynamic_method_name(*args, **kwargs)

unless @__rendered
  # render was NOT called inside the block
  # so treat the return value as the body
  @__rendered = true
  @__body << result.to_s
  @__status = status || 200
end
# if @__rendered is already true here,
# render was called inside the block — we do nothing

So the default behavior stays the same — block returns a string, framework handles the rest. But now streaming renderers can also call render directly inside the block without hitting a double render error.

---

Edge cases

Duplicate names — fail at registration time with a clear ArgumentError. Better to blow up at boot than to silently overwrite a renderer:

config.renderer(:phlex) { ... }
config.renderer(:phlex) { ... }  # => ArgumentError: a renderer named :phlex is already registered

Collision with existing methods — before calling class_eval, we check RageController::API.method_defined?(:"render_#{name}"). This prevents accidentally clobbering any current or future framework methods.

Code reloading in development — this isn't really a concern. RageController::API lives inside the gem, not under app/, so Zeitwerk never touches it. Methods defined on the base class at boot time survive reloads. User-defined subclasses like ArticlesController do get reloaded, but they inherit render_phlex from the base class through normal Ruby inheritance — no special handling needed.

No block given — raise ArgumentError immediately at the config.renderer call.

Proc returns nil — result.to_s gives "", which means an empty body with status 200. That's consistent with how render plain: nil behaves today.

---

Files to change

The only file that needs to be touched is lib/rage/configuration.rb — we add the renderer method, the @renderers hash, and the class_eval loop inside __finalize. Nothing in the router, code loader, or middleware needs to change.

Tests should cover the main scenarios: registering a renderer, calling it from a controller, the status: keyword, duplicate name errors, method name conflicts, making sure the block has access to controller context, nil return values, SSE rendering via render inside the block, and that subclasses properly inherit the generated methods.

Happy to adjust anything here based on feedback. Let me know if anything needs more discussion and I'll get started on the implementation once this is approved.

---

Inertia.js compatibility

Since renderer procs have full controller context, the Inertia use case works naturally:

config.renderer(:inertia) do |component, props: {}|
  if request.headers["X-Inertia"]
    headers["content-type"] = "application/json"
    headers["x-inertia"] = "true"
    { component:, props:, url: request.url }.to_json
  else
    headers["content-type"] = "text/html"
    InertiaPage.render(component, props)
  end
end

Controllers just call render_inertia MyComponent, props: { ... } — clean and simple.

---

Happy to adjust anything here based on feedback. Let me know if anything needs more discussion and I'll get started on the implementation once this is approved.

[rsamoilov]

Hi @anuj-pal27

This looks amazing! I really like the addition of the centralised status keyword!

Return value semantics

I agree that treating the result of the renderer block as the response body is probably the optimal approach. What if we also allowed to call render inside of it as a way to, for example, render SSE streams?

How controller methods will be defined

Rage relies on dynamic code generation a lot. Is there a way to avoid using instance_exec and instead build a method with the body of the proc? How complex is this approach?

A @renderers hash on Rage::Configuration, keyed by renderer name (as a symbol), holding the block:

We would also need to support objects that respond to call as renderers. For example, the following class would render ERB views while also maintaining a cache of templates:

class ERBRenderer
  def initialize
    @templates_cache = {}
  end

  def call(path)
    @templates_cache[path] ||= ERB.new(Rage.root.join("app/views/{path}.html.erb").read)
    @templates_cache[path].result(binding)
  end
end

# register
Rage.configure do
  config.renderer :erb, ERBRenderer.new
end

[anuj-pal27]

Thanks for the feedback @rsamoilov ! I'll spend some time digging into the codebase — mainly to understand how Rage handles dynamic code generation, how SSE rendering works internally, and how to support callable objects as renderers. Once I have a better understanding of all of this I'll come back with an updated proposal!

[anuj-pal27]

hii @rsamoilov, I've gone through all the points and here's what I'm thinking:

1. Return value semantics — instead of pre-setting @__rendered before the block runs, we check it after. Here's how both cases work:

Simple case (Phlex, CSV) — block just returns a string:

config.renderer(:phlex) do |object|
  headers["content-type"] = "text/html"
  object.call  # returns a string, framework puts it in body
end

Advanced case (SSE) — block calls render directly:

config.renderer(:sse) do |stream|
  render sse: stream  # render handles everything itself
end

Both cases are handled by this pattern:

result = dynamic_method_name(*args, **kwargs)

unless @__rendered
  # render was NOT called inside the block
  # so treat the return value as the body
  @__rendered = true
  @__body << result.to_s
  @__status = status || 200
end
# if @__rendered is already true here,
# render was called inside the block — we do nothing

So the default behavior stays the same — block returns a string, framework handles the rest. But now streaming renderers can also call render directly inside the block without hitting a double render error..

2. Avoiding instance_exec — I looked at how Rage already handles this in lib/rage/controller/api.rb.
   There's a method called define_dynamic_method which converts a block into a named method on the controller class:

# already exists in lib/rage/controller/api.rb
def define_dynamic_method(block)
  name = @@__dynamic_name_seed.next.join
  define_method("__rage_dynamic_#{name}", block)
end

Rage already uses this pattern for before_action, after_action, and rescue_from — instead of storing the block and calling it with instance_exec on every request, it converts the block into a named method once at boot time and just calls that method directly.

So instead of this:

# what we had before — instance_exec on every request
result = instance_exec(*args, **kwargs, &block)

We can do this:

# convert block into a named method ONCE at boot time
dynamic_method_name = RageController::API.define_dynamic_method(block)

# then generate render_phlex that just calls that named method directly
RageController::API.class_eval <<~RUBY
  def render_#{name}(*args, status: nil, **kwargs)
    result = #{dynamic_method_name}(*args, **kwargs)
    # ...
  end
RUBY

The complexity is low since this pattern already exists in the codebase — we're just applying it to custom renderers.

3. Callable objects — I'll update config.renderer to accept either a block or any object that responds to call. The main thing I want to confirm is — callable objects like ERBRenderer won't have direct access to headers, request etc. since they live outside the controller context. They would just receive arguments and return a string. Is that acceptable or should we find a way to pass the controller instance to them as well?

I'll update the proposal with all of this once I get your thoughts on the callable objects context question!

[rsamoilov]

callable objects like ERBRenderer won't have direct access to headers, request etc. since they live outside the controller context

Fair. OK, let's ditch callable objects for v1 and only focus on procs.