Recommended Usage

Keep state on the server

RGX works best when the server remains the source of truth for authentication, permissions, filters, pagination, and any other state the page already depends on.

The browser should request the current view and swap it in, not become a second state machine that has to be kept in sync.

The cleanest RGX page is still a server-rendered page. RGX only handles the transport and swap step.

Let templates own the defaults

Use Blade, Go templates, or the server renderer you already trust to define the shell, empty states, fallback copy, and the HTML for each route.

That keeps the default markup close to the data source and gives RGX a stable surface to swap into place when a fragment response arrives.

<a href="/dashboard" data-gx-select="#site-main">Dashboard</a>

Bridge shared component state

In a Laravel app, keep the controller thin and mount a request-scoped singleton or view model with the shared data the page needs.

Blade components can read from that shared context first, so the nav, notifications, cards, and other partials collaborate instead of each making their own query.

If the same component tree also powers an RGX endpoint, point it at the same controller action and return the same view fragments. Then bundle selectors for the nav, page body, notifications, or modal shell so one response can refresh everything together.

app()->scoped(ViewState::class, function () {
    return new ViewState(
        nav: Navigation::forUser(auth()->user()),
        notifications: Notification::forUser(auth()->id()),
        page: PageState::current(),
    );
});

data-gx-select="#site-nav@outerHTML->#site-nav@outerHTML #site-main@outerHTML->#site-main@outerHTML #toast-root@innerHTML->#toast-root@innerHTML"

Offer selector bundles

When one route needs several swap shapes, expose named presets instead of repeating long selector strings in every link or button.

RGX can read preset bundles from `data-gx-presets`, or from an external JSON file with `data-gx-presets-url` and `data-gx-presets-ttlm-ms` when you want the server to publish them separately.

<button
  data-gx-presets="default sidebar"
  data-gx-presets-url="/assets/rgx-presets.json"
  data-gx-presets-ttlm-ms="60000">
  Load preset bundle
</button>

Keep selectors short

Choose one short target per surface, such as `#site-main`, `#site-nav`, or `#examples-stage`, and make that the default in your templates.

Only reach for longer selectors when the response really needs a different destination. The point is to keep the client markup boring and the server route readable.

• Default to one stable swap target per screen.
• Move selector complexity into presets or server-side rendering.
• Keep fallback links and forms valid without JavaScript.