liquid_response 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf11fe2f34626e9a1de07771d207a6fd41b305358f40251711ca1c0f8c97b7c2
+  data.tar.gz: e31a1a2426d569019b198f7b948d513cda3789fec8befe89f663cea2be0d33fb
+SHA512:
+  metadata.gz: a94e27ac67684b698d91b535e3c4945ac29c729afb772a18aa854f76d2da97fe63d63170df834231cb28defa02426a8f2f5fd23bf1cdea9faf1883c54f64cd85
+  data.tar.gz: c19d90983a3f2b216e0fa73a4cd759bce8c67a6baf92ce04ee6617643d1cce34c1660b85fac39f026b42131d9379e04c8b5f54414eeeaeed4d5d44288d7960f0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Elia Schito
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,266 @@
+# LiquidResponse
+
+Rails controller and view helpers for rendering [Liquid](https://shopify.github.io/liquid/) templates — designed for [Shopify App Proxy](https://shopify.dev/docs/apps/online-store/app-proxies) and any Rails app that serves Liquid markup to a storefront.
+
+## How it works
+
+Shopify's App Proxy lets your Rails app respond to storefront requests with Liquid templates, which Shopify then renders in the context of the live theme. `LiquidResponse` handles:
+
+- Registering the `liquid` MIME type with Rails
+- Telling Rails to prefer `liquid` over `html` for app proxy requests
+- Stripping `turbo-stream` from the Accept header (Turbo injects it everywhere; the proxy can't use it)
+- View helpers for building valid Liquid `{% render %}`, `{% assign %}`, and `{% capture %}` tags from ERB
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "liquid_response"
+```
+
+## Setup
+
+### 1. Register the MIME type
+
+```ruby
+# config/initializers/liquid_response.rb
+require "liquid_response"
+
+LiquidResponse.register_liquid_mime_type!
+```
+
+### 2. Include the controller helper
+
+```ruby
+class AppProxyController < ApplicationController
+  include LiquidResponse::ControllerHelper
+
+  allow_liquid_rendering_when_html_is_requested
+end
+```
+
+`allow_liquid_rendering_when_html_is_requested` installs a `before_action` that:
+- Strips `turbo-stream` from `request.formats`
+- Prepends `Mime[:liquid]` so Rails picks the `.liquid.erb` template
+
+### 3. Create `.liquid.erb` views
+
+Rails will look for `app/views/posts/show.liquid.erb` when the request format resolves to `liquid`. Write Liquid tags using the view helpers:
+
+```erb
+<%# app/views/posts/show.liquid.erb %>
+<%= render_liquid "my-app--post--card", title: @post.title, published: @post.published? %>
+```
+
+This outputs:
+
+```liquid
+{% render "my-app--post--card", title: "Hello World", published: true %}
+```
+
+## View helpers
+
+All helpers are available in views once `LiquidResponse::ControllerHelper` is included (it auto-includes `LiquidResponse::ViewHelper` as a helper module).
+
+### `render_liquid(snippet_name, **assigns)`
+
+Emits a Liquid `{% render %}` tag with the given assigns.
+
+```erb
+<%= render_liquid "my-app--product--card",
+      title: @product.title,
+      price: @product.price,
+      available: @product.available? %>
+```
+
+```liquid
+{% render "my-app--product--card", title: "Widget", price: 9.99, available: true %}
+```
+
+### `assign_liquid(variable_name, value)`
+
+Emits a `{% assign %}` tag. Useful for hoisting a value to Liquid scope before passing it to a snippet.
+
+```erb
+<%= assign_liquid :greeting, "Welcome" %>
+```
+
+```liquid
+{% assign greeting = "Welcome" %}
+```
+
+### `liquid_variable(name)`
+
+Returns a `LiquidVariable` object — a placeholder that renders as a bare Liquid variable name (no quotes). Pass it as an assign value when the variable already exists in Liquid scope.
+
+```erb
+{% assign products = collections.all.products %}
+<%= render_liquid "my-app--product--list", items: liquid_variable(:products) %>
+```
+
+```liquid
+{% render "my-app--product--list", items: products %}
+```
+
+### `liquid_capture(name, &block)`
+
+Wraps the block output in `{% capture %}` / `{% endcapture %}`.
+
+```erb
+<%= liquid_capture(:sidebar) do %>
+  <p>Some sidebar content</p>
+<% end %>
+```
+
+```liquid
+{% capture sidebar %}<p>Some sidebar content</p>{% endcapture %}
+```
+
+## Passing complex values
+
+### Strings, numbers, booleans, nil, dates, times, symbols
+
+Converted to their JSON equivalents automatically.
+
+```erb
+<%= render_liquid "my-app--order",
+      id: 42,
+      status: :pending,
+      placed_on: Date.today,
+      gift: false,
+      note: nil %>
+```
+
+```liquid
+{% render "my-app--order", id: 42, status: "pending", placed_on: "2026-05-26", gift: false, note: null %}
+```
+
+### Hashes (nested objects)
+
+Each Hash assign is promoted to an intermediate `{% assign %}` variable so Liquid receives it as an object.
+
+```erb
+<%= render_liquid "my-app--address--card",
+      address: {
+        street: @address.line1,
+        city:   @address.city,
+        zip:    @address.zip
+      } %>
+```
+
+```liquid
+{% assign h_address_a1b2c = null | default: street: "Via Roma 1", city: "Roma", zip: "00100" %}
+{% render "my-app--address--card", address: h_address_a1b2c %}
+```
+
+Nesting works recursively:
+
+```erb
+<%= render_liquid "my-app--subscription",
+      plan: {
+        name:     "Monthly",
+        interval: { unit: "week", count: 4 }
+      } %>
+```
+
+```liquid
+{% assign h_interval_x = null | default: unit: "week", count: 4 %}
+{% assign h_plan_y     = null | default: name: "Monthly", interval: h_interval_x %}
+{% render "my-app--subscription", plan: h_plan_y %}
+```
+
+### Arrays
+
+Arrays are converted to indexed hashes (Liquid has no native array literal):
+
+```erb
+<%= render_liquid "my-app--tag--list", tags: ["sale", "new"] %>
+```
+
+```liquid
+{% assign h_tags_z = null | default: 0: "sale", 1: "new" %}
+{% render "my-app--tag--list", tags: h_tags_z %}
+```
+
+### Custom objects — `as_liquid` protocol
+
+Any object that implements `as_liquid` is serialized through it. The method must return a `Hash`, a scalar, or another `as_liquid`-capable object.
+
+```ruby
+class Product
+  def as_liquid
+    { "title" => title, "price" => price.to_f, "available" => available? }
+  end
+end
+```
+
+```erb
+<%= render_liquid "my-app--product--card", product: @product %>
+```
+
+`LiquidResponse` ships with `as_liquid` on `String`, `Numeric`, `TrueClass`, `FalseClass`, `NilClass`, `Date`, `Time`, `Symbol`, `Array`, `Hash`, and `Data` — all the types you use day-to-day.
+
+### ActiveModel / Serializable objects
+
+Objects that respond to `serializable_hash` are converted automatically:
+
+```erb
+<%= render_liquid "my-app--user--card", user: current_user %>
+```
+
+### Mixing types
+
+Everything composes:
+
+```erb
+<%= render_liquid "my-app--portal",
+      customer_name: @customer.name,
+      logged_in:     true,
+      items:         liquid_variable(:cart_items),
+      address: {
+        city: @shipping_address.city,
+        zip:  @shipping_address.zip
+      } %>
+```
+
+## `liquid_routes` (app-level, not in the gem)
+
+The helper `liquid_routes` — which exposes Rails route helpers as a Liquid-usable hash — is intentionally **not** part of this gem. It depends on your app's routing conventions. Define it yourself in your base controller and expose it via `helper_method`:
+
+```ruby
+class AppProxyController < ApplicationController
+  include LiquidResponse::ControllerHelper
+  allow_liquid_rendering_when_html_is_requested
+
+  helper_method :liquid_routes
+
+  private
+
+  def liquid_routes
+    Rails.application.routes.routes
+      .filter_map do |route|
+        next unless route.name&.start_with?("my_app_proxy_")
+        [route.name.sub("my_app_proxy_", "") + "_url", route.path.spec.to_s.sub(/\([^)]*\)/, "")]
+      end
+      .sort.to_h
+  end
+end
+```
+
+Then in views:
+
+```erb
+<%= render_liquid "my-app--nav", routes: liquid_routes %>
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/liquid_response/controller_helper.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "liquid_response/view_helper"
+
+module LiquidResponse
+  module ControllerHelper
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def allow_liquid_rendering_when_html_is_requested
+        before_action do
+          # Strip turbo-stream from all positions — Turbo's Accept header lists it first,
+          # which causes Rails to select that format and return the wrong content type.
+          request.formats.reject! { |f| f.turbo_stream? }
+          html_like = request.formats.any? { |f| f.html? || f.all? }
+          request.formats.unshift Mime[:liquid] if html_like
+        end
+      end
+    end
+
+    included do
+      helper LiquidResponse::ViewHelper
+    end
+  end
+end

data/lib/liquid_response/core_ext.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "date"
+
+[String, Numeric, TrueClass, FalseClass, NilClass, Date, Time, Symbol].each do |klass|
+  klass.class_eval do
+    def as_liquid
+      self
+    end
+  end
+end
+
+Array.class_eval do
+  def as_liquid
+    map.with_index { |v, i| [i, v] }.to_h.as_liquid
+  end
+end
+
+Hash.class_eval do
+  def as_liquid
+    transform_values { it.respond_to?(:as_liquid) ? it.as_liquid : it }
+  end
+end
+
+Data.class_eval do
+  def as_liquid
+    to_h.as_liquid
+  end
+end

data/lib/liquid_response/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module LiquidResponse
+  class UnsupportedValueError < ArgumentError
+    attr_accessor :key, :value
+
+    def initialize(value, key = nil)
+      @value = value
+      @key = key
+      super("Can't convert value #{value.inspect} of type #{value.class} to a liquid-compatible format")
+    end
+
+    def message
+      key ? "Error converting value for key '#{key}': #{super}" : super
+    end
+  end
+end

data/lib/liquid_response/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LiquidResponse
+  VERSION = "0.1.0"
+end

data/lib/liquid_response/view_helper.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "json"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/object/json"
+require "liquid_response/errors"
+require "liquid_response/core_ext"
+
+module LiquidResponse
+  module ViewHelper
+    class LiquidBuffer
+      class LiquidVariable
+        def initialize(name)
+          @name = name.to_s
+          self.class.validate_name!(@name)
+        end
+
+        def self.validate_name!(name)
+          unless name.to_s.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*\z/)
+            raise ArgumentError, "Invalid Liquid variable name: #{name}"
+          end
+        end
+
+        attr_reader :name
+
+        def self.random(prefix = "var")
+          prefix = prefix.to_s.gsub(/[^a-zA-Z0-9]+/, "_")
+          prefix = "var" if prefix.blank? || prefix.match?(/\A\d/)
+          new("#{prefix}_#{SecureRandom.hex(5)}")
+        end
+
+        def inspect
+          "LiquidVariable(#{name})"
+        end
+
+        def as_liquid
+          self
+        end
+      end
+
+      def initialize
+        @lines = []
+      end
+
+      def line(liquid_line)
+        @lines << liquid_line
+        nil
+      end
+
+      def to_s
+        @lines.join("\n").html_safe
+      end
+
+      def render_liquid(name, **assigns)
+        assigns_liquid = ", #{liquid_arguments(assigns)}" unless assigns.blank?
+        line "{% render #{name.to_s.to_json}#{assigns_liquid} %}"
+      end
+
+      def assign_liquid(variable, value)
+        LiquidVariable.validate_name!(variable)
+
+        if value.is_a?(Hash)
+          value = "null | default: #{liquid_arguments(value, variable)}"
+        else
+          value = liquid_value(value, variable)
+        end
+
+        line "{% assign #{variable} = #{value} %}"
+      end
+
+      def liquid_arguments(assigns, _base_name = nil)
+        assigns.map { |k, v| "#{k}: #{liquid_value(v, k.to_s)}" }.join(", ")
+      end
+
+      def liquid_value(value, variable_name = nil)
+        if value.respond_to?(:as_liquid)
+          value = value.as_liquid
+        elsif value.respond_to?(:serializable_hash)
+          value = value.serializable_hash
+        end
+
+        value = case value
+        when String, Numeric, TrueClass, FalseClass, NilClass, Date, Time, Symbol
+          value.to_json
+        when LiquidVariable
+          value.name
+        when Hash
+          assign_name = LiquidVariable.random("h_#{variable_name}").name
+          assign_liquid(assign_name, value)
+          assign_name
+        else
+          raise UnsupportedValueError.new(value, variable_name)
+        end
+        value.html_safe
+      end
+    end
+
+    %i[render_liquid assign_liquid].each do |method_name|
+      define_method method_name do |*args, **kwargs|
+        LiquidBuffer.new.tap { _1.send(method_name, *args, **kwargs) }.to_s
+      end
+    end
+
+    def liquid_capture(name, &block)
+      safe_join(["{% capture #{name} %}".html_safe, capture(&block).html_safe, "{% endcapture %}".html_safe])
+    end
+
+    def liquid_variable(name)
+      LiquidBuffer::LiquidVariable.new(name)
+    end
+  end
+end

