Architecture Svelte
All the Svelte-specific code is in resources/js. For the Laravel side (modules, tenancy, auth), see Core architecture.
Overview
Here's the path a request takes from a Laravel controller to a Svelte page:
Controller: Inertia::render('users/Index', $props)
→ @inertiajs/vite resolves resources/js/pages/users/Index.svelte
→ app.ts picks the default layout from the page name
→ page reads its own props with $props() and shared props from `page`The app is created in resources/js/app.ts. You won't find a resolve callback there, because the @inertiajs/vite plugin in vite.config.ts handles page resolution. What app.ts does have is a layout callback, which picks a default layout based on the page name:
| Page name starts with | Default layout |
|---|---|
auth/ | AuthLayout |
settings/ | AppLayout wrapping settings/Layout.svelte |
| anything else | AppLayout |
Any page can override that default from its <script module> block (more on this in Layouts).
After that, app.ts runs two setup functions:
initializeTheme()fromlib/theme.svelte.ts, which applies light, dark or system mode.initializeFlashToast()fromlib/flash-toast.ts, which turns flash data from the server into toasts.
View app.ts
createInertiaApp({
title: (title) => (title ? `${title} - ${appName}` : appName),
layout: (name) => {
switch (true) {
case name.startsWith('auth/'):
return AuthLayout;
case name.startsWith('settings/'):
return [AppLayout, SettingsLayout];
default:
return AppLayout;
}
},
progress: { color: '#4B5563' },
});
initializeTheme();
initializeFlashToast();Folder map
| Folder | Purpose |
|---|---|
app.ts | createInertiaApp, default layouts, theme, flash toasts |
pages/ | Inertia pages (PascalCase .svelte): auth/, errors/, roles/, settings/, setup/, tenants/, users/, plus Dashboard.svelte and Home.svelte |
layouts/ | AppLayout.svelte, AuthLayout.svelte, their variants in app/ and auth/, and settings/Layout.svelte |
components/common/ | The Common* form kit and ConfirmDialog |
components/ui/ | shadcn-svelte primitives (bits-ui) |
components/ | App shell and feature components (AppHead, AppSidebar, AppHeader, UserMenuContent, …) |
lib/ | Shared logic; rune modules end in .svelte.ts |
types/ | Hand-written and generated TypeScript types |
lang/ | Generated translation JSON (php artisan erag:generate-lang) |
routes/, actions/, wayfinder/ | Generated by Wayfinder, ignored by git |
Naming
| Thing | Convention | Example |
|---|---|---|
| Page | PascalCase .svelte under a lowercase folder | pages/tenants/Index.svelte |
| Inertia page name | Path without extension | Inertia::render('tenants/Index') |
| Page-only child component | Partials/ next to the page | pages/users/Partials/UserFormModal.svelte |
| Shared component | PascalCase .svelte | components/UserMenuContent.svelte |
| Form component | Common prefix | components/common/CommonSelect.svelte |
| Shared logic | camelCase module in lib/; .svelte.ts when it uses runes | lib/permission.ts, lib/confirmDialog.svelte.ts |
| UI primitive | shadcn-svelte folder with index.ts | components/ui/dialog |
Every component uses <script lang="ts"> with runes ($props(), $state, $derived, $effect). Where you'd reach for slots in older Svelte, we use snippets ({#snippet} / {@render}).
Linting runs through ESLint with eslint-plugin-svelte. It expects type-only imports, import groups in alphabetical order, 1TBS braces and a blank line before and after control statements.
lib modules
| File | Exports |
|---|---|
confirmDialog.svelte.ts | useConfirmDialog() → confirm(options), setLoading() |
currentUrl.svelte.ts | useCurrentUrl(), isCurrentUrl(), isCurrentOrParentUrl(), currentUrlState() |
debounce.svelte.ts | useDebounce(getter, delay) → { value }, useDebounceFn(fn, delay) |
flash-toast.ts | initializeFlashToast() |
initials.ts | getInitials(), useInitials() |
language.ts | useLanguage(), DEFAULT_LANGUAGE_VALUE, languageLabel(), toLocaleValue(), transformLocale(), changeLanguage() |
permission.ts | can(), usePermission() |
secret.ts | generateSecret(), useSecret() |
slug.ts | slugify(), useSlug() |
statusBadge.ts | useStatusBadge(): workspace status labels and badge classes |
subdomain.ts | extractSubdomain(), useSubdomain(), formatDomain() |
theme.svelte.ts | initializeTheme(), useAppearance(), updateAppearance(), updateTheme(), themeState() |
twoFactorAuth.svelte.ts | useTwoFactorAuth(), twoFactorAuthState() (QR code, setup key, recovery codes via useHttp) |
users/assignUserPermissions.svelte.ts | State for the assign-permissions dialog |
utils.ts | cn(), toUrl() |
Generated files
| Generator | Output | Import as |
|---|---|---|
Wayfinder (Vite plugin or php artisan wayfinder:generate --with-form) | routes/, actions/, wayfinder/ | @/routes/users, @/actions/Modules/Settings/Http/Controllers/ProfileController |
php artisan typescript:transform | types/Modules/<Module>/Data and .../Enums from Spatie Data classes and enums in app/ and Modules/ | import type { DomainData } from '@/types/Modules/Tenant/Data' |
php artisan erag:generate-lang | lang/<locale>/…json | Read by svelteLang() |
The page prop types we wrote by hand live alongside the generated ones (types/Tenants/tenants.ts, types/Users/users.ts, types/Roles/roles.ts), and @/types re-exports them. For how to call the Wayfinder functions, see Inertia.
TIP
composer lint runs typescript:transform before it starts the frontend linters. That way the generated types never drift away from the PHP classes.
Shared props
Every page receives the props below from HandleInertiaRequests. Their type is SharedData, declared in types/global.d.ts.
| Prop | Type | Content |
|---|---|---|
name | string | App name (per-domain "App name", or the tenant company on tenant domains) |
auth | Auth | user, isTenant, permissions, isSuperAdmin |
locale, userLocale, defaultLocale | string | Active, user-selected and domain default locale |
languages | LanguageOption[] | Selectable languages |
menus, setupMenus | NavItem[] | Sidebar trees, already filtered by permission |
layout | LayoutSettings | app_layout, sidebar_variant, sidebar_collapsible, auth_layout |
sidebarOpen | boolean | Sidebar cookie state |
appUrl, domain | string (domain can be null) | App URL and central domain |
permissionsConfig | not declared in SharedData (unknown) | Grouped permissions used by the permission dialogs |
Shared props come from the reactive page object. Props that belong to one page come from $props():
<script lang="ts">
import { page } from '@inertiajs/svelte';
let { canResetPassword }: { canResetPassword: boolean } = $props();
const user = $derived(page.props.auth.user);
</script>Because types/global.d.ts registers SharedData with Inertia, page.props is typed in every file. The same file declares a global PageProps<T> type (T & SharedData).
Permissions on the frontend
Rather than digging through page.props.auth yourself, call usePermission() from lib/permission.ts.
can(...names)returnstruefor a super admin, or when the user holds any of the permissions you pass.- The same page runs on central and tenant domains, so pass both permission names together.
<script lang="ts">
import { usePermission } from '@/lib/permission';
const { can } = usePermission();
</script>
{#if can('Create User', 'Create Tenant User')}
<CommonButton>…</CommonButton>
{/if}INFO
Hiding a button just keeps the UI tidy. The real protection is the permission: middleware on the server routes. See Users, roles & permissions.
Language works the same way. useLanguage() from lib/language.ts gives you getters (language.languages, language.userLocale) and changeLanguage(). Read the reactive values through the object and don't destructure them.
Translations
Always import the helper from the Svelte subpath, @erag/lang-sync-inertia/svelte. Importing from the package root breaks the build.
<script lang="ts">
import { svelteLang } from '@erag/lang-sync-inertia/svelte';
const { __ } = svelteLang();
</script>
<AppHead title={__('modules.user.index.title')} />- Each key points to
lang/<locale>/modules/<feature>.php. - Running
php artisan erag:generate-langexports them toresources/js/lang/<locale>/modules/<feature>.json. - Placeholders behave just like they do in Laravel:
__('modules.user.index.delete_confirm.message', { name: user.name }). - You also get
trans,transChoiceandtrans_choicefromsvelteLang().
Localization has the full story.
Related files
resources/js/app.ts: app entry, default layoutsvite.config.ts: Inertia, Svelte, Tailwind and Wayfinder (formVariants: true) pluginsresources/js/types/global.d.ts:SharedData,PageProps<T>app/Http/Middleware/HandleInertiaRequests.php: shared propsresources/js/lib/: shared logiceslint.config.js: lint rules
INFO
When svelte-check loads vite.config.ts, the config sets LARAVEL_BYPASS_ENV_CHECK. This lets you type check without a running Laravel environment.