Development Svelte
Daily workflow
| 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 and 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 @/routes and @/actions without Vite running |
The complete 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
We'll walk through adding a Reports page to the Dashboard module, served at /reports. You'll find the full code for each step in the collapsible blocks further down.
route (module web.php) → controller → Inertia::render('reports/Index')
→ resources/js/pages/reports/Index.svelte → translations → permission + menu → test- Add the route to
Modules/Dashboard/routes/web.php. It goes inside theauth+verifiedgroup, with thepermission:View Reports|View Tenant Reportsmiddleware and the namereports.index. - Create the controller at
Modules/Dashboard/Http/Controllers/ReportController.php. Keep it thin and put any business logic inModules/<Module>/Services. The controller renders the page by its path underresources/js/pages, which is PascalCase in this kit:Inertia::render('reports/Index', …). - Create the page at
resources/js/pages/reports/Index.svelte. Breadcrumbs go in<script module>, props come from$props(), andAppHeadsets the title. - Check Wayfinder. You can only import
@/routes/reportsafter Wayfinder has run. Ifnpm run devis running, that happens on its own. If not, runphp artisan wayfinder:generate --with-form. - Add translation keys to
lang/en/modules/dashboard.phpand to the matching file in every other locale, then runphp artisan erag:generate-lang. In Svelte you write the dot form,__('modules.dashboard.reports.title'). In PHP it's the slash form,__('modules/dashboard.reports.title'). - Add the permissions:
View Reportsgoes inconfig/permissions/dashboard.phpandView Tenant Reportsinconfig/permissions/tenant/dashboard.php. Then seed them with the commands below. - Add a menu entry with
'route_name' => 'reports.index'and the permission todatabase/seeders/MenuSeeder.php(and todatabase/seeders/tenant/MenuSeeder.php), then runphp artisan db:seed --class=MenuSeeder. The menu title is read from thenav.<slug>keys inlang/<locale>/modules/common.php. - Write a test that checks a user with the permission gets the
reports/Indexcomponent.
Steps 1–2: 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');
});// Modules/Dashboard/Http/Controllers/ReportController.php
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' => [],
]);
}
}Step 3: page file
<script module lang="ts">
import { dashboard } from '@/routes';
import { index } from '@/routes/reports';
export const layout = {
breadcrumbs: [
{ title: 'modules.common.nav.dashboard', href: dashboard() },
{ title: 'modules.dashboard.reports.title', href: index() },
],
};
</script>
<script lang="ts">
import { svelteLang } from '@erag/lang-sync-inertia/svelte';
import AppHead from '@/components/AppHead.svelte';
import Heading from '@/components/Heading.svelte';
let {
reports,
}: {
reports: { id: number; name: string }[];
} = $props();
const { __ } = svelteLang();
</script>
<AppHead title={__('modules.dashboard.reports.title')} />
<div class="space-y-6 px-4 py-6">
<Heading
title={__('modules.dashboard.reports.title')}
description={__('modules.dashboard.reports.description')}
/>
<ul class="space-y-2">
{#each reports as report (report.id)}
<li>{report.name}</li>
{/each}
</ul>
</div>Steps 5–7: translations, permissions and seeding
// lang/en/modules/dashboard.php
'reports' => [
'title' => 'Reports',
'description' => 'Exported analytics reports.',
],// config/permissions/dashboard.php (central)
[
'permission_name' => 'View Reports',
'associated_roles' => ['Super Admin', 'Admin'],
],
// config/permissions/tenant/dashboard.php (tenant)
[
'permission_name' => 'View Tenant Reports',
'associated_roles' => ['Super Admin', 'Admin'],
],php artisan erag:generate-lang
php artisan db:seed --class=PermissionSeeder
php artisan tenants:seed --class="Database\Seeders\PermissionSeeder"
php artisan db:seed --class=MenuSeederStep 8: 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.svelte doesn't exist.
INFO
When a user is given a system role after seeding, they pick up the permission through associated_roles. For users you already have, grant it from Users → Assign permissions. Users, roles & permissions explains how this works.
Adding a form
A form posts to a controller action using Wayfinder and Inertia's <Form> component. If you want something to copy, look at the roles form (RoleController, RoleData, pages/roles/Partials/RoleFormModal.svelte).
- Validate on the server. We use Spatie Data classes for this (for example
Modules/RolePermission/Data/RoleData.php, which has arules()method), type-hinted in the controller action. - Let the controller hand the work to a service, flash a toast with
Inertia::flash('toast', …)and redirect. - Add a route to the module's
routes/web.php, with a name and the permission middleware. - Build the form: spread the Wayfinder
.form()object into<Form>, then addCommon*inputs withnameanderror.
<script lang="ts">
import { Form } from '@inertiajs/svelte';
import { store } from '@/routes/roles';
</script>
<Form {...store.form()} options={{ preserveScroll: true }}>
{#snippet children({ 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>
{/snippet}
</Form>Validation errors show up in errors without any extra code, and lib/flash-toast.ts displays the flashed toast. For edit forms, useForm and create/edit modals, see Inertia → Forms.
Type checking & linting
| Command | What it runs |
|---|---|
npm run lint | eslint ., prettier --check resources/, svelte-check --tsconfig ./tsconfig.json |
npm run lint:fix | eslint . --fix, prettier --write resources/, svelte-check --tsconfig ./tsconfig.json |
npx svelte-check --tsconfig ./tsconfig.json | Type check only |
composer lint | Pint, php artisan typescript:transform, npm run lint:fix |
composer test | config:clear, composer lint:check, Larastan (composer types:check), 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 before destructive actions withuseConfirmDialog(). - Use Wayfinder rather than typing URLs by hand, and pair
.form()with<Form>. - Type everything. Data objects get the generated types from
@/types/Modules/..., and type-only imports useimport type(ESLint will remind you). - Hide actions the user isn't allowed to take with
usePermission(), for examplecan('Export Analytics Reports', 'Export Tenant Reports'). See Architecture → Permissions. - Put shared logic in
lib/(as a.svelte.tsfile if it needs runes). Components that belong to a single page go in that page'sPartials/folder.