---
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