Contributing

The canonical repository is Inertia-X/InertiaX. Read its CONTRIBUTING.md before opening a change; it is the authority for environment setup, commit policy, release intent, and pull-request checks.

Repository structure

packages/protocol       canonical wire schema and fixtures
packages/core           portable state, requests, sessions, catalogs
packages/react          React renderer and built-in Table UI
packages/react-inertia  Inertia application-stack adapter
packages/laravel        Laravel authoring and execution
apps/react-renderer-lab direct renderer examples
apps/laravel-workbench  full-stack Laravel/Inertia examples
apps/demo               public browser-simulated examples
apps/docs               this documentation site

Each publishable package keeps its own manifest, public boundary, version, and artifact even though the source shares one repository.

Set up the workspace

Use the repository’s pinned package-manager version and install frontend dependencies from the root. Install Laravel dependencies in the package/workbench paths described by the root contributor guide.

Useful focused commands include:

pnpm lint
pnpm test
pnpm --dir apps/docs build
pnpm --filter @inertiax/react-renderer-lab test
composer --working-dir=packages/laravel test
pnpm --filter @inertiax/laravel-workbench verify:app

Run the checks proportional to the paths changed. The required CI performs path classification and aggregates selected evidence into CI / Required CI.

Route the change

• Protocol structure or meaning starts in packages/protocol, then refreshes Laravel’s snapshot.
• Portable state, requests, sessions, catalogs, and pipelines belong in packages/core.
• React presentation belongs in packages/react.
• Inertia prop, navigation, and location behavior belongs in packages/react-inertia.
• Laravel definitions, query execution, validation, and data behavior belong in packages/laravel.
• Browsable full-stack examples belong in apps/laravel-workbench.
• Public browser-simulated examples belong in apps/demo and must preserve their explicit non-Laravel/non-Inertia disclosure plus equivalent Laravel authoring.
• Renderer conformance examples belong in apps/react-renderer-lab.
• Customer documentation belongs in apps/docs.

A rendering framework and an application stack are separate axes. A renderer must not import Inertia; an Inertia integration must not move host navigation into Core.

Adding a frontend package

Package discovery is manifest-driven under packages/*. A new package needs a unique public responsibility, build and export metadata, license, ownership/path coverage, package-consumer evidence, and a Changeset. Do not add a shared global version or hardcoded package list.

Add no speculative package before a concrete integration proves the boundary.

Protocol changes

Start with canonical schemas and valid/invalid fixtures. Regenerate runtime types and artifacts, verify the checksum, refresh Laravel’s locked snapshot, build compatible consumers, and run the live full-stack workbench:

pnpm --filter @inertiax/protocol verify
composer --working-dir=packages/laravel protocol:refresh
pnpm protocol:verify

The protocol package and consumers version independently. An incompatible major must fail early.

Release intent

Pull requests that touch a Changesets-managed npm package must include that package in a manually authored .changeset/*.md file. Release-worthy Laravel changes must add customer-facing notes under ## Unreleased in packages/laravel/CHANGELOG.md.

The required CI compares the exact base and head and performs both checks read-only. Use skip-changeset only when changed package paths genuinely do not warrant a distributed release. Changesets version only affected npm packages; Laravel has a separate, human-approved preparation flow documented in the repository release guide.

Full-stack evidence

apps/laravel-workbench/tools/verify.mjs exercises live Composer and pnpm links, a real Inertia page, query and Collection sources, and matched Inertia generations. Release-grade evidence uses an isolated packed consumer so a passing workspace link cannot hide an artifact problem.

Use monorepo CI ownership to identify the evidence selected by each path. Unknown product paths fail classification until they receive an explicit owner.