data/lib/liquid_response.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "liquid_response/version"
+require "liquid_response/errors"
+require "liquid_response/core_ext"
+require "liquid_response/view_helper"
+require "liquid_response/controller_helper"
+
+module LiquidResponse
+  def self.register_liquid_mime_type!
+    return if Mime::Type.lookup_by_extension(:liquid)
+
+    Mime::Type.register "application/liquid", :liquid
+  end
+end

data/sig/liquid_response.rbs

@@ -0,0 +1,4 @@
+module LiquidResponse
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: liquid_response
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Elia Schito
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: LiquidResponse provides Rails controller and view helpers for rendering
+  Liquid templates, designed for use with Shopify App Proxy and similar setups where
+  Rails serves Liquid markup to a storefront.
+email:
+- elia@schito.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/liquid_response.rb
+- lib/liquid_response/controller_helper.rb
+- lib/liquid_response/core_ext.rb
+- lib/liquid_response/errors.rb
+- lib/liquid_response/version.rb
+- lib/liquid_response/view_helper.rb
+- sig/liquid_response.rbs
+homepage: https://github.com/elia/liquid_response
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/elia/liquid_response
+  source_code_uri: https://github.com/elia/liquid_response
+  changelog_uri: https://github.com/nebulab/liquid_response/releases
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Render Liquid templates from Rails controllers and views
+test_files: []