---

name: react-project-structure description: File and folder organization conventions for React + Vite + shadcn/ui projects. Use when creating new components, organizing files, deciding folder structure, naming files/folders, or reviewing project organization. Covers folder-per-component vs flat structure, naming conventions, barrel exports, internal elements, and form patterns.

React Project Structure Guidelines

Core Conventions

Folder vs Flat Decision

Internal Folder Naming

Important: Only create components/ or containers/ folders in pages when helpers are shared by multiple sibling pages. For single-page helpers, keep files flat in the page folder.

Directory Structure

Copysrc/
├── components/          # Shared/reusable components
│   ├── Header/          # Standalone component (PascalCase at top level OK)
│   │   ├── index.js
│   │   ├── Header.jsx
│   │   ├── elements/
│   │   └── __tests__/   # Tests can live in component folder
│   ├── prompts/         # Grouping folder (flat structure)
│   │   ├── index.js
│   │   ├── LoginPrompt.jsx
│   │   ├── SignupPrompt.jsx
│   │   ├── elements/    # Internal primitives
│   │   └── __tests__/   # Or in grouping folder for multiple components
│   ├── dialogs/
│   │   ├── PricingSliderDialog/  # Complex → folder-per-component
│   │   │   ├── index.js
│   │   │   ├── PricingSliderDialog.jsx
│   │   │   ├── hooks/
│   │   │   └── elements/
│   │   └── ConfirmDialog.jsx    # Simple → flat
│   ├── pricing/         # Mixed: flat files + nested folders OK
│   │   ├── index.js
│   │   ├── CustomPricingCard.jsx
│   │   ├── StandardPricingCard.jsx
│   │   ├── PricingSlider/       # Complex component gets folder
│   │   └── elements/
│   ├── LanguageDropdown/
│   │   ├── index.js
│   │   ├── LanguageDropdown.jsx
│   │   ├── flags/       # Domain-specific assets folder
│   │   └── elements/
│   ├── form/            # Form utilities pattern
│   │   ├── index.js
│   │   ├── FormController.jsx
│   │   ├── FormField.jsx
│   │   ├── elements/    # Shared primitives
│   │   └── containers/  # Layout utilities (not layouts/)
│   └── ui/              # shadcn/ui primitives ONLY
├── layouts/
├── pages/
│   ├── admin/Users/
│   │   ├── index.js
│   │   ├── UsersPage.jsx
│   │   └── Toolbar/     # Single-page helper → flat in page folder
│   ├── errors/          # Multiple pages sharing helpers
│   │   ├── General/
│   │   ├── Network/
│   │   ├── NotFound/
│   │   ├── components/  # Shared by all error pages
│   │   └── containers/  # Shared layout utilities
│   └── public/Pricing/
│       ├── index.js
│       ├── PricingPage.jsx
│       ├── EnterpriseTab.jsx   # Single-page helpers → flat
│       └── StandardCards.jsx
└── hooks/               # Shared hooks

File Patterns

Export Style

index.js (barrel)

Copyexport { ComponentName } from './ComponentName'

ComponentName.jsx

Copyexport const ComponentName = ({ ...props }) => {
  return (/* ... */)
}

When to Extract vs Inline

Inline Helpers Example

Copy// ProfileDialog.jsx
const Row = ({ children }) => (
  <div className='flex items-center gap-2'>{children}</div>
)

export const ProfileDialog = ({ profile }) => {
  /* ... */
}

Form Utilities Pattern

Copyform/
├── index.js              # Exports: FormController, FormField, FormRoot, FormFields
├── FormController.jsx    # Wrapper for controlled inputs (Select, Switch)
├── FormField.jsx         # Wrapper for native inputs (Input, Textarea)
├── elements/             # Shared primitives (Error, Label, FieldWrapper)
└── containers/           # Layout utilities (FormRoot, FormFields)

Use containers/ (not layouts/) to avoid confusion with page layouts.

src/components/ui/ Rules

• Reserved for shadcn/ui primitives only
• Install via npx shadcn@latest add <component>
• Uses regular functions + default exports (shadcn convention)
• Custom wrappers go in src/components/, not ui/

Import Examples

Copyimport { LoginPrompt, SignupPrompt } from '@/components/prompts'
import { PricingSliderDialog } from '@/components/dialogs'
import { Button, Card } from '@/components/ui'
import { FormController, FormRoot } from '@/components/form'