Inertia X adds Frames to Inertia 3

Update: You might also be interested in [Inertia X UI](https://dev.to/buhrmi/elon-is-mining-asteroids-and-im-just-sitting-here-making-modals-ppi), a UI layer built on top of Inertia X. It has been a long time coming, but after countless hours of refactoring, testing, and completely rethinking how we orchestrate monolithic single-page applications, I am very excited to finally type `npm publish`. **Inertia X.11 is a fork of Inertia 3 that adds the Frame component to the Svelte adapter.** You can check out the source code, read the documentation, and grab the package right now on GitHub: [github.com/buhrmi/inertiax](https://github.com/buhrmi/inertiax). If you’ve been following the project, you know that the landscape shifted dramatically with the arrival of the Inertia 3.x branch. To ensure complete alignment with these fundamental core upgrades and Svelte’s modern architecture, I made a tough but necessary decision: **Inertia X.11 is a complete rewrite from scratch.** By avoiding fragile monkey-patching and building natively on top of the newest Inertia 3 foundation, Inertia X.11 is cleaner, strictly typed, and incredibly fast. Here is a deep dive into why you should use it, what has changed, and how it works. --- ## The Core Problem: The Singleton Limitation Standard Inertia.js is brilliant, but it introduces a major architectural constraint: the global singleton router. Standard Inertia assumes your entire app has exactly one router and one active page state. Because of this, building complex interfaces—like slide-over panels, nested application wizards, or dynamic sidebars that pull live server data without resetting the rest of the application UI—can turn into a developer nightmare. You’re often forced to ditch the Inertia paradigm entirely and build custom JSON API endpoints or pollute your global page props. **Inertia X.11 shatters this limitation.** It adds a first-class `<Frame>` component to the Svelte adapter, giving you the ability to spin up multiple independent Inertia page regions on the exact same document. Each frame owns its own router and page state, ensuring that forms and links executed inside a frame only update that specific frame. --- ## What’s New and Changed in X.11? If you used previous iterations of Inertia X, things look vastly different now that we are built on top of Inertia 3: * **Explicit, First-Class Hooks:** Instead of manually digging through global store lookups, X.11 introduces clear, modern hooks like `useFrameRouter()` and `useFrameContext()`. * **Smart Browser History Tracking:** By default, actions taken within non-top frames update that frame's history state *without* replacing or mangling the browser URL. If you want a frame navigation to explicitly change the address bar, you now explicitly pass `updateBrowserUrl: true`. * **Automatic Link Interception:** Inertia X.11 introduces a global click handler that automatically intercepts standard same-origin `<a>` tags clicked within a frame, turning them into frame-scoped visits without requiring any boilerplate. * **`X-Inertia-Referer` Header:** To support clean server-side `redirect_back` behavior inside isolation, Inertia X now automatically sends an `X-Inertia-Referer` header containing the frame’s `src` URL. --- ## Useful Examples Using Inertia X.11 feels exactly like standard Inertia, but with superpowers. Here is how you can use the new syntax in your projects today: ### 1. Basic Frame Loading Need to load a dynamic sub-page or sidebar? Simply place a `<Frame>` component. You can pass a fallback snippet inside it to handle loading states smoothly. ```html <script> import { Frame } from 'inertiax-svelte'; </script> <div class="app-layout"> <main> <h1>Dashboard Home</h1> </main> <aside> <Frame id="sidebar" src="/users/42/edit"> <p>Loading user profile...</p> </Frame> </aside> </div> ``` ### 2. Accessing the Local Router Inside a component rendered within a frame, you can seamlessly control navigation utilizing `useFrameRouter()`. The top-level global router remains accessible through the standard import. ```html <script lang="ts"> import { useFrameRouter } from 'inertiax-svelte'; const router = useFrameRouter(); function nextStep() { // Navigates strictly inside this frame router.get('/wizard/step-2'); } </script> <button on:click={nextStep}>Next Step</button> ``` ### 3. Controlling a Frame From Somewhere Else Sometimes a parent layout or a main data table needs to trigger an event inside a secondary panel (like a detail slider). You can target a frame using `frameId` in your visit options: ```html <script lang="ts"> import { router } from 'inertiax-svelte'; function openDetailsPanel(userId: number) { router.get(`/users/${userId}/details`, {}, { frameId: 'details' }); } </script> <button on:click={() => openDetailsPanel(42)}>View Details</button> ``` Alternatively, if you prefer explicit control, you can instantiate a dedicated router and pass it directly to the frame: ```html <script lang="ts"> import { createRouter, Frame } from 'inertiax-svelte'; const detailsRouter = createRouter('details'); function showUser(userId: number) { detailsRouter.visit(`/users/${userId}/details`); } </script> <button on:click={() => showUser(42)}>Show User</button> <Frame id="details" router={detailsRouter} src="/users/42/details"> <p>Loading details...</p> </Frame> ``` ### 4. Customizing Link Interception Because standard `<a>` tags are intercepted automatically inside frames, building navigation is incredibly clean. If you want a specific link to bypass Inertia entirely, just use `data-inertia-ignore`. You can also intercept links programmatically using the `onClickLink` prop: ```html <script lang="ts"> import { Frame } from 'inertiax-svelte'; function onClickLink(event: MouseEvent, href: string) { if (href.startsWith('/admin')) { event.preventDefault(); // Stop frame navigation for admin routes // Implement custom routing or alert logic here } } </script> <Frame id="sidebar" src="/users/42/edit" {onClickLink} /> ``` --- ## Installation & Migration Because Inertia X.11 is a complete replacement ecosystem built over Inertia 3, migrating means swapping out the core packages. Your backend adapters (Laravel, Rails, Go, etc.) require zero changes! ```bash # Using npm npm remove @inertiajs/svelte @inertiajs/vite @inertiajs/core npm install inertiax-svelte inertiax-vite inertiax-core ``` Next, update your imports across your project files: * Change `@inertiajs/svelte` -> `inertiax-svelte` * Change `@inertiajs/core` -> `inertiax-core` * Change `@inertiajs/vite` -> `inertiax-vite` --- ## Wrapping Up Rewriting Inertia X from scratch for the 3.x branch was a massive undertaking, but the result is a bulletproof development experience. You no longer have to fight the framework to build complex, multi-region web applications. Go check out the code on [GitHub](https://github.com/buhrmi/inertiax), install the package, and let me know what incredible interfaces you create with it!