Development React
Daily workflow
Run composer dev to start everything, then work in resources/js and Modules/. While you edit, Vite reloads the browser and keeps the Wayfinder files up to date.
| Command | What it does |
|---|---|
composer dev | Runs php artisan serve, queue:listen, pail and npm run dev together |
npm run dev | Vite dev server with HMR (also regenerates Wayfinder files) |
npm run build | Production build to public/build |
npm run build:ssr | Client + SSR bundle (vite build && vite build --ssr) |
php artisan erag:generate-lang | Export lang/* to resources/js/lang/*.json |
php artisan wayfinder:generate --with-form | Regenerate Wayfinder files without Vite running |
The full list is on the Commands page.
TIP
Change not showing up in the browser? Make sure npm run dev (or composer dev) is running, or run npm run build.
Adding a page
Let's walk through adding a Reports page to the Dashboard module, served at /reports.
routes/web.php → ReportController@index → Inertia::render('reports/index') → pages/reports/index.tsx- Add the route to
Modules/Dashboard/routes/web.phpinside theauth+verifiedgroup. Give it thepermission:View Reports|View Tenant Reportsmiddleware and the namereports.index. - Create the controller at
Modules/Dashboard/Http/Controllers/ReportController.php. It should stay thin: call a service inModules/<Module>/Servicesand returnInertia::render('reports/index', [...]). - Create the page at
resources/js/pages/reports/index.tsx. It needs a default-exported component and a staticlayoutthat sets the breadcrumbs. - Once Wayfinder has run, you can import
@/routes/reports. Ifnpm run devis running, that happens on its own. - Add the translation keys to
lang/en/modules/dashboard.phpand to the same file in each of the other locales, then runphp artisan erag:generate-lang. - Add the permissions:
View Reportsgoes inconfig/permissions/dashboard.phpandView Tenant Reportsinconfig/permissions/tenant/dashboard.php. Seed them afterwards. - If you want a menu entry (optional), add one to
database/seeders/MenuSeeder.phpanddatabase/seeders/tenant/MenuSeeder.phpwith'route_name' => 'reports.index'and the permission. - Write a test that checks the route renders the
reports/indexcomponent.
The page itself doesn't need much:
export default function ReportsIndex({ reports }: Props) {
const { __ } = reactLang();
return (
<>
<Head title={__('modules.dashboard.reports.title')} />
<Heading title={__('modules.dashboard.reports.title')} />
<ul>
{reports.map((report) => <li key={report.id}>{report.name}</li>)}
</ul>
</>
);
}View route and controller
// Modules/Dashboard/routes/web.php
use Modules\Dashboard\Http\Controllers\ReportController;
Route::middleware(['auth', 'verified'])->group(function () {
Route::get('reports', [ReportController::class, 'index'])
->middleware('permission:View Reports|View Tenant Reports')
->name('reports.index');
});namespace Modules\Dashboard\Http\Controllers;
use App\Http\Controllers\Controller;
use Inertia\Inertia;
use Inertia\Response;
class ReportController extends Controller
{
public function index(): Response
{
return Inertia::render('reports/index', [
'reports' => [],
]);
}
}View full page file
import { reactLang } from '@erag/lang-sync-inertia/react';
import { Head } from '@inertiajs/react';
import Heading from '@/components/heading';
import { dashboard } from '@/routes';
import { index } from '@/routes/reports';
type Props = {
reports: { id: number; name: string }[];
};
export default function ReportsIndex({ reports }: Props) {
const { __ } = reactLang();
return (
<>
<Head title={__('modules.dashboard.reports.title')} />
<div className="space-y-6 px-4 py-6">
<Heading
title={__('modules.dashboard.reports.title')}
description={__('modules.dashboard.reports.description')}
/>
<ul className="space-y-2">
{reports.map((report) => (
<li key={report.id}>{report.name}</li>
))}
</ul>
</div>
</>
);
}
ReportsIndex.layout = {
breadcrumbs: [
{ title: 'modules.common.nav.dashboard', href: dashboard() },
{ title: 'modules.dashboard.reports.title', href: index() },
],
};View translations, permissions and menu
The translation keys go in lang/en/modules/dashboard.php. Repeat them for every locale under lang/<locale>/modules/:
'reports' => [
'title' => 'Reports',
'description' => 'Exported analytics reports.',
],On the frontend you write __('modules.dashboard.reports.title'). In PHP, use the slash form instead: __('modules/dashboard.reports.title').
Permissions:
// config/permissions/dashboard.php
[
'permission_name' => 'View Reports',
'associated_roles' => ['Super Admin', 'Admin'],
],
// config/permissions/tenant/dashboard.php
[
'permission_name' => 'View Tenant Reports',
'associated_roles' => ['Super Admin', 'Admin'],
],Seed them:
php artisan db:seed --class=PermissionSeeder
php artisan tenants:seed --class="Database\Seeders\PermissionSeeder"Anyone who's given a system role after this gets the permission through associated_roles. For existing users, grant it from Users → Assign permissions.
After adding the menu entry, run php artisan db:seed --class=MenuSeeder. The menu title comes from the nav.<slug> key in lang/<locale>/modules/common.php.
Roles, permissions and tenant seeding are covered in more depth in Users, roles & permissions.
View feature test
use App\Models\User;
use Inertia\Testing\AssertableInertia as Assert;
use Spatie\Permission\Models\Permission;
test('users with the permission can visit the reports page', function () {
$user = User::factory()->create();
$user->givePermissionTo(Permission::findOrCreate('View Reports', 'web'));
$this->actingAs($user)
->get(route('reports.index'))
->assertInertia(fn (Assert $page) => $page->component('reports/index'));
});Run it with php artisan test --compact --filter=reports. Since config/inertia.php turns on testing.ensure_pages_exist, the test will fail if reports/index.tsx doesn't exist.
Adding a form
A form posts directly to a Laravel route, with no API layer in between.
<Form {...store.form()}> → Controller@store(Data $data) → Service → Inertia::flash('toast') → redirect- Add a named
POST(orPATCH/PUT) route with permission middleware. - Write the validation rules in the
rules()method of a Spatie Data class (Modules/<Module>/Data/*Data.php), then type-hint that class in the controller action the wayRoleController@store(RoleData $data)does. - In the controller, call the service, flash a toast and redirect.
- On the page, spread the Wayfinder
.form()object into<Form>and addCommon*inputs with anameand anerror.
import { store } from '@/routes/roles';
<Form {...store.form()} resetOnSuccess options={{ preserveScroll: true }}>
{({ errors, processing }) => (
<>
<CommonInput name="name" label={__('modules.role.form_modal.name')} error={errors.name} />
<CommonButton type="submit" loading={processing}>
{__('modules.role.form_modal.create')}
</CommonButton>
</>
)}
</Form>If validation fails, the messages come back in errors, keyed by field name. For edit forms, useForm and combined create/edit modals, see Inertia → Forms.
View controller action
public function store(RoleData $data): RedirectResponse
{
$this->roleService->createRole($data);
Inertia::flash('toast', ['type' => 'success', 'message' => __('modules/role.toasts.created')]);
return to_route('roles.index');
}Type checking & linting
| Command | What it does |
|---|---|
npm run lint | eslint . + prettier --check resources/ + tsc --noEmit |
npm run lint:fix | eslint . --fix + prettier --write resources/ + tsc --noEmit |
npx tsc --noEmit | Type check only |
composer lint | Pint, php artisan typescript:transform, npm run lint:fix |
composer test | Lint check, Larastan, then php artisan test |
Get into the habit of running npm run lint:fix before you commit.
Conventions
- Don't hard-code text. Every string the user sees goes through
__()with amodules.<feature>.<key>key, and that includes breadcrumbs, placeholders, toasts and confirm dialogs. - Build form fields and buttons from the
Common*components, and ask for confirmation withuseConfirmDialog()before anything destructive. - Get URLs from Wayfinder rather than typing them out, and pair
.form()with<Form>. - Type everything. Data objects use the generated types from
@/types/Modules/..., and type-only imports useimport type(ESLint enforces it). - Hide actions the user isn't allowed to take with
usePermission().can(...), as described in Architecture → Permissions. - Hooks go in
hooks/use-x.tsand page-only components go in the page'spartials/folder. All file names are kebab-case.