inertia-rage 0.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a6b20a9b2fd94ff4fa3e0595f894f95c6fb59b8ea09f5565359c814bc755ce3
-  data.tar.gz: a3368121cb820f940c09199ad6ef3aed2006c5aeb5f7c41b00af848f26307eb5
+  metadata.gz: 9d633e20c984eefe3e5c928a6328e17964fb879dc285a81bcda592d9a57e9ea5
+  data.tar.gz: a8079309590a94cdb78cb91fe6b380aadb992b0ccd8816a7ff79cb4bcd48c640
 SHA512:
-  metadata.gz: 1cb1310953698b5fd1a5274ba43eda6ceca9b7abaf5dcf850b9e589646638f8c4182f2d2694b852fd08a375744e37d3de2fd99fe5904316ed92701687f658352
-  data.tar.gz: 4e55f0e48d08c6bd63be5ea53b79659564bc20ee012ac27662595c89b0102888aa6ad06e87d18fba365a26d44a2c02b9de3f92512699fcc1cff07bdae81605f5
+  metadata.gz: e3f2d8f819e89054d3c655eef9784b02f840f12fcf39a7bcadd952b4b5a01e965806d22fdd1baa20714cc8fc021fee44292cd3f2c6fe34a74d5e63e2ecccca58
+  data.tar.gz: dc09e729d8f5859faeef881184eb1fa5ec5b2863b2fcd45849ce02f75dcfd53fcf1d726cfaf92772984bd54dd712fbf87c169d1f46affea4404d7da41a1491ae

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
-## [0.1.0] - 2026-06-22
+## [1.1.0] - 2026-09-15
+
+- Add support for SSR.
+
+## [1.0.0] - 2026-07-27
 
 - Initial release

data/README.md

@@ -8,6 +8,8 @@ This gem handles Inertia page responses, provides flexible prop types, and integ
 
 ## Usage
 
+### Server-side setup
+
 Create a Rage app and add the gem:
 
 ```
@@ -15,6 +17,15 @@ rage new my-app -d postgresql
 bundle add inertia-rage
 ```
 
+Update the parent controller in your `ApplicationController` from `RageController::API` to `RageController::Inertia` to get access to CSRF protection and redirect helpers:
+
+```ruby
+class ApplicationController < RageController::Inertia
+end
+```
+
+### Client-side setup
+
 Create a frontend project in any directory within your project's root or `app` folder:
 
 ```
@@ -202,7 +213,7 @@ See the [API documentation](https://inertia-api.rage-rb.dev/Inertia/Configuratio
 ## Learn More
 
 - [Props API Reference](https://inertia-api.rage-rb.dev/Inertia)
-- [Controller API Reference](https://inertia-api.rage-rb.dev/Inertia/ControllerHelpers.html)
+- [Controller API Reference](https://inertia-api.rage-rb.dev/RageController/Inertia.html)
 - [Configuration API Reference](https://inertia-api.rage-rb.dev/Inertia/Configuration.html)
 
 ## Contributing

data/lib/inertia/configuration.rb

@@ -90,6 +90,13 @@ module Inertia
       @dev_server ||= DevServer.new
     end
 
+    # Returns the SSR configuration.
+    #
+    # @return [Ssr] the SSR configuration object
+    def ssr
+      @ssr ||= Ssr.new
+    end
+
     ##
     # Stores configuration for the Vite development server.
     #
@@ -106,5 +113,48 @@ module Inertia
         @port = 5173
       end
     end
+
+    ##
+    # Stores configuration for server-side rendering.
+    #
+    class Ssr
+      # @return [Boolean] whether SSR is enabled
+      attr_accessor :enabled
+
+      # @return [String] the URL of the SSR server (default: `http://localhost:13714`)
+      attr_accessor :url
+
+      # @return [Pathname, nil] the path to the SSR build output
+      attr_accessor :build_path
+
+      # @private
+      def initialize
+        @url = "http://localhost:13714"
+      end
+
+      # Sets the path where SSR bundle is located.
+      #
+      # When set, this overrides the default `ssr` directory inside {Frontend.dist}.
+      # The path should be relative to the application root.
+      #
+      # @param path [String] path relative to the application root
+      # @raise [ArgumentError] if path resolves to the public directory
+      def build_path=(path)
+        candidate_path = Rage.root.join(path)
+        public_path = Rage.root.join("public")
+
+        if candidate_path.to_s.start_with?(public_path.to_s)
+          raise ArgumentError, "ssr.build_path cannot be inside public/"
+        end
+
+        @build_path = candidate_path
+      end
+
+      # @private
+      def local?
+        normalized = URI(@url).hostname.downcase
+        %w[localhost localhost. 0.0.0.0 ::1].include?(normalized) || normalized.start_with?("127.")
+      end
+    end
   end
 end

