--- title: "React Kit Frontend Architecture" description: "How resources/js is organised in the React kit: folder map, page and layout resolution, shared props, permission checks and translations with Inertia." --- # Architecture All the React-specific code sits in `resources/js`. For the Laravel side (modules, tenancy, auth), see [Core architecture](/docs/core/architecture). ## Overview Every request hits Laravel first. Your controller returns an Inertia response, then the React app finds the matching page and renders it inside a default layout. ```text Controller → Inertia::render('users/index', props) → @inertiajs/vite resolves pages/users/index.tsx → app.tsx picks a default layout from the page name → page renders with its props + shared props ``` The app is created in `resources/js/app.tsx`. A few things to know about it: - There's no `resolve` callback. The `@inertiajs/vite` plugin in `vite.config.ts` finds pages in `resources/js/pages` for you. - The `layout` callback chooses a default layout from the page name, as shown in the table below. - `withApp` wraps every page in `TooltipProvider` and the sonner `Toaster`. - It runs with `strictMode: true`, and the Vite React plugin runs the React Compiler. - `initializeTheme()` (from `hooks/use-appearance.tsx`) applies light, dark or system mode when the page loads. | Page name starts with | Default layout | | --- | --- | | `auth/` | `AuthLayout` | | `settings/` | `AppLayout` wrapping `settings/layout.tsx` | | anything else | `AppLayout` | Any page can override this with a static `layout` property, which [Layouts](/docs/react/layouts) explains. ::: details View app.tsx ```tsx 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; } }, strictMode: true, withApp(app) { return ( {app} ); }, progress: { color: '#4B5563' }, }); initializeTheme(); ``` ::: ## Folder map | Folder / file | Purpose | | --- | --- | | `app.tsx` | `createInertiaApp`, default layouts, providers, theme | | `pages/` | Inertia pages: `auth/`, `errors/`, `roles/`, `settings/`, `setup/`, `tenants/`, `users/`, `dashboard.tsx`, `home.tsx` | | `layouts/` | `app-layout.tsx`, `auth-layout.tsx`, their variants in `app/` and `auth/`, and `settings/layout.tsx` | | `components/common/` | The kit's form components (`common-input.tsx`, `common-select.tsx`, `confirm-dialog.tsx`, …) | | `components/ui/` | shadcn/ui primitives (Radix UI) | | `components/` | App shell and feature components (`app-sidebar.tsx`, `app-header.tsx`, `nav-main.tsx`, `user-menu-content.tsx`, …) | | `hooks/` | `use-x.ts(x)` hooks (`use-permission`, `use-confirm-dialog`, `use-language`, …) | | `lib/utils.ts` | `cn()` and `toUrl()` | | `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 | kebab-case `.tsx`, default export | `pages/tenants/index.tsx` → `TenantsIndex` | | Inertia page name | kebab-case path, no extension | `Inertia::render('tenants/index')` | | Page-only component | `partials/` next to the page | `pages/users/partials/user-form-modal.tsx` | | Shared component | kebab-case file, PascalCase component | `user-menu-content.tsx` → `UserMenuContent` | | Form component | `common-` prefix, named + default export | `common-select.tsx` → `CommonSelect` | | Hook | `use-x.ts` exporting `useX()` | `hooks/use-permission.ts` | | UI primitive | shadcn/ui file | `components/ui/dialog.tsx` | ESLint checks these for you. It wants `import type` for type-only imports, alphabetised import groups, the React Hooks rules, 1TBS braces and a blank line around control statements. ### Hooks | File | Exports | | --- | --- | | `use-appearance.tsx` | `useAppearance()`, `initializeTheme()`, `updateTheme()` | | `use-clipboard.ts` | `useClipboard()` | | `use-confirm-dialog.ts` | `useConfirmDialog()` → `confirm(options)`, `setLoading()`; also exports `confirm` directly | | `use-current-url.ts` | `useCurrentUrl()` → `isCurrentUrl`, `isCurrentOrParentUrl`, `whenCurrentUrl` | | `use-debounce.ts` | `useDebounce(value, delay)`, `useDebounceFn(fn, delay)` | | `use-flash-toast.ts` | `useFlashToast()` (used by the `Toaster`) | | `use-initials.tsx` | `getInitials()`, `useInitials()` | | `use-language.ts` | `useLanguage()`, `DEFAULT_LANGUAGE_VALUE`, `toLocaleValue()`, `transformLocale()` | | `use-mobile.tsx`, `use-mobile-navigation.ts` | `useIsMobile()`, `useMobileNavigation()` | | `use-permission.ts` | `usePermission()` → `can(...permissions)` | | `use-secret.ts` | `generateSecret()`, `useSecret()` | | `use-slug.ts` | `slugify()`, `useSlug()` | | `use-status-badge.ts` | `useStatusBadge()` → workspace status labels and badge classes | | `use-subdomain.ts` | `extractSubdomain()`, `useSubdomain()` | | `use-two-factor-auth.ts` | `useTwoFactorAuth()` (QR code, setup key, recovery codes via `useHttp`) | | `users/use-assign-user-permissions.ts` | State for the assign-permissions dialog | ### Generated files | Command | Output | Import as | | --- | --- | --- | | Wayfinder Vite plugin (`npm run dev` / `build`) | `routes/`, `actions/` | `@/routes/users`, `@/actions/Modules//Http/Controllers/` | | `php artisan typescript:transform` | `types/Modules//Data` and `.../Enums` | `import type { DomainData } from '@/types/Modules/Tenant/Data'` | | `php artisan erag:generate-lang` | `lang//modules/.json` | through `reactLang()` | Because Wayfinder runs with `formVariants: true`, each route function also gets a `.form()` variant. You'll find usage in [Inertia → Wayfinder routes](/docs/react/inertia#wayfinder-routes). Page prop types that we wrote by hand sit next to the generated ones (`types/Tenants/tenants.ts`, `types/Users/users.ts`, `types/Roles/roles.ts`) and you can import them from `@/types`. For pagination, use `LengthAwarePaginator` from `@/types/Illuminate`. ::: tip `composer lint` runs `typescript:transform` before the frontend linters. That keeps the generated types in step with your PHP classes. ::: ## Shared props Every page gets the props below from `HandleInertiaRequests`. Their type is `SharedData` in `types/global.d.ts`. | Prop | Type | Content | | --- | --- | --- | | `name` | `string` | App name (per-domain "App name" or tenant company on tenant domains) | | `auth` | `Auth` | `user`, `isTenant`, `permissions`, `isSuperAdmin` | | `locale`, `userLocale`, `defaultLocale` | `string` (`userLocale` may be `null`) | 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`, `string \| null` | App URL and central domain | | `permissionsConfig` | `PermissionGroup[]` | Grouped permissions for the permission dialogs | `permissionsConfig` isn't declared on `SharedData`. It falls under the type's `[key: string]: unknown` index signature, so you have to cast it where you read it (`hooks/users/use-assign-user-permissions.ts` casts it to `PermissionGroup[]`). Since `SharedData` is registered with Inertia, `usePage().props` is typed without passing a generic: ```tsx const { auth } = usePage().props; ``` Props that belong to one page come in as the component's own props. Type them with a local `Props` type and destructure them in the signature, like `Login({ status, canResetPassword }: Props)` in `pages/auth/login.tsx`. ## Permissions on the frontend Menus arrive already filtered by permission from the backend. Inside a page, you hide buttons and actions yourself with `usePermission()`: ```tsx const { can } = usePermission(); {can('Create User', 'Create Tenant User') && …} ``` - `can()` returns `true` when the user has **any** of the permissions you pass. - For super admins (`auth.isSuperAdmin`) it's always `true`. - Pass the central and the tenant permission name together, and the same page works on both domains. ::: warning Hiding a button doesn't protect anything on its own. The route still has to check the permission with `permission:` middleware. ::: ## Translations Each string the user sees goes through `__()` from `reactLang()`. Import it from the **React subpath**, because the root import breaks the build. ```tsx import { reactLang } from '@erag/lang-sync-inertia/react'; const { __ } = reactLang(); ``` - A key points to `lang//modules/.php`. - Running `php artisan erag:generate-lang` exports the keys to `resources/js/lang//modules/.json`. - Pass replacements as the second argument: `__('modules.user.index.delete_confirm.message', { name: user.name })`. - Besides `__`, `reactLang()` returns `trans`, `transChoice` and `trans_choice`. - `useLanguage()` (`languages`, `changeLanguage`) lists the languages and switches between them. [Localization](/docs/core/localization) has the rest. ## Related files - `resources/js/app.tsx`: the app entry, with default layouts and providers - `vite.config.ts`: Inertia, React (with React Compiler), Tailwind and Wayfinder plugins - `app/Http/Middleware/HandleInertiaRequests.php`: where the shared props come from - `resources/js/types/global.d.ts`: `SharedData`, global `PageProps`, Inertia type registration - `resources/js/hooks/use-permission.ts`, `use-language.ts`: permission and language helpers - `eslint.config.js`, `tsconfig.json`: lint and type-check rules