inertia-rage 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b02bfd40eee71d4f47b7aa88f120895a078d8f08adfef18002172e9ce7e5a988
-  data.tar.gz: de0d2658ebc07bcbdfed14aa6d9fe2cc17ca1f8f35f1b17d49a9a28f34c788a1
+  metadata.gz: 9d633e20c984eefe3e5c928a6328e17964fb879dc285a81bcda592d9a57e9ea5
+  data.tar.gz: a8079309590a94cdb78cb91fe6b380aadb992b0ccd8816a7ff79cb4bcd48c640
 SHA512:
-  metadata.gz: f0add134abde83e42eb7a9137654b25a3b8f94d8bbb2f5e81b22b5fe2ee7d99c66cb8df059a4e2085d2752d064ffdb4a69af1c299844ff60474f3e3224d77bb0
-  data.tar.gz: ce8bcfa86c0a2eba062f04755b005ebfee024f4c6075373a109996f8e862d5b99132ef6692e8cae95475f1b49fd9f1c31657441f5f46c66a5c34d4bf012fb32d
+  metadata.gz: e3f2d8f819e89054d3c655eef9784b02f840f12fcf39a7bcadd952b4b5a01e965806d22fdd1baa20714cc8fc021fee44292cd3f2c6fe34a74d5e63e2ecccca58
+  data.tar.gz: dc09e729d8f5859faeef881184eb1fa5ec5b2863b2fcd45849ce02f75dcfd53fcf1d726cfaf92772984bd54dd712fbf87c169d1f46affea4404d7da41a1491ae

data/CHANGELOG.md

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

data/README.md

@@ -213,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) TODO
+- [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

@@ -83,6 +83,14 @@ 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

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
@@ -36,6 +41,15 @@ module Inertia
         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 = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inertia-rage
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Roman Samoilov
@@ -49,6 +49,8 @@ files:
 - 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