Architecture Vue
All the Vue-specific code sits in resources/js. For the Laravel side (modules, tenancy, auth), see Core architecture.
Overview
Each request passes through a controller in a Laravel module and comes out as a Vue page wrapped in a layout:
Route → Controller → Service → Inertia::render('users/Index', props)
→ pages/users/Index.vue (+ shared props)
→ default layout picked in app.ts (or the page's own)The client starts in resources/js/app.ts. There's no resolve callback in it, because the @inertiajs/vite plugin in vite.config.ts loads pages from resources/js/pages for you.
app.ts also picks a default layout from the page name: auth/* → AuthLayout, settings/* → AppLayout + settings/Layout.vue, and everything else → AppLayout. Layouts has the details.
The browser title comes out as "<page title> - <VITE_APP_NAME>". On boot, initializeTheme() from composables/useAppearance.ts applies light, dark or system mode, and initializeFlashToast() from lib/flashToast.ts starts turning server flash data 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 |
|---|---|
pages/ | Inertia pages (PascalCase .vue): auth/, errors/, roles/, settings/, setup/, tenants/, users/, plus Dashboard.vue and Home.vue |
layouts/ | AppLayout.vue, AuthLayout.vue, their variants in app/ and auth/, and settings/Layout.vue |
components/common/ | The kit's form kit: CommonInput, CommonSelect, ConfirmDialog, … |
components/ui/ | shadcn-vue primitives (reka-ui) |
components/ | App shell and feature components: AppSidebar, AppHeader, NavMain, UserMenuContent, … |
composables/ | Shared logic as useX.ts |
lib/ | utils.ts (cn, toUrl) and flashToast.ts |
types/ | Hand-written and generated TypeScript types |
lang/ | Generated translation JSON |
routes/, actions/, wayfinder/ | Generated by Wayfinder, git-ignored |
Every component uses <script setup lang="ts">. ESLint checks for import type on type-only imports, ordered import groups, 1TBS braces and blank lines around control statements. We don't write code comments; that's a project rule in .ai/rules/general.md. For naming, see Conventions.
Composables
| File | Exports |
|---|---|
useAppearance.ts | useAppearance(), initializeTheme(), updateTheme() |
useConfirmDialog.ts | useConfirmDialog() → confirm(options), setLoading() |
useCurrentUrl.ts | useCurrentUrl() → isCurrentUrl, isCurrentOrParentUrl, whenCurrentUrl |
useDebounce.ts | useDebounce(source, delay), useDebounceFn(fn, delay) |
useInitials.ts | getInitials(), useInitials() |
useLanguage.ts | useLanguage(), DEFAULT_LANGUAGE_VALUE |
usePermission.ts | usePermission() → can(...permissions) |
useSecret.ts | generateSecret(), useSecret() |
useSlug.ts | slugify(), useSlug() |
useStatusBadge.ts | useStatusBadge() → workspace status labels and badge classes |
useSubdomain.ts | extractSubdomain(), useSubdomain() → formatDomain() |
useTwoFactorAuth.ts | useTwoFactorAuth(): QR code, setup key and recovery codes via useHttp |
users/useAssignUserPermissions.ts | State for the assign-permissions dialog |
Generated files
| Output | Generated by | Import from |
|---|---|---|
| Route and controller functions | Wayfinder Vite plugin (formVariants: true) or php artisan wayfinder:generate --with-form | @/routes/..., @/actions/... |
Types for Data classes and enums in app/ and Modules/ | php artisan typescript:transform | @/types/Modules/<Module>/Data, .../Enums |
| Translation JSON | php artisan erag:generate-lang | Read by vueLang() |
The page prop types we wrote by hand are in types/Tenants/tenants.ts, types/Users/users.ts and types/Roles/roles.ts, and you can import them from @/types. To see how the Wayfinder functions are called, read Inertia → Wayfinder routes.
TIP
composer lint runs wayfinder:generate --with-form and typescript:transform before the frontend linters. That way the generated files always match your PHP classes.
Shared props
Every page gets these props from HandleInertiaRequests. Their type is SharedData, in types/global.d.ts.
| Prop | Content |
|---|---|
name | App name (per-domain "App name", or the tenant company on tenant domains) |
auth | user, isTenant, permissions, isSuperAdmin |
locale, userLocale, defaultLocale | Active, user-selected and domain default locale |
languages | Selectable languages (LanguageOption[]) |
menus, setupMenus | Sidebar trees (NavItem[]), already filtered by permission |
layout | LayoutSettings: app_layout, sidebar_variant, sidebar_collapsible, auth_layout |
sidebarOpen | Sidebar cookie state |
appUrl, domain | App URL and central domain |
permissionsConfig | Grouped permissions for the permission dialogs (not declared in SharedData) |
Since types/global.d.ts registers SharedData with Inertia and declares a global PageProps<T>, usePage() is typed without any imports:
const page = usePage<PageProps>();
const user = computed(() => page.props.auth.user);Where a composable exists (usePermission, useLanguage), use it instead of reading the props yourself.
Permissions on the frontend
Menu items the user isn't allowed to see are already removed by the backend. Inside a page, you hide buttons and actions with usePermission():
const { can } = usePermission();
const canCreate = can('Create User', 'Create Tenant User');can() returns true if the user has any of the permissions you pass, and it's always true for super admins. Pass both the central and the tenant permission name, so the same check works on every domain.
WARNING
Hiding a button doesn't secure anything. You still need the permission: middleware on the backend route. See Users, roles & permissions.
Translations
lang/<locale>/modules/<feature>.php
→ php artisan erag:generate-lang
→ resources/js/lang/<locale>/modules/<feature>.json
→ __('modules.<feature>.<key>') in Vue<script setup lang="ts">
import { vueLang } from '@erag/lang-sync-inertia/vue';
const { __ } = vueLang();
</script>
<template>
<p>{{ __('modules.user.index.delete_confirm.message', { name: user.name }) }}</p>
</template>vueLang() also gives you trans, transChoice and trans_choice. There's more in Localization.
WARNING
Always import from the /vue subpath. The package root exports the React and Svelte helpers as well, and importing it breaks the build.
Related files
resources/js/app.ts: entry point, default layouts, theme and flash toastsvite.config.ts: the Inertia, Wayfinder (formVariants: true), Tailwind and Vue DevTools pluginsapp/Http/Middleware/HandleInertiaRequests.php: where the shared props come fromresources/js/types/global.d.ts:SharedDataandPagePropsresources/js/composables/usePermission.ts,useLanguage.tsresources/js/lib/flashToast.ts,lib/utils.tscomponents.json: the shadcn-vue config