skip to content

In a Hotwire Native app, how do path configuration rules make a habit tracker's /habits/new open as a modal, and how are matching rules combined?

level: middleimportance: nice to knowfreq 24%

answer

  1. settings plus rules in one JSON file
  2. patterns are unanchored regexes
  3. every matching rule applies; later wins
  4. "context": "modal"
  5. bundled copy plus a versioned remote one

basics

~20 s

The path configuration is JSON with settings and rules; each rule pairs regex patterns with properties. Every rule whose pattern matches the path applies in order, later ones overriding earlier ones, so a "/new$" rule with "context": "modal" opens /habits/new as a modal.

solid answer

~40 s

The app loads a JSON file with two keys: `settings` for app-level values and `rules`, an ordered list of `{ patterns, properties }`. For each visit, the native library tests the path against every rule's regex patterns and merges the properties of all matching rules in order, so later rules override earlier ones. The usual layout is a catch-all `".*"` rule with defaults, then specific overrides: `"/new$"` with `"context": "modal"` and `"pull_to_refresh_enabled": false` presents /habits/new as a modal without the refresh gesture fighting the dismiss gesture. Patterns are searched, not fully matched, so `/new` without `$` also hits /newsletter. Other properties include `presentation` (replace, pop, refresh, clear_all, replace_root, none), iOS `view_controller` and `modal_style`, and Android `uri`. Ship a bundled copy for first launch and offline, plus a versioned remote file per platform.

code

json · 17 lines
json
{
  "settings": {},
  "rules": [
    {
      "patterns": [".*"],
      "properties": { "context": "default", "pull_to_refresh_enabled": true }
    },
    {
      "patterns": ["/habits/new$", "/habits/\\d+/edit$"],
      "properties": { "context": "modal", "pull_to_refresh_enabled": false }
    },
    {
      "patterns": ["/habits/\\d+/check_in$"],
      "properties": { "context": "modal", "modal_style": "medium" }
    }
  ]
}

go deeper

for a junior

Recall that a JSON path configuration with settings and rules decides how URLs are presented, for example as modals.

for a middle

Explain ordered merging, unanchored regex patterns, the common properties and the bundled plus remote loading order.

for a senior

Version remote files per platform and build, anchor patterns carefully, and keep server-side rule changes compatible with old app builds.

for a principal

Use the remote configuration as a deliberate, versioned contract between the web team and the native releases.

## What the path configuration is Hotwire Native's default is simple: every internal link pushes a new screen. Anything else, such as presenting a form as a modal, replacing a screen, or showing a native screen for a URL, is driven by the **path configuration**, a JSON document the app loads at start-up: ```json { "settings": {}, "rules": [ { "patterns": [".*"], "properties": { "context": "default", "pull_to_refresh_enabled": true } }, { "patterns": ["/new$", "/edit$"], "properties": { "context": "modal", "pull_to_refresh_enabled": false } } ] } ``` - **`settings`** is free-form app configuration that the app reads itself, such as feature flags. - **`rules`** is an ordered list. Each rule has `patterns` (regular expressions) and `properties` (what to do). ## How rules combine For each visit the library takes the URL's path plus any query string (always on Android; on iOS while `matchQueryStrings` is left at its default of true) and walks the rules **in order**. Every rule whose pattern matches contributes its properties, and a later rule overwrites keys an earlier one set. So for `/habits/new`: 1. `".*"` matches: `context` default, pull to refresh on. 2. `"/new$"` matches: `context` becomes modal, pull to refresh off. The result is a modal without pull to refresh. Order matters more than specificity: a catch-all placed last would undo every override above it. The libraries also append their own rules for the historical-location paths turbo-rails redirects to, after yours, so those always win. Patterns are **searched, not fully matched**. `"/new"` matches `/habits/new`, but also `/newsletter` and `/habits/new/preview`; anchor with `$` (and `^` where it helps) to say what you mean. ## The properties the libraries understand | property | values | effect | |---|---|---| | `context` | `default`, `modal` | main stack or a modal | | `presentation` | `default`, `replace`, `pop`, `refresh`, `clear_all`, `replace_root`, `none` | how the stack changes | | `pull_to_refresh_enabled` | `true`, `false` | defaults to true on iOS, false on Android | | `animated` | `true`, `false` | animate the transition; default true | | `view_controller` (iOS) | an identifier | show a native view controller conforming to `PathConfigurationIdentifiable` | | `modal_style` (iOS) | `large`, `medium`, `full`, `page_sheet`, `form_sheet` | sheet style when `context` is modal | | `uri` / `fallback_uri` (Android) | a destination URI such as `hotwire://fragment/web` | which fragment shows the URL | You may add your own keys; the app can read them from the visit's properties. ## Loading it Both platforms take a **local** file bundled with the app and a **remote** URL: - iOS: `Hotwire.loadPathConfiguration(from: [.file(localURL), .server(remoteURL)])`. - Android: `Hotwire.loadPathConfiguration(context, PathConfiguration.Location(assetFilePath = ..., remoteFileUrl = ...))`. The bundled file applies immediately, a cached copy of the last remote download applies next, and a fresh download replaces it when it arrives. The remote file is the lever that lets you change navigation without an app release. ## Settings, and reading your own properties - **`settings`** carries values the app reads at start-up, such as feature flags or a support URL, so they can change without a release. - **Custom properties** in a rule are passed through untouched: a `"hide_tab_bar": true` key can be read by your own native code from the visit's properties. - **Query strings** count on both platforms by default, so `"\?view=calendar$"` can treat `/habits?view=calendar` differently from `/habits`. ## Debugging a rule that does not apply 1. Check the order: is a later rule overwriting the key? 2. Check the anchor: is the pattern matching more or less than you think? 3. Check which file the build loaded: bundled, cached remote or freshly downloaded. 4. Check the platform: `view_controller` and `modal_style` mean nothing on Android, `uri` nothing on iOS. ## Versioning Because old builds stay installed for months, name remote files per platform and version (`/configurations/ios_v1.json`, `/configurations/android_v1.json`) and keep serving old versions. A rule that points `/habits/stats` at a native screen only works in builds that contain that screen; a new build reads `ios_v2.json`, while older ones keep the rules they understand. Serving these files from Rails is an ordinary controller action or a static file.

  • Why put the catch-all rule first rather than last?
    All matching rules apply in array order and later ones overwrite earlier keys. A catch-all placed first sets defaults that specific rules then override; placed last it would overwrite every specific rule above it.
  • Why bundle a path configuration in the app if the server serves one?
    The bundled file applies at once, including on the first launch and when the device is offline, before any remote file has been downloaded. The remote file, cached after its first successful download, then lets you change behaviour without a release.

  • Only the first matching rule applies, so order does not matter
  • Path configuration patterns must match the whole path, so /new matches only /new
  • A path configuration can only be bundled in the app binary
  • pull_to_refresh_enabled defaults to the same value on iOS and Android
  • Changing a remote path configuration rule always requires a new app release