Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
261 lines (181 loc) · 8.4 KB

CONTRIBUTING.md

File metadata and controls

261 lines (181 loc) · 8.4 KB

Contributing

Thank you for your interest in contributing to Inertia.js! Your contributions help make this project better for everyone.

Inertia.js is maintained as a monorepo using pnpm workspaces. Below you'll find an overview of the repository and how to get your development environment running.

Note: You'll need pnpm version 10 or higher. If you're unsure which version you have, run pnpm -v.

Repository Overview

inertia/
├── packages/          Core libraries and framework adapters
│   ├── core/          Framework-agnostic core library
│   ├── react/         React adapter
│   │   └── test-app/  React test application
│   ├── svelte/        Svelte adapter
│   │   └── test-app/  Svelte test application
│   └── vue3/          Vue 3 adapter
│       └── test-app/  Vue 3 test application
├── playgrounds/       Full Laravel applications for manual testing
│   ├── react/         Laravel + React
│   ├── svelte5/       Laravel + Svelte 5
│   └── vue3/          Laravel + Vue 3
└── tests/             End-to-end tests and test server
    ├── app/           Shared Node.js backend
    └── *.spec.ts      Playwright test suite

Key Components

  • Core Library: The framework-agnostic engine powering all adapters (packages/core).
  • Adapters: Framework-specific integrations for React, Svelte, and Vue.
  • Test Applications: Minimal frontend apps used for automated testing (packages/*/test-app/).
  • Playwright Tests: Framework-agnostic end-to-end tests that verify behavior across adapters (tests/*.spec.ts).
  • Playgrounds: Full Laravel applications for manual testing (playgrounds/). These are optional and may eventually be removed.

Getting Started

Clone the repository and install the dependencies:

git clone https://github.com/inertiajs/inertia.git inertia
cd inertia
pnpm install

Then, start the development environment:

pnpm dev

This builds the core library and all adapters, and starts a file watcher that will automatically rebuild each package when changes are made.

If you prefer, you can also start individual watchers from each package directory. For example:

cd packages/core && pnpm dev
cd packages/react && pnpm dev

Note: The core package (packages/core) must always be running, as all adapters depend on it.

Running Tests

Inertia.js uses Playwright to run a shared end-to-end test suite against each adapter. This is how we verify that Inertia behaves the same across React, Svelte, and Vue.

Run the test suite for a specific adapter:

pnpm test:react
pnpm test:svelte
pnpm test:vue

These commands automatically set a PACKAGE environment variable that tells the Node.js test server which adapter to serve. For example, when running pnpm test:react, the test server loads the React test application.

If you want to run Playwright directly, you can pass the environment variable yourself:

PACKAGE=react playwright test

You may filter tests by name:

pnpm test:react -g "partial reload"

Run tests in headed mode (to see the browser):

pnpm test:vue --headed

Or in debug mode:

pnpm test:vue --debug

How the Test Setup Works

All adapters use the same Node.js backend and Playwright test suite. The only difference is which adapter's test app is served.

tests/app/server.js         Shared Node.js backend
├── serves: react test app  (when PACKAGE=react)
├── serves: svelte test app (when PACKAGE=svelte)
└── serves: vue test app    (when PACKAGE=vue3)

tests/*.spec.ts             Shared Playwright test suite

When running a test command, the correct adapter is selected automatically:

Adapter PACKAGE value Test server port App URL
React react 13716 http://localhost:13716/
Svelte svelte 13717 http://localhost:13717/
Vue 3 vue3 13715 http://localhost:13715/

Automatic Test Server Boot

You do not need to start the test server manually. When you run a test, Playwright automatically builds the frontend for the selected adapter and boots the Node.js test server before running the tests. This is configured in the Playwright config (playwright.config.ts) using the webServer option. If a server is already running (for example, during local development), Playwright will reuse it.

Running Test Applications

The test applications are the primary development environments for Inertia.js. These minimal apps cover all supported features and are used for both manual development and automated end-to-end testing.

Run all test apps at once:

pnpm dev:test-app

Or start an individual one:

pnpm dev:test-app:react
pnpm dev:test-app:svelte
pnpm dev:test-app:vue

Each test app runs two servers:

  • A Node.js backend that automatically restarts when changed
  • A Vite development server for the frontend

If you are developing a new feature or fixing a bug, you can use these test apps to develop and test your changes.

Adding Tests

If you are fixing a bug, adding a feature, or improving existing functionality, please verify that your changes work across all adapters, not just one.

1. Add Frontend Pages

Create the same frontend page in each test application:

packages/react/test-app/Pages/YourFeature.jsx
packages/svelte/test-app/Pages/YourFeature.svelte
packages/vue3/test-app/Pages/YourFeature.vue

Each page should provide the same behavior and functionality.

2. Add Backend Routes (If Needed)

If your change requires a backend route, add it to the shared Node.js test server:

// tests/app/server.js
app.get('/your-feature', (req, res) =>
  inertia.render(req, res, {
    component: 'YourFeature',
    props: { foo: 'bar' },
  }),
)

3. Write a Playwright Test

Add a new Playwright test to verify your change. Playwright allows us to test features across all adapters without duplicating test logic.

// tests/your-feature.spec.ts
import { test, expect } from '@playwright/test'

test('your feature works', async ({ page }) => {
  await page.goto('/your-feature')
  // Your assertions here
})

4. Run the Tests in All Adapters

Be sure to run your test for each adapter:

pnpm test:react -g "your feature"
pnpm test:svelte -g "your feature"
pnpm test:vue -g "your feature"

Your work is not considered complete until it works consistently across all frameworks.

Using the Playgrounds (Optional)

The repository also includes several full Laravel applications that integrate Inertia.js. These are optional and mostly useful for manually exploring how Inertia works inside a real Laravel app.

The playgrounds are provided as-is and are not part of the automated test setup. They may be removed in the future.

Getting Started

To start a playground, simply run:

pnpm playground:react

The playground script will automatically handle initial setup if needed:

  • Installing PHP dependencies via Composer
  • Installing Node.js dependencies via pnpm
  • Creating the .env file from .env.example
  • Generating the application key
  • Setting up the SQLite database
  • Running migrations with seed data

Visit the application at http://127.0.0.1:8000.

Each playground has its own pnpm script:

pnpm playground:react
pnpm playground:svelte
pnpm playground:vue

Publishing (Maintainers Only)

Releasing is handled by the included release script. You'll need both the git CLI and the GitHub CLI (gh) installed. To create a new release:

./release.sh

The script will:

  • Ensure you're on the master branch with a clean working tree
  • Prompt you to select the type of version bump (patch, minor, or major)
  • Update all package versions automatically
  • Update the lockfile
  • Create a git commit and tag
  • Push changes and tags to GitHub
  • Create a GitHub release with auto-generated notes
  • Trigger the CI publishing workflow

Publishing is handled securely using GitHub + npm trusted publishing.