inertia_hanami 0.1.0

data/README.md

@@ -0,0 +1,417 @@
+# InertiaHanami
+
+Server-side adapter implementing the [Inertia.js protocol](https://inertiajs.com/) for the
+[Hanami](https://hanamirb.org) web framework.
+
+## Installation
+
+Add the gem to your Hanami app's Gemfile in **both** the default and `:cli` groups. The `:cli`
+group is required for the `hanami generate inertia:install` command below to be available -
+Bundler's `Hanami::CLI::Bundler.require(:cli)` is what loads it before `hanami` dispatches
+commands:
+
+```ruby
+gem "inertia_hanami", groups: [:default, :cli]
+```
+
+Then run:
+
+```bash
+bundle install
+bundle exec hanami generate inertia:install
+```
+
+This scaffolds:
+
+- `config/providers/inertia.rb` - registers the gem's configuration with the app container.
+- `config.middleware.use InertiaHanami::Middleware::Version` / `::Redirects` / `::Csrf` in
+  `config/app.rb`.
+- `app/templates/layouts/app.html.erb` - the initial full-page-load layout, rendering
+  `<%= inertia_root(page: page) %>`.
+- `app/views/helpers.rb` - includes `InertiaHanami::Helper` so `inertia_root` is callable
+  unqualified from templates.
+- A sample page (`app/actions/inertia_example/show.rb`, `app/views/inertia_example/show.rb`,
+  `app/templates/inertia_example/show.html.erb`) plus a matching route in `config/routes.rb`.
+- `@inertiajs/*` frontend packages merged into `package.json` (or printed as `npm install`
+  guidance if no `package.json` exists yet).
+
+Pass `--framework=vue` or `--framework=svelte` to target a different Inertia client adapter
+(defaults to `react`), and `--force` to overwrite files it previously generated. Run
+`bundle exec hanami generate inertia:install --help` for details.
+
+Finally, run `npm install` (or yarn/pnpm) to install the frontend packages. Wiring up the JS
+entrypoint (Vite/`hanami-assets` config) is outside this gem's scope - it only manages the
+Ruby/server side of the Inertia protocol.
+
+### Additional app setup the generator doesn't do for you
+
+- **JSON body parsing.** Inertia's client sends `application/json` request bodies for
+  `post`/`put`/`patch`/`delete` visits and form submissions (except when uploading files, which
+  switch to `multipart/form-data`). Hanami doesn't parse JSON bodies into `params` out of the box,
+  so without this, `request.params` will be empty and any `params do ... end` contract will fail
+  validation on every request. Add to `config/app.rb`:
+
+  ```ruby
+  require "hanami/middleware/body_parser"
+
+  module MyApp
+    class App < Hanami::App
+      config.middleware.use Hanami::Middleware::BodyParser, :json
+      # ...
+    end
+  end
+  ```
+
+- **Sessions.** `errors`, `flash`, and CSRF protection are all no-ops until
+  `config.actions.sessions` is configured (see [Actions - Sessions](https://hanakai.org/learn/hanami/actions/sessions/)
+  for the setup, plus a `session_secret` app setting). `InertiaHanami::Middleware::Csrf` in
+  particular does nothing useful without sessions enabled.
+
+- **Client package versions.** This gem speaks the current Inertia protocol, which as of Inertia
+  v3 embeds the initial page via a `<script data-page="app" type="application/json">` tag rather
+  than a `data-page` attribute on the root `<div>` - `inertia_root` renders both. If you pin an
+  older `@inertiajs/*` client version, check that it still reads the script-tag form; very old
+  client versions only supported the div-attribute form and won't hydrate.
+
+## Usage
+
+Include `InertiaHanami::Action` in an action to speak the Inertia protocol from it. This skips
+Hanami's automatic view rendering for Inertia XHR requests, renders the Inertia page envelope for
+both XHR and full-page-load requests, and gives you `inertia_render`, `inertia_share`,
+`inertia_location`, and friends:
+
+```ruby
+module MyApp
+  module Actions
+    module Dashboard
+      class Show < MyApp::Action
+        include InertiaHanami::Action
+
+        def handle(req, res)
+          inertia_render "Dashboard/Show", props: { name: "Ada" }
+        end
+      end
+    end
+  end
+end
+```
+
+`inertia_render` accepts `component:` (implicit, first positional arg), `props:`, `url:` (defaults
+to the current request URL), `version:` (defaults to the configured asset version), and
+`encrypt_history:` / `clear_history:` (see below). It's usually cleanest to include
+`InertiaHanami::Action` once in a shared base action class rather than in every action.
+
+### Sharing props across actions
+
+`inertia_share` (class-level) declares props merged into every `inertia_render` call from that
+action class and its subclasses - handy on a base action for data every page needs:
+
+```ruby
+class ApplicationAction < MyApp::Action
+  include InertiaHanami::Action
+
+  inertia_share app_name: "My App"
+
+  # Block form is instance_exec'd at render time, so it can call other
+  # action instance methods (current_user, session, etc.).
+  inertia_share do
+    { current_user: current_user&.to_h }
+  end
+end
+```
+
+Call `inertia_share` again (with or without a block) from inside `#handle` to add props scoped to
+that single request instance only, without affecting other instances of the action:
+
+```ruby
+def handle(req, res)
+  inertia_share breadcrumbs: build_breadcrumbs(req)
+  inertia_render "Posts/Show"
+end
+```
+
+Both class- and instance-level shared props are merged in before the `props:` you pass directly to
+`inertia_render`, so a per-render prop always wins over a shared one with the same key.
+
+### Errors and flash
+
+Two props are auto-shared on every `inertia_render` call (only when the app has sessions enabled):
+
+- `flash` - the current request's flash messages, when there are any.
+- `errors` - validation errors stashed via `share_inertia_errors`, delivered once and then cleared
+  from the session. Mirrors inertia-rails' `redirect_to ..., inertia: { errors: ... }`:
+
+```ruby
+def handle(req, res)
+  form = PostForm.new(req.params)
+  return inertia_render("Posts/New") if req.get?
+
+  if form.invalid?
+    share_inertia_errors(form.errors)
+    res.redirect_to(routes.path(:new_post))
+    return
+  end
+
+  # ...
+end
+```
+
+Set `config.always_include_errors_hash = true` (see Configuration below) to always send an
+`errors: {}` prop even when nothing was stashed, instead of omitting the key entirely.
+
+### External redirects
+
+Inertia's XHR-driven visits can't follow a redirect to a different origin. `inertia_location(url)`
+handles this: on an Inertia request it sets `X-Inertia-Location` and responds `409` so the client
+performs a full browser visit; on a non-Inertia request it's a normal redirect:
+
+```ruby
+def handle(req, res)
+  inertia_location("https://example.com/checkout")
+end
+```
+
+### Encrypted history
+
+When enabled, the client encrypts its Inertia history state (useful for pages with sensitive data
+you don't want recoverable via the browser's back button after logout). Set the default globally
+via `config.encrypt_history` (see Configuration below), override it per action class with
+`encrypt_history`, or per instance/request by calling the instance method inside `#handle`:
+
+```ruby
+class Settings::Show < MyApp::Action
+  include InertiaHanami::Action
+
+  encrypt_history # defaults to true; pass value: false to opt an action out
+end
+```
+
+`clear_history` marks the *next* `inertia_render` call's response as `clearHistory: true`, telling
+the client to wipe any encrypted history it has stored - call it before redirecting on logout:
+
+```ruby
+def handle(req, res)
+  clear_history
+  res.redirect_to(routes.path(:root))
+end
+```
+
+### Configuration
+
+Configured in `config/providers/inertia.rb` (scaffolded by the install generator):
+
+```ruby
+Hanami.app.register_provider(:inertia, namespace: true) do
+  start do
+    configure do |config|
+      config.version = nil                              # default: digest of assets.json, if present
+      config.root_view = "app"                           # default
+      config.root_dom_id = "app"                         # default
+      config.component_path_resolver = ->(component) { component } # default: identity
+      config.always_include_errors_hash = false           # default
+      config.encrypt_history = false                      # default
+    end
+  end
+end
+```
+
+- `version` - the asset version string sent to the client and checked against
+  `X-Inertia-Version` by `InertiaHanami::Middleware::Version` (a mismatch triggers a full reload
+  so the client picks up new assets). Defaults to a SHA256 digest of hanami-assets'
+  `assets.json` manifest when present, or `nil` otherwise.
+- `root_view` - the view rendered for the initial full-page (non-Inertia) load.
+- `root_dom_id` - the `id` of the div `inertia_root` renders, matching the client's mount point.
+- `component_path_resolver` - a callable mapping the string passed to `inertia_render` to the
+  actual client-side component path, if you want the two to differ.
+- `always_include_errors_hash` - see Errors and flash above.
+- `encrypt_history` - see Encrypted history above.
+- `ssr.*` - see Server-side rendering (SSR) below.
+
+### Props
+
+Wrap a value in one of `InertiaHanami::Props`' wrapper classes to control how it's resolved and
+included in the response. There's no factory-method DSL - construct them directly with `.new`:
+
+```ruby
+def handle(req, res)
+  inertia_render "Users/Index", props: {
+    # Only sent when explicitly requested via a partial reload (`only:`).
+    stats: InertiaHanami::Props::Optional.new(block: -> { expensive_stats }),
+
+    # Always sent, even during a partial reload that would otherwise exclude it.
+    permissions: InertiaHanami::Props::Always.new(block: -> { current_user.permissions }),
+
+    # Loaded in a follow-up request after the initial page load. Props sharing the same
+    # `group:` (default `"default"`) are batched into one follow-up request.
+    notifications: InertiaHanami::Props::Defer.new(group: "sidebar", block: -> { fetch_notifications }),
+
+    # Resolved once and cached client-side; the client tells the server what it already has
+    # via X-Inertia-Except-Once-Props, so the block isn't re-run on subsequent visits.
+    locale_options: InertiaHanami::Props::Once.new(block: -> { available_locales }),
+
+    # Merged into the existing client-side prop instead of replacing it.
+    comments: InertiaHanami::Props::Merge.new(match_on: "id", block: -> { Comment.recent })
+  }
+end
+```
+
+- `Once#key:` - the cache key reported in `onceProps`; defaults to the prop's dot-path.
+- `Once#fresh:` - when `true`, always re-resolves and re-sends the prop even if the client
+  reports it as cached (bypasses `X-Inertia-Except-Once-Props`). Defaults to `false`.
+- `Once#expires_in:` - a number of seconds after which the client should treat its cached copy
+  as stale and ask for it again. Defaults to `nil` (never expires).
+- `Merge#deep_merge:` - deep-merges Hashes instead of the default shallow/array-append merge.
+- `Merge#match_on:` - a dot-path (relative to the prop) identifying items by key during a merge,
+  so updates replace existing items instead of duplicating them (e.g. `"id"` for an array of
+  records).
+
+#### Infinite scroll
+
+`InertiaHanami::Props::Scroll` drives the client's infinite-scroll feature: it merges into the
+existing client-side prop (appending on `fetchNext`, prepending on `fetchPrevious`, per the
+`X-Inertia-Infinite-Scroll-Merge-Intent` request header the client sends) and reports pagination
+metadata via the response's `scrollProps` map, which the client reads to know whether there's a
+next/previous page to fetch:
+
+```ruby
+def handle(req, res)
+  page = req.params[:page].to_i.nonzero? || 1
+  paginated = Post.page(page)
+
+  inertia_render "Posts/Index", props: {
+    posts: InertiaHanami::Props::Scroll.new(
+      match_on: "id",
+      current_page: paginated.current_page,
+      previous_page: paginated.prev_page,
+      next_page: paginated.next_page,
+      block: -> { paginated.to_a }
+    )
+  }
+end
+```
+
+- `page_name:` - the request param name the client increments as it scrolls (defaults to
+  `"page"`; must match the param your action reads, `req.params[:page]` above).
+- `previous_page:` / `next_page:` - the page identifier to request next in each direction, or
+  `nil` when there's nothing more to load in that direction (the client stops fetching once
+  `nil`).
+- `current_page:` - the page identifier just loaded, echoed back to the client.
+- `match_on:` - same de-duping semantics as `Merge#match_on:` above; near-essential for infinite
+  scroll so re-fetched items replace rather than duplicate existing ones.
+
+### CSRF protection
+
+CSRF is handled automatically once `config.actions.sessions` is configured and
+`InertiaHanami::Middleware::Csrf` is registered (both done for you by
+`hanami generate inertia:install`) - no app code required.
+
+Hanami's own `Hanami::Action::CSRFProtection` (auto-included on every action when sessions are
+enabled) stores its challenge token in the session and checks for it via an `X-CSRF-Token`
+header. Inertia's client, on the other hand, automatically reads an `XSRF-TOKEN` cookie and
+echoes it back as `X-XSRF-TOKEN` on every request - it never sends `X-CSRF-Token`. Neither side
+needs to change to talk to the other; `InertiaHanami::Middleware::Csrf` just translates between
+them: it mirrors the session's CSRF token into a readable `XSRF-TOKEN` cookie on responses, and
+copies an incoming `X-XSRF-TOKEN` header into `X-CSRF-Token` before the request reaches the
+action, so Hanami's own verification passes without either the client or the action needing to
+know about the other's naming convention.
+
+### Server-side rendering (SSR)
+
+By default, the initial page load is client-side rendered: the layout emits a
+`<script data-page="app" type="application/json">` tag holding the page JSON plus an empty
+`<div id="app">`, and the JS app hydrates it in the browser. Enabling SSR renders that markup up
+front, on the server, by delegating to a separately-run Node process.
+
+Configure it in `config/providers/inertia.rb`:
+
+```ruby
+Hanami.app.register_provider(:inertia, namespace: true) do
+  # ...
+  configure do |config|
+    config.ssr.enabled = true
+    config.ssr.url = "http://localhost:13714"   # default
+    config.ssr.raise_on_error = false            # default: fall back to CSR on SSR failure
+  end
+end
+```
+
+- `ssr.enabled` - turn SSR on for full-page (non-`X-Inertia`) requests. Disabled by default.
+- `ssr.url` - base URL of the Node SSR server. `InertiaHanami::SSRRenderer` POSTs the Inertia
+  page JSON to `#{ssr.url}/render`.
+- `ssr.raise_on_error` - when the SSR server is unreachable or errors, `false` (default) silently
+  falls back to CSR for that request; `true` re-raises so the failure surfaces instead of being
+  masked.
+
+Responses are cached in-process by a digest of the page JSON, so re-rendering an unchanged page
+within the same process skips the HTTP round-trip.
+
+**Running the Node SSR server.** This gem does not run or supervise the Node process for you -
+unlike inertia-rails' bundled Puma plugin, there is no process-management integration here. Run it
+as an independent process, exposing a `POST /render` endpoint that accepts the Inertia page JSON
+and returns `{"head": "...", "body": "..."}` (an array of strings for `head` is also accepted). See
+[inertia-rails' SSR server setup](https://inertia-rails.dev/guide/server-side-rendering) for the
+JS-side implementation - the wire protocol is the same. For example, with a `package.json` script:
+
+```bash
+node ssr/server.js   # listens on the port configured via ssr.url, e.g. 13714
+```
+
+Start it alongside your Hanami app (a `Procfile` entry, systemd unit, or `foreman start` are all
+reasonable choices) before enabling `ssr.enabled` in production.
+
+## Testing
+
+Require the RSpec matchers in your `spec/spec_helper.rb`:
+
+```ruby
+require "inertia_hanami/testing/rspec"
+```
+
+Then, in a request spec that `include`s `Rack::Test::Methods`:
+
+```ruby
+RSpec.describe "GET /" do
+  include Rack::Test::Methods
+
+  def app = MyApp::App
+
+  it "renders the dashboard" do
+    get "/", {}, { "HTTP_X_INERTIA" => "true" }
+
+    expect(inertia).to be_inertia_response
+    expect(inertia).to render_component("Dashboard/Show")
+    expect(inertia).to have_props(name: "Ada")
+    expect(inertia).to have_exact_props(name: "Ada", role: "admin")
+    expect(inertia).to have_no_prop(:secret)
+  end
+end
+```
+
+`inertia_reload_only(*props)`, `inertia_reload_except(*props)`, and
+`inertia_load_deferred_props(group = nil)` re-issue a GET against the last request's path
+with the appropriate `X-Inertia-Partial-*` headers, so you can assert on the result of a
+partial reload:
+
+```ruby
+get "/", {}, { "HTTP_X_INERTIA" => "true" }
+inertia_reload_only("name")
+expect(inertia).to have_exact_props(name: "Ada")
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kamalogudah/inertia_hanami. 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/kamalogudah/inertia_hanami/blob/main/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 InertiaHanami project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/kamalogudah/inertia_hanami/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[test rubocop]

data/lib/generators/inertia_hanami/install_generator.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "erb"
+require "json"
+require "dry/files"
+
+module InertiaHanami
+  module Generators
+    # Scaffolds everything a Hanami app needs to start using inertia_hanami:
+    # the provider, middleware wiring, layout, view helper, a sample page,
+    # and @inertiajs/* package.json guidance.
+    #
+    # Mirrors the shape of hanami-cli's own generators (`fs:`, `inflector:`,
+    # `out:` injected, `#call` performs the work), so it composes naturally
+    # with `Hanami::CLI::Commands::App::Command` subclasses.
+    class InstallGenerator
+      TEMPLATES_DIR = File.expand_path("templates", __dir__)
+
+      FRAMEWORK_PACKAGES = {
+        "react" => %w[@inertiajs/react react react-dom],
+        "vue" => %w[@inertiajs/vue3 vue],
+        "svelte" => %w[@inertiajs/svelte svelte]
+      }.freeze
+
+      MIDDLEWARE = {
+        "version" => "Version",
+        "redirects" => "Redirects",
+        "csrf" => "Csrf"
+      }.freeze
+
+      def initialize(fs:, inflector:, out:)
+        @fs = fs
+        @inflector = inflector
+        @out = out
+      end
+
+      def call(base_path:, namespace:, framework: "react", force: false)
+        unless FRAMEWORK_PACKAGES.key?(framework.to_s)
+          raise ArgumentError, "unknown framework #{framework.inspect}, expected one of #{FRAMEWORK_PACKAGES.keys}"
+        end
+
+        @base_path = base_path.to_s
+        @namespace = namespace.to_s
+        @framework = framework.to_s
+        @force = force
+
+        generate_provider
+        generate_middleware
+        generate_layout
+        generate_helpers
+        generate_sample_page
+        generate_package_json_guidance
+
+        out.puts
+        out.puts "Next steps:"
+        out.puts "  - Run `npm install` (or yarn/pnpm) to install the @inertiajs/* packages."
+        out.puts "  - Wire up your JS entrypoint (Vite/hanami-assets config) - inertia_hanami " \
+                 "does not manage frontend bundling."
+      end
+
+      private
+
+      attr_reader :fs, :inflector, :out, :base_path, :namespace, :framework, :force
+
+      def path(*parts)
+        fs.join(base_path, *parts)
+      end
+
+      def render(template)
+        erb_binding = binding
+        erb_binding.local_variable_set(:namespace, @namespace)
+        ERB.new(File.read(File.join(TEMPLATES_DIR, template)), trim_mode: "-").result(erb_binding)
+      end
+
+      def create(relative_path, content, force: self.force)
+        full_path = path(relative_path)
+
+        if fs.exist?(full_path) && !force
+          out.puts "      skip  #{relative_path} (already exists)"
+          return false
+        end
+
+        fs.write(full_path, content)
+        out.puts "    create  #{relative_path}"
+        true
+      end
+
+      def generate_provider
+        create("config/providers/inertia.rb", render("provider.rb.erb"))
+      end
+
+      def generate_middleware
+        app_file = path("config/app.rb")
+
+        unless fs.exist?(app_file)
+          out.puts "      skip  config/app.rb (not found - register the middleware manually)"
+          return
+        end
+
+        content = fs.read(app_file)
+
+        if middleware_registered?(content)
+          out.puts "      skip  config/app.rb (middleware already registered)"
+          return
+        end
+
+        inject_middleware_requires(app_file, content)
+        fs.inject_line_at_class_bottom(app_file, /class .* < Hanami::App/, middleware_use_lines)
+        out.puts "    update  config/app.rb"
+      rescue Dry::Files::MissingTargetError
+        out.puts "      skip  config/app.rb (unrecognized format - add the middleware manually: " \
+                 "#{middleware_use_lines.join(" / ")})"
+      end
+
+      def middleware_registered?(content)
+        MIDDLEWARE.each_value.all? { |klass| content.include?(middleware_class(klass)) }
+      end
+
+      def inject_middleware_requires(app_file, content)
+        MIDDLEWARE.each_key do |name|
+          require_line = %(require "inertia_hanami/middleware/#{name}")
+          fs.inject_line_before(app_file, /^module /, require_line) unless content.include?(require_line)
+        end
+      end
+
+      def middleware_use_lines
+        MIDDLEWARE.each_value.map { |klass| "config.middleware.use #{middleware_class(klass)}" }
+      end
+
+      def middleware_class(klass)
+        "InertiaHanami::Middleware::#{klass}"
+      end
+
+      def generate_layout
+        create("app/templates/layouts/app.html.erb", render("layout.html.erb.erb"))
+      end
+
+      def generate_helpers
+        helpers_file = path("app/views/helpers.rb")
+
+        unless fs.exist?(helpers_file)
+          create("app/views/helpers.rb", render("helpers.rb.erb"))
+          return
+        end
+
+        content = fs.read(helpers_file)
+
+        if content.include?("InertiaHanami::Helper")
+          out.puts "      skip  app/views/helpers.rb (already includes InertiaHanami::Helper)"
+          return
+        end
+
+        unless content.include?('require "inertia_hanami/helper"')
+          fs.inject_line_before(helpers_file, /^module /, 'require "inertia_hanami/helper"')
+        end
+        fs.inject_line_at_class_bottom(helpers_file, /module Helpers/, "include InertiaHanami::Helper")
+        out.puts "    update  app/views/helpers.rb"
+      rescue Dry::Files::MissingTargetError
+        out.puts "      skip  app/views/helpers.rb (unrecognized format - add " \
+                 "`include InertiaHanami::Helper` to it manually)"
+      end
+
+      def generate_sample_page
+        create("app/actions/inertia_example/show.rb", render("sample_action.rb.erb"))
+        create("app/views/inertia_example/show.rb", render("sample_view.rb.erb"))
+        create("app/templates/inertia_example/show.html.erb", render("sample_template.html.erb.erb"))
+
+        routes_file = path("config/routes.rb")
+        unless fs.exist?(routes_file)
+          out.puts "      skip  config/routes.rb (not found - add the route manually)"
+          return
+        end
+
+        content = fs.read(routes_file)
+        if content.include?('"inertia_example.show"')
+          out.puts "      skip  config/routes.rb (route already present)"
+          return
+        end
+
+        fs.inject_line_at_class_bottom(
+          routes_file, /class .* < Hanami::Routes/,
+          %(get "/inertia-example", to: "inertia_example.show")
+        )
+        out.puts "    update  config/routes.rb"
+      rescue Dry::Files::MissingTargetError
+        out.puts "      skip  config/routes.rb (unrecognized format - add the route manually: " \
+                 'get "/inertia-example", to: "inertia_example.show")'
+      end
+
+      def generate_package_json_guidance
+        packages = FRAMEWORK_PACKAGES.fetch(framework)
+        package_json_file = path("package.json")
+
+        unless fs.exist?(package_json_file)
+          out.puts
+          out.puts "No package.json found - install the frontend packages yourself:"
+          out.puts "  npm install #{packages.join(" ")}"
+          return
+        end
+
+        data = JSON.parse(fs.read(package_json_file))
+        dependencies = (data["dependencies"] ||= {})
+        added = packages.reject { |pkg| dependencies.key?(pkg) }
+
+        if added.empty?
+          out.puts "      skip  package.json (@inertiajs/* dependencies already present)"
+          return
+        end
+
+        added.each { |pkg| dependencies[pkg] = "latest" }
+        fs.write(package_json_file, "#{JSON.pretty_generate(data)}\n")
+        out.puts "    update  package.json (added #{added.join(", ")})"
+      end
+    end
+  end
+end

data/lib/generators/inertia_hanami/templates/helpers.rb.erb

@@ -0,0 +1,12 @@
+# auto_register: false
+# frozen_string_literal: true
+
+require "inertia_hanami/helper"
+
+module <%= namespace %>
+  module Views
+    module Helpers
+      include InertiaHanami::Helper
+    end
+  end
+end

data/lib/generators/inertia_hanami/templates/layout.html.erb.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title><%= namespace %></title>
+    <%%= inertia_ssr_head(ssr_head) if ssr_head %>
+  </head>
+  <body>
+    <%% if ssr_body %>
+      <%%= inertia_ssr_body(ssr_body) %>
+    <%% else %>
+      <%%= inertia_root(page: page) %>
+    <%% end %>
+  </body>
+</html>

data/lib/generators/inertia_hanami/templates/provider.rb.erb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "inertia_hanami/provider"
+
+Hanami.app.register_provider(:inertia, namespace: true, source: InertiaHanami::Provider)