inertia-rails-pages

Inertia Rails Pages

Page components, layouts, navigation, and client-side APIs.

Before building a page, ask:

• Does this page need a layout? → Use persistent layout (React: Page.layout = ...; Vue: defineOptions({ layout }); Svelte: module script export) — wrapping in JSX/template remounts on every navigation, losing scroll position, audio playback, and component state
• Does UI state come from the URL? → Change BOTH controller (read params, pass as prop) AND component (derive from prop, no useState/useEffect) — use router.get to update URL
• Need to refresh data without navigation? → router.reload({ only: [...] }) — never useEffect + fetch
• Need to update a prop without server round-trip? → router.replaceProp — no fetch, no reload

NEVER:

• Parse window.location.search or use useSearchParams — derive URL state from controller props
• Use useState/useEffect to sync URL ↔ React state — the controller passes URL-derived data as props; the component just reads them
• Pass arguments to <Deferred> render function — {(data) => ...} does NOT work; child reads via usePage()
• Access usePage().props.flash — flash is top-level: usePage().flash
• Wrap layout in JSX return for persistence — use Page.layout = ... or global layout inside createInertiaApp's resolve callback

Page Component Structure

Pages are default exports receiving controller props as function arguments. Use type Props = { ... } (not interface — causes TS2344 in React). Vue uses defineProps<T>(), Svelte uses let { ... } = $props().

type Props = {
  posts: Post[]
}

export default function Index({ posts }: Props) {
  return <PostList posts={posts} />
}

Persistent Layouts

Layouts persist across navigations — no remounting, preserving scroll, audio, etc.

import { AppLayout } from '@/layouts/app-layout'

export default function Show({ course }: Props) {
  return <CourseContent course={course} />
}

// Single layout
Show.layout = (page: React.ReactNode) => <AppLayout>{page}</AppLayout>