RubyGems - inertia-rage - Versions diffs - 0.0.1 - Mend

inertia-rage 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

checksums.yaml +7 -0
data/.rspec +1 -0
data/.yardopts +1 -0
data/CHANGELOG.md +5 -0
data/CODE_OF_CONDUCT.md +10 -0
data/LICENSE.txt +21 -0
data/README.md +218 -0
data/Rakefile +12 -0
data/lib/inertia/configuration.rb +110 -0
data/lib/inertia/controller_helpers.rb +159 -0
data/lib/inertia/frontend.rb +161 -0
data/lib/inertia/inertia.rb +87 -0
data/lib/inertia/middleware/assets.rb +40 -0
data/lib/inertia/middleware/version.rb +36 -0
data/lib/inertia/props.rb +31 -0
data/lib/inertia/protocol_builder.rb +209 -0
data/lib/inertia/rage_extension.rb +48 -0
data/lib/inertia/renderer.rb +69 -0
data/lib/inertia/request_context.rb +85 -0
data/lib/inertia/rspec.rb +171 -0
data/lib/inertia/version.rb +5 -0
data/lib/inertia/vite_dev_server.rb +27 -0
data/lib/inertia-rage.rb +1 -0
metadata +77 -0

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a6b20a9b2fd94ff4fa3e0595f894f95c6fb59b8ea09f5565359c814bc755ce3
+  data.tar.gz: a3368121cb820f940c09199ad6ef3aed2006c5aeb5f7c41b00af848f26307eb5
+SHA512:
+  metadata.gz: 1cb1310953698b5fd1a5274ba43eda6ceca9b7abaf5dcf850b9e589646638f8c4182f2d2694b852fd08a375744e37d3de2fd99fe5904316ed92701687f658352
+  data.tar.gz: 4e55f0e48d08c6bd63be5ea53b79659564bc20ee012ac27662595c89b0102888aa6ad06e87d18fba365a26d44a2c02b9de3f92512699fcc1cff07bdae81605f5

data/.rspec ADDED Viewed

	@@ -0,0 +1 @@
1	+ --require spec_helper

data/.yardopts ADDED Viewed

	@@ -0,0 +1 @@
1	+ --no-private

data/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,5 @@
+## [Unreleased]
+## [0.1.0] - 2026-06-22
+- Initial release

data/CODE_OF_CONDUCT.md ADDED Viewed

@@ -0,0 +1,10 @@
+# Code of Conduct
+"inertia-rage" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+If you have any concerns about behaviour within this project, please contact us at ["developers@rage-rb.dev"](mailto:"developers@rage-rb.dev").

data/LICENSE.txt ADDED Viewed

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+Copyright (c) 2026 Roman Samoilov
+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 ADDED Viewed