data/lib/inertia/frontend.rb

@@ -37,6 +37,26 @@ module Inertia
         @dist ||= Inertia.config.build_path || root.join("dist")
       end
 
+      # Returns the directory containing built SSR assets.
+      #
+      # Uses {Configuration::Ssr#build_path} if set, otherwise defaults to
+      # `dist/ssr` inside the frontend root.
+      #
+      # @return [Pathname] path to the build output directory
+      # @raise [RuntimeError] if no Vite config file is found
+      def ssr_dist
+        @ssr_dist ||= begin
+          path = Inertia.config.ssr.build_path || dist.join("ssr")
+          public_path = Rage.root.join("public")
+
+          if path.to_s.start_with?(public_path.to_s)
+            raise ArgumentError, "SSR build path cannot be inside public/; configure it explicitly via config.ssr.build_path"
+          end
+
+          path
+        end
+      end
+
       # Returns a version identifier for the frontend assets.
       #
       # Computes an MD5 hash of the Vite manifest or index.html to detect
@@ -76,6 +96,29 @@ module Inertia
         @package_runner
       end
 
+      # Returns the JavaScript runtime command.
+      #
+      # Detects the runtime by checking for lock files and returns
+      # the appropriate command to execute scripts.
+      #
+      # @return [String] runtime command (e.g., "node", "bun", "deno run")
+      # @raise [RuntimeError] if no supported runtime is detected
+      def runtime
+        @runtime ||= if root.join("package-lock.json").exist?
+          "node"
+        elsif root.join("pnpm-lock.yaml").exist?
+          "node"
+        elsif root.join("bun.lockb").exist? || root.join("bun.lock").exist?
+          "bun"
+        elsif root.join("yarn.lock").exist?
+          "yarn node"
+        elsif root.join("deno.lock").exist?
+          "deno run --allow-net --allow-env"
+        else
+          raise "No supported JavaScript runtime detected"
+        end
+      end
+
       # Renders the HTML layout with the Inertia page object embedded.
       #
       # In development, it fetches the layout from the Vite dev server and
@@ -122,7 +165,7 @@ module Inertia
           "from \"#{dev_server_url}/#{$2}\""
         end
 
-        inject_page_data(layout, data)
+        hydrate_layout(layout, data)
       end
 
       # Returns the cached static layout with page data.
@@ -131,13 +174,46 @@ module Inertia
       # @return [String] HTML with page data injected
       # @raise [RuntimeError] if index.html does not exist in build path
       def build_static_layout(data)
-        @layout ||= begin
+        @static_layout ||= begin
           layout = dist.join("index.html")
           raise "Production layout not found at #{layout}. Ensure the frontend has been built" unless layout.exist?
           layout.read
         end
 
