Inertia Table Laravel Package

Getting Started

This assessment is based on the 2.0.0-beta.1 release notes only — treat it as a starting orientation and confirm specifics against the repo's README.md and UPGRADING.md before committing to a migration.

• Check the version gate first. 2.x targets Laravel 12/13, Inertia 2/3 and laravel-data 4. If you are on Laravel 11, Inertia 1, or laravel-data 3, stop here: ^1.x is unaffected by this release and continues on the 1.x branch. Confirm each constraint in your composer.json before running anything.
• Read UPGRADING.md before installing. The release notes explicitly call this out. It is the authoritative source for the 1.x → 2.x delta (renamed classes, changed prop shapes, config keys) and will be more accurate than blog posts or the README's older examples.
• Install with the stability flag. The pre-release will not resolve from a plain ^2.0 constraint:

  composer require "felipeva/inertia-table:^2.0@beta"
  npm install @felipeva/inertiajs-table-react@next
  

  The npm package may 404 initially — the notes say it lands only once the staged release is approved. If npm install fails with ETARGET, the frontend half has not shipped yet; you are not doing anything wrong.
• First use case: pick a single read-only admin index page — one model, one laravel-data resource, paginated and sortable, no filters, no bulk actions. This shakes out the composer/npm/Inertia wiring (the most likely place to hit version friction) without touching tables your users depend on.
• Where to look next: UPGRADING.md for the migration path, README.md for the current API surface, and the package's test suite or demo app (if present) for the exact shape of the props the React component expects — that shape is the thing you will spend the most time matching.

Implementation Patterns

• Keep table state server-side and URL-addressable. The durable pattern with an Inertia table is that page, sort column, sort direction and filters live in the query string and are read on the server, not held in React component state. That gives you deep-linkable views, working browser back/forward, and a table that survives a full page refresh — all of which break if you sort in the client.
• Use Inertia partial reloads for table interactions. Sorting, paging and filtering should re-request only the table prop (only: ['users'] or equivalent) rather than re-shipping every prop on the page. This is the single biggest perceived-performance lever in an Inertia table.
• One table class per resource, query building out of the controller. Controllers should resolve a table instance and hand it to Inertia; joins, with(), search scopes and column definitions belong in a dedicated class. This keeps the controller readable and makes the table testable without rendering React.
• Let laravel-data own the row shape. Define a DTO per row with explicit types and DataCollection::prepareForInertia()-style transformation, so the frontend contract is a typed object rather than an Eloquent model's incidental attributes. This also means column renames are a one-line DTO change instead of a React change.
• Reset to page 1 on every filter change. Debounce text inputs (~300ms), push the new query string, and drop the page parameter. Forgetting this produces the classic "no results on page 4" bug.
• Migrate in two separate PRs. The laravel-data 3 → 4 upgrade is likely a larger and more invasive change than the table package itself. Land the laravel-data bump on its own (with its own tests) and then swap the table package, so a failure has an obvious owner.
• Run 1.x and 2.x in parallel while evaluating. Keep the 2.0 work on a branch with an isolated dependency set. If you maintain multiple apps, a CI matrix split by Laravel version is cleaner than trying to satisfy both constraint sets in one branch.
• Test the props, not the pixels. Assert the Inertia prop shape (columns, rows, pagination meta) in PHPUnit/Inertia assertions. Frontend rendering is the React package's responsibility; your tests should catch a broken query or a renamed DTO field.

Gotchas and Tips

• @beta is a stability flag, not a version. ^2.0@beta will happily pull beta.2, beta.3, and so on. Between betas there is no API stability guarantee — pin the exact version (2.0.0-beta.1) in CI and read the changelog on every bump. Floating a pre-release constraint in a shared app is how you get a red build on a Tuesday for no reason.
• Don't reach for minimum-stability: dev to force the install. If @beta on the single requirement isn't enough, the real problem is a transitive constraint conflict (usually laravel-data 4 versus another package still pinning ^3). Fix that conflict; loosening global stability will silently pull unstable versions of unrelated packages.
• The npm dist-tag is next, and it may not exist yet. A staged release awaiting approval means the tarball is not on the registry. Confirm the package resolves (npm view @felipeva/inertiajs-table-react dist-tags) before planning frontend work around it; otherwise you are blocked on a maintainer action, not on your own code.
• React bindings only. The JavaScript package is named inertiajs-table-react. If your app is Vue or Svelte, this release does not give you a first-party frontend — check whether the server-side package is frontend-agnostic enough to hand-roll the client before assuming parity with 1.x.
• 1.x is the production answer today. ^1.x installs are explicitly unaffected and the 1.x branch is live. Treat 2.0.0-beta.1 as an evaluation target for a greenfield Laravel 12 app or a spike branch, not a drop-in for a shipped product.
• When the README and UPGRADING.md disagree, trust UPGRADING.md for the 1.x → 2.x jump. Docs on the default branch often track the unreleased line; the upgrade guide is written specifically for people in your position.
• Check for a publishable config before forking anything. Most packages of this shape expose a config file for default pagination size, per-page options and view/component paths. Run the publish command and read the config first — customising a vendor file is the most common way to make the next beta painful.
• "Table renders empty" is almost always a server-side prop-shape mismatch. Dump the Inertia props (dd($props) via the Inertia testing helpers, or the Vue/React devtools panel) before touching the frontend. Mismatched keys between the table class and the React component — often introduced by a beta rename — account for most of these reports.
• Extension points to note while reading the source: the table/column classes themselves (subclass rather than copy), any published config, and the Inertia prop serialisation step. Those three cover the majority of "I need to change one thing" cases without vendoring.