laravel-inertia-react-structure

name

laravel-inertia-react-structure

description

Frontend structure conventions for Laravel Inertia React applications based on Spatie's production practices. Use when creating, scaffolding, or reviewing frontend code in a Laravel Inertia React project. Triggers on creating React components, pages, modules, organizing frontend directories, setting up Inertia pages, structuring a React frontend within Laravel, or when the user asks about frontend file organization in an Inertia app.

Laravel Inertia React Frontend Structure

Based on Spatie's conventions for structuring production Laravel Inertia React applications.

Directory Structure

Four base directories under resources/js:

resources/js/
├── common/       # Generic, reusable code portable across projects
├── modules/      # Project-specific code shared across multiple pages
├── pages/        # Inertia page components
└── shadcn/       # Auto-generated shadcn/ui components (if used)

common vs modules: ask "Does it relate to a domain or feature?" If yes → modules. If it's generic and project-agnostic → common.

Naming Conventions

• Components and React contexts: PascalCase (e.g. Button.tsx, AuthContext.tsx)
• Other files (helpers, hooks, constants, stores): camelCase (e.g. useAuth.ts, formatDate.ts)
• Directories: kebab-case (e.g. date-picker/, user-management/)

Module Organization

Small modules have a few top-level files. Larger modules organize by type:

modules/agenda/
├── components/
├── contexts/
├── constants/
├── helpers/
├── hooks/
├── stores/
└── types.ts          # or types/ directory if large

The common/ directory follows the same structure.

Pages Directory

Pages mirror the URL structure. Components are suffixed with Page.

pages/
├── layouts/              # Global layouts
├── admin/
│   ├── layouts/          # Section-specific layouts
│   ├── users/
│   │   ├── components/   # Page-specific partials
│   │   ├── helpers/
│   │   ├── IndexPage.tsx
│   │   └── EditPage.tsx
│   └── DashboardPage.tsx
└── auth/
    ├── LoginPage.tsx
    └── RegisterPage.tsx

React Component Conventions

Use function declarations (not const arrow functions) and named exports exclusively:

// Correct
export function Button({ variant, className }: ButtonProps) {
  return <button className={cn(variant, className)}>Click</button>;
}

// Wrong: const + default export
const Button = ({ variant }) => { ... };
export default Button;

One component per file. No barrel files (index.ts re-exports).

Import Organization

Two blocks separated by a blank line: library imports first, then application imports. Use absolute paths with aliases (@/):

import { useState } from "react";
import { cn } from "@/common/helpers/cn";

import { useAgenda } from "@/modules/agenda/hooks/useAgenda";
import { AgendaItem } from "@/modules/agenda/components/AgendaItem";

Props

Sort alphabetically, with className and children last:

interface DialogProps {
  onClose: () => void;
  open: boolean;
  title: string;
  className?: string;
  children: React.ReactNode;
}

Stylesheets

Use Tailwind. Single app.css for most projects. Larger projects split into:

resources/css/
├── base/
├── components/
└── utilities/

Multi-Zone Applications

For apps with distinct sections (e.g. admin/client), introduce apps/:

resources/js/
├── common/           # Shared across all zones
├── modules/          # Global modules shared across zones
├── apps/
│   ├── admin/
│   │   ├── modules/  # Admin-specific modules
│   │   ├── pages/
│   │   └── app.tsx
│   └── client/
│       ├── modules/  # Client-specific modules
│       ├── pages/
│       └── app.tsx
└── shadcn/

shadcn/ui Usage

Abstract shadcn components into simpler, project-specific implementations rather than using the low-level API directly in application code. Place abstractions in common/ or modules/ as appropriate.