-        inject_page_data(@layout, data)
+        hydrate_layout(@static_layout, data)
+      end
+
+      def hydrate_layout(layout, data)
+        if Inertia.config.ssr.enabled
+          ssr_layout = inject_ssr_data(layout, data)
+          return ssr_layout if ssr_layout
+        end
+
+        inject_page_data(layout, data)
+      end
+
+      def inject_ssr_data(layout, data)
+        ssr_data = Inertia::SSR::Client.render(data)
+
+        processed_layout = layout.sub(/<div\s[^>]*\bid=(["'])app\1[^>]*>\s*<\/div>/i) { ssr_data["body"] }
+        # the app container is not empty - fallback to CSR
+        return nil if processed_layout == layout
+
+        if (head = ssr_data["head"]).any?
+          processed_layout.sub!(/<head([^>]*)>/i) do |head_tag|
+            <<~HTML
+              #{head_tag}
+                #{ssr_data["head"].join}
+            HTML
+          end
+        end
+
+        processed_layout
+
+      rescue => e
+        Rage.logger.error("SSR render failed", exception: e.message)
+        Rage::Errors.report(e)
+        nil
       end
 
       # Injects the page object JSON into the HTML body.

data/lib/inertia/inertia.rb

@@ -7,7 +7,6 @@ require_relative "frontend"
 require_relative "renderer"
 require_relative "request_context"
 require_relative "protocol_builder"
-require_relative "controller_helpers"
 require_relative "configuration"
 require_relative "middleware/version"
 require_relative "middleware/assets"
@@ -84,4 +83,16 @@ module Inertia
   # @!endgroup
 
   autoload :ViteDevServer, "inertia/vite_dev_server"
+
+  module SSR
+    autoload :Client, "inertia/ssr/client"
+    autoload :Server, "inertia/ssr/server"
+  end
+
+  class SSRServerError < StandardError
+  end
+end
+
+module RageController
+  autoload :Inertia, "inertia/rage_controller/inertia"
 end

data/lib/inertia/{controller_helpers.rb → rage_controller/inertia.rb}

@@ -2,11 +2,9 @@
 
 require "uri"
 
-module Inertia
-  ##
-  # Provides controller helper methods for Inertia.js integration.
-  module ControllerHelpers
-    module ClassMethods
+module RageController
+  class Inertia < RageController::API
+    class << self
       # Shares data with all Inertia responses in a controller.
       #
       # This method registers a before_action that evaluates the given block
@@ -22,7 +20,7 @@ module Inertia
       # @yieldreturn [Hash] the data to merge into the shared props
       #
       # @example Share data for all actions
-      #   class ApplicationController < RageController::API
+      #   class ApplicationController < RageController::Inertia
       #     inertia_share do
       #       { current_user: current_user&.as_json }
       #     end
@@ -57,6 +55,10 @@ module Inertia
       end
     end
 
+    # @private
+    attr_accessor :inertia_shared_data
+    before_action :protect_from_csrf
+
     # Redirects the client to the specified location.
     #
     # @param location [String] the URL to redirect to
@@ -114,12 +116,6 @@ module Inertia
       end
     end
 
-    # @private
-    def self.included(klass)
-      klass.before_action :protect_from_csrf
-      klass.attr_accessor :inertia_shared_data
-    end
-
     private
 
     # Appends additional request information to the log payload.

data/lib/inertia/rage_extension.rb

@@ -15,6 +15,11 @@ module Inertia
       # Automatically start Vite dev server in development mode
       config.daemons << ViteDevServer if Rage.env.development?
 
+      # Automatically start the SSR server
+      after_initialize do
+        config.daemons << SSR::Server if Inertia.config.ssr.enabled && Inertia.config.ssr.local? && !Rage.env.development?
+      end
+
       # In production, serve prebuilt static assets via the public file server and Assets middleware
       unless Rage.env.development?
         config.public_file_server.enabled = true
@@ -30,18 +35,21 @@ module Inertia
       config.middleware.use Middleware::Version
     end
 
-    # Include ControllerHelpers to add support for `redirect_to` and other Inertia-specific methods
-    initializer "inertia.rage.controller_helpers" do
-      RageController::API.include ControllerHelpers
-      RageController::API.extend ControllerHelpers::ClassMethods
-    end
-
     # Prebuild frontend assets before launching the server in production
     before_server_start do
       if Inertia.config.build_on_start?
         puts "INFO: Building frontend"
         puts ""
         system("#{Frontend.package_runner} vite build", chdir: Frontend.root) || abort("ERROR: Frontend build failed")
+
+        if Inertia.config.ssr.enabled
+          if Inertia.config.ssr.local?
+            out_dir = Frontend.ssr_dist.relative_path_from(Frontend.root)
+            system("#{Frontend.package_runner} vite build --ssr --outDir #{out_dir}", chdir: Frontend.root) || abort("ERROR: SSR build failed")
+          else
+            puts "INFO: SSR server is remote - skipping SSR build"
+          end
+        end
       end
     end
   end

data/lib/inertia/ssr/client.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module Inertia
+  module SSR
+    ##
+    # HTTP client for communicating with the SSR server.
+    #
+    # Sends page data to the SSR server and receives rendered HTML
+    # containing the `head` and `body` fragments.
+    #
+    class Client
+      class << self
+        # Renders the Inertia page data on the SSR server.
+        #
+        # @param data [Hash] the Inertia page object to render
+        # @return [Hash] parsed response containing "head" and "body" keys
+        def render(data)
+          response = begin
+            Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", open_timeout: 1, read_timeout: 1) do |http|
+              http.post(uri.request_uri, data.to_json, "Content-Type" => "application/json")
+            end
+          rescue => e
+            raise Inertia::SSRServerError, e
+          end
+
+          unless response.code == "200"
+            raise Inertia::SSRServerError, "Request failed with status #{response.code}: #{response.body}"
+          end
+
+          JSON.parse(response.body)
+        end
+
+        private
+
+        # Returns the URI for the SSR endpoint.
+        #
+        # In development, uses the Vite dev server's SSR endpoint.
+        # In production, uses the configured {Configuration::Ssr#url}.
+        #
+        # @return [URI] the SSR server URI
+        def uri
+          @uri ||= if Rage.env.development?
+            dev_server_config = Inertia.config.dev_server
+            URI("http://#{dev_server_config.host}:#{dev_server_config.port}/__inertia_ssr")
+          else
+            uri = URI(Inertia.config.ssr.url)
+            uri.path = "/render" if uri.path.empty? || uri.path == "/"
+            uri
+          end
+        end
+      end # class << self
+    end
+  end
+end

data/lib/inertia/ssr/server.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Inertia
+  module SSR
+    ##
+    # Background daemon that runs the Node.js SSR server.
+    #
+    class Server < Rage::Daemon
+      def perform
+        puts "INFO: Starting SSR server"
+
+        ssr_bundle = Frontend.ssr_dist.glob("*.{js,mjs}").first
+
+        unless ssr_bundle&.exist?
+          Rage.logger.fatal("Could not start SSR server - bundle not found")
+          return Rage::Daemon::Stop
+        end
+
+        @pid = Process.spawn("#{Frontend.runtime} #{ssr_bundle.relative_path_from(Frontend.root)}", chdir: Frontend.root)
+        Process.wait(@pid)
+      end
+
+      def cleanup
+        Process.kill("TERM", @pid) if @pid
+      rescue Errno::ESRCH
+      end
+    end
+  end
+end

data/lib/inertia/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Inertia
-  VERSION = "0.0.1"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inertia-rage
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Roman Samoilov
@@ -38,17 +38,19 @@ files:
 - Rakefile
 - lib/inertia-rage.rb
 - lib/inertia/configuration.rb
-- lib/inertia/controller_helpers.rb
 - lib/inertia/frontend.rb
 - lib/inertia/inertia.rb
 - lib/inertia/middleware/assets.rb
 - lib/inertia/middleware/version.rb
 - lib/inertia/props.rb
 - lib/inertia/protocol_builder.rb
+- lib/inertia/rage_controller/inertia.rb
 - lib/inertia/rage_extension.rb
 - lib/inertia/renderer.rb
 - lib/inertia/request_context.rb
 - lib/inertia/rspec.rb
+- lib/inertia/ssr/client.rb
+- lib/inertia/ssr/server.rb
 - lib/inertia/version.rb
 - lib/inertia/vite_dev_server.rb
 homepage: https://rage-rb.dev