@@ -0,0 +1,218 @@
+<p align="center"><img height="200" alt="logo" src="https://github.com/user-attachments/assets/470e237b-f947-47f1-882c-1b7191709f50" /></p>
+# Inertia Rage
+The official [Inertia.js](https://inertiajs.com) adapter for the [Rage](https://github.com/rage-rb/rage) framework.
+This gem handles Inertia page responses, provides flexible prop types, and integrates seamlessly with Vite.
+## Usage
+Create a Rage app and add the gem:
+```
+rage new my-app -d postgresql
+bundle add inertia-rage
+```
+Create a frontend project in any directory within your project's root or `app` folder:
+```
+npm create vite@latest app/frontend
+```
+Install the required packages and initialize your Inertia app. Refer to the Inertia documentation for [client-side setup](https://inertiajs.com/docs/v3/installation/client-side-setup).
+<details>
+<summary>If you are using React</summary>
+Vite's React template uses `root` as the container element id, but Inertia expects `app`. Update `index.html` accordingly:
+```diff
+<body>
+-  <div id="root"></div>
++  <div id="app"></div>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+```
+</details>
+Start the app:
+```
+rage s
+```
+Rage automatically starts the Vite dev server in development and pre-builds assets in other environments. In most cases, `rage s` is all you need to run your app.
+## Rendering
+Use `render inertia:` to render Inertia responses in your controller actions:
+```ruby
+class PostsController < ApplicationController
+  def index
+    render inertia: "Posts/Index", props: { posts: current_user.posts }
+  end
+end
+```
+Rage can also infer the component name from the current controller and action. The following will render the `Posts/Index` component:
+```ruby
+class PostsController < ApplicationController
+  def index
+    render inertia: { posts: current_user.posts }
+  end
+end
+```
+Redirects are supported via `redirect_to`, `redirect_back`, and `redirect_back_or_to`:
+```ruby
+class PostsController < ApplicationController
+  def create
+    Post.create!(post_params)
+    redirect_back fallback_location: "/"
+  end
+end
+```
+## Props
+Inertia Rage supports several prop types to optimize data loading and improve performance.
+### Lazy Props
+Define lazy props using procs:
+```ruby
+render inertia: {
+  user:,
+  posts: -> { user.posts }
+}
+```
+Lazy props are evaluated on the initial page load just like regular props. The difference emerges during partial reloads: lazy props are only evaluated when explicitly requested. For example, if a partial reload requests only `user`, the `posts` query is skipped entirely.
+### Deferred Props
+Deferred props are excluded from the initial page load and fetched automatically in a subsequent request:
+```ruby
+render inertia: {
+  user:,
+  comments: Inertia.deferred { user.build_comments_tree }
+}
+```
+Use deferred props for expensive operations that would otherwise slow down the initial page load.
+### Optional Props
+Optional props are never evaluated during the initial page load. The frontend must explicitly request them:
+```ruby
+render inertia: {
+  user:,
+  last_posted_at: Inertia.optional { user.posts.last.created_at }
+}
+```
+### Once Props
+Once props are cached by the frontend after their first evaluation. On subsequent requests, the cached value is used and the prop is not re-evaluated. Since Inertia resets the cache for once props that are absent from the page, you'll typically want to use them inside `inertia_share` blocks:
+```ruby
+class ApplicationController < RageController::API
+  inertia_share do
+    { permissions: Inertia.once { current_user.permissions } }
+  end
+end
+```
+## Shared Data
+Use `inertia_share` to share data across all Inertia responses:
+```ruby
+class ApplicationController < RageController::API
+  inertia_share do
+    { has_new_notifications: current_user.notifications.unread.exists? }
+  end
+end
+```
+`inertia_share` accepts the same arguments as [`before_action`](https://api.rage-rb.dev/RageController/API#before_action-class_method):
+```ruby
+class DashboardsController < ApplicationController
+  inertia_share if: :user_signed_in?, except: :destroy do
+    { all_dashboards: Dashboard.where.not(user: current_user) }
+  end
+end
+```
+## Testing with RSpec
+The gem provides an [`inertia`](https://inertia-api.rage-rb.dev/Inertia/RSpec/TestResponse) helper for testing Inertia responses. Require `inertia/rspec` in your request specs to access it:
+```ruby
+require "inertia/rspec"
+RSpec.describe UsersController, type: :request do
+  it "renders user posts" do
+    get "posts"
+    expect(inertia.component).to eq("Posts/Index")
+    expect(inertia.props).to have_key(:posts)
+  end
+end
+```
+Partial reloading is supported via the [`inertia` option](https://inertia-api.rage-rb.dev/Inertia/RSpec/RequestHelpers.html) on the `get` method:
+```ruby
+require "inertia/rspec"
+RSpec.describe UsersController, type: :request do
+  it "renders post comments" do
+    get "posts/1", inertia: { only: :comments }
+    expect(inertia.props.keys).to eq(:comments)
+  end
+end
+```
+## Configuration
+Use `Inertia.configure` to customize the default behavior:
+```ruby
+Inertia.configure do |config|
+  config.build_on_start = false
+  config.dev_server.port = 5000
+end
+```
+See the [API documentation](https://inertia-api.rage-rb.dev/Inertia/Configuration.html) for the complete list of configuration options.
+## Learn More
+- [Props API Reference](https://inertia-api.rage-rb.dev/Inertia)
+- [Controller API Reference](https://inertia-api.rage-rb.dev/Inertia/ControllerHelpers.html)
+- [Configuration API Reference](https://inertia-api.rage-rb.dev/Inertia/Configuration.html)
+## Contributing
+Bug reports and pull requests are welcome on GitHub at https://github.com/rage-rb/inertia-rage. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/rage-rb/inertia-rage/blob/master/CODE_OF_CONDUCT.md).
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+## Code of Conduct
+Everyone interacting in the Inertia::Rage project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/rage-rb/inertia-rage/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile ADDED Viewed

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+require "bundler/gem_tasks"
+require "minitest/test_task"
+Minitest::TestTask.create
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+task default: %i[test rubocop]

data/lib/inertia/configuration.rb ADDED Viewed

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+module Inertia
+  ##
+  # Stores global configuration options for the Inertia integration.
+  #
+  # @example Configure via block
+  #   Inertia.configure do |config|
+  #     config.frontend_path = "client"
+  #     config.build_path = "public/dist"
+  #     config.build_on_start = false
+  #
+  #     config.dev_server.host = "0.0.0.0"
+  #     config.dev_server.port = 3000
+  #   end
+  #
+  class Configuration
+    # @private
+    def initialize
+      @build_on_start = !Rage.env.development?
+    end
+    # Set whether to build frontend assets on server start.
+    #
+    # @param value [Boolean]
+    # @see #build_on_start?
+    def build_on_start=(value)
+      @build_on_start = value
+    end
+    # Returns whether frontend assets should be built when the server starts.
+    #
+    # Defaults to `true` in non-development environments.
+    #
+    # @return [Boolean]
+    def build_on_start?
+      !!@build_on_start
+    end
+    # Returns the configured frontend directory path.
+    #
+    # @return [Pathname, nil]
+    # @see #frontend_path=
+    def frontend_path
+      @frontend_path
+    end
+    # Sets the path to the frontend application directory.
+    #
+    # When set, this overrides automatic Vite config detection. The path should
+    # be relative to the application root.
+    #
+    # @param path [String] path relative to the application root
+    def frontend_path=(path)
+      @frontend_path = Rage.root.join(path)
+    end
+    # Returns the configured build output path.
+    #
+    # @return [Pathname, nil]
+    # @see #build_path=
+    def build_path
+      @build_path
+    end
+    # Sets the path where built frontend assets are located.
+    #
+    # When set, this overrides the default `dist` directory inside {#frontend_path}.
+    # The path should be relative to the application root.
+    #
+    # Building directly into `public/` is not supported because a root-level
+    # `index.html` would intercept all requests to the application's `/` endpoint.
+    # Use a nested directory instead, e.g., `public/dist`.
+    #
+    # @param path [String] path relative to the application root
+    # @raise [ArgumentError] if path resolves to the public directory root
+    # @note This setting should be paired with updating the `build.outDir` option in your Vite config.
+    def build_path=(path)
+      @build_path = Rage.root.join(path)
+      if @build_path == Rage.root.join("public")
+        raise ArgumentError, "build_path cannot be set to public/; use a nested directory instead, e.g., public/dist"
+      end
+    end
+    # Returns the dev server configuration.
+    #
+    # @return [DevServer] the dev server configuration object
+    def dev_server
+      @dev_server ||= DevServer.new
+    end
+    ##
+    # Stores configuration for the Vite development server.
+    #
+    class DevServer
+      # @return [String] the hostname for the Vite dev server (default: "localhost")
+      attr_accessor :host
+      # @return [Integer] the port for the Vite dev server (default: 5173)
+      attr_accessor :port
+      # @private
+      def initialize
+        @host = "localhost"
+        @port = 5173
+      end
+    end
+  end
+end

data/lib/inertia/controller_helpers.rb ADDED Viewed

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+require "uri"
+module Inertia
+  ##
+  # Provides controller helper methods for Inertia.js integration.
+  module ControllerHelpers
+    module ClassMethods
+      # Shares data with all Inertia responses in a controller.
+      #
+      # This method registers a before_action that evaluates the given block
+      # in the controller instance context and merges the returned hash into
+      # the shared data. The shared data is automatically included in all
+      # Inertia responses rendered by the controller.
+      #
+      # Multiple `inertia_share` calls are cumulative - each block's data
+      # is merged into the existing shared data.
+      #
+      # @param options [Hash] options passed to `before_action` (e.g., `only:`, `except:`, `if:`, `unless:`)
+      # @yield Block evaluated in controller context that returns a Hash of data to share
+      # @yieldreturn [Hash] the data to merge into the shared props
+      #
+      # @example Share data for all actions
+      #   class ApplicationController < RageController::API
+      #     inertia_share do
+      #       { current_user: current_user&.as_json }
+      #     end
+      #   end
+      #
+      # @example Share data only for specific actions
+      #   class UsersController < ApplicationController
+      #     inertia_share only: [:index, :show] do
+      #       { permissions: current_user.permissions }
+      #     end
+      #   end
+      #
+      # @example Share data conditionally
+      #   class DashboardController < ApplicationController
+      #     inertia_share if: :user_signed_in? do
+      #       { notifications: current_user.unread_notifications }
+      #     end
+      #   end
+      def inertia_share(**options, &block)
+        raise ArgumentError, "inertia_share requires a block" unless block
+        before_action(**options) do
+          data = instance_eval(&block)
+          return unless data
+          if self.inertia_shared_data
+            self.inertia_shared_data.merge!(data)
+          else
+            self.inertia_shared_data = data
+          end
+        end
+      end
+    end
+    # Redirects the client to the specified location.
+    #
+    # @param location [String] the URL to redirect to
+    # @param external [Boolean] whether to force an external (full page) redirect.
+    #   When `true`, the browser will perform a full page visit instead of an Inertia visit
+    #
+    # @example Basic redirect
+    #   redirect_to "/dashboard"
+    #
+    # @example Force an external redirect
+    #   redirect_to "https://example.com", external: true
+    def redirect_to(location, external: false)
+      if external
+        headers["x-inertia-location"] = location
+        head 409
+        return
+      end
+      head(request.get? || request.post? ? 302 : 303)
+      headers["location"] = location
+    end
+    # Redirects the client back to the referring page, with a fallback location.
+    #
+    # @param fallback_location [String] the URL to redirect to if there is no referer
+    # @param external [Boolean] whether to force an external (full page) redirect.
+    #   When `true`, the browser will perform a full page visit instead of an Inertia visit
+    #
+    # @example Redirect back with a fallback
+    #   redirect_back fallback_location: "/dashboard"
+    #
+    # @see #redirect_back_or_to
+    def redirect_back(fallback_location:, external: false)
+      redirect_back_or_to fallback_location, external:
+    end
+    # Redirects the client back to the referring page, or to the specified fallback location.
+    #
+    # @param fallback_location [String] the URL to redirect to if there is no referer
+    # @param external [Boolean] whether to force an external (full page) redirect.
+    #   When `true`, the browser will perform a full page visit instead of an Inertia visit
+    #
+    # @example Redirect back or to a fallback
+    #   redirect_back_or_to "/dashboard"
+    #
+    # @example Force an external redirect
+    #   redirect_back_or_to "/dashboard", external: true
+    def redirect_back_or_to(fallback_location, external: false)
+      referer = request.env["HTTP_REFERER"]
+      if referer
+        redirect_to referer, external:
+      else
+        redirect_to fallback_location, external:
+      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.
+    #
+    # This method is called by the framework to enrich log entries with
+    # request parameters. Parameters are only included in development mode
+    # to avoid logging sensitive data in production.
+    def append_info_to_payload(context)
+      context[:params] = params if Rage.env.development?
+    end
+    def protect_from_csrf
+      # safe methods are always allowed
+      method = request.env["REQUEST_METHOD"]
+      return if method == "GET" || method == "HEAD" || method == "OPTIONS"
+      sec_fetch_site = request.env["HTTP_SEC_FETCH_SITE"]
+      return if sec_fetch_site == "same-origin" || sec_fetch_site == "none"
+      # check the Origin header
+      if sec_fetch_site.nil?
+        origin = request.env["HTTP_ORIGIN"]
+        # either the request is same-origin or not a browser request
+        return unless origin
+        begin
+          origin_host = URI(origin).authority
+          return if origin_host == request.env["HTTP_HOST"]
+        rescue URI::InvalidURIError
+          # fallthrough
+        end
+      end
+      render plain: "CSRF rejected", status: 403
+    end
+  end
+end