Project File Organization

When to use this skill

• New Projects: Initial folder structure design

• Project Growth: Refactoring when complexity increases

• Team Standardization: Establish consistent structure

Instructions

Step 1: React/Next.js Project Structure

src/ ├── app/ # Next.js 13+ App Router │ ├── (auth)/ # Route groups │ │ ├── login/ │ │ └── signup/ │ ├── (dashboard)/ │ │ ├── layout.tsx │ │ ├── page.tsx │ │ └── settings/ │ ├── api/ # API routes │ │ ├── auth/ │ │ └── users/ │ └── layout.tsx │ ├── components/ # UI Components │ ├── ui/ # Reusable UI (Button, Input) │ │ ├── Button/ │ │ │ ├── Button.tsx │ │ │ ├── Button.test.tsx │ │ │ └── index.ts │ │ └── Input/ │ ├── layout/ # Layout components (Header, Footer) │ ├── features/ # Feature-specific components │ │ ├── auth/ │ │ └── dashboard/ │ └── shared/ # Shared across features │ ├── lib/ # Utilities & helpers │ ├── utils.ts │ ├── hooks/ │ │ ├── useAuth.ts │ │ └── useLocalStorage.ts │ └── api/ │ └── client.ts │ ├── store/ # State management │ ├── slices/ │ │ ├── authSlice.ts │ │ └── userSlice.ts │ └── index.ts │ ├── types/ # TypeScript types │ ├── api.ts │ ├── models.ts │ └── index.ts │ ├── config/ # Configuration │ ├── env.ts │ └── constants.ts │ └── styles/ # Global styles ├── globals.css └── theme.ts

Step 2: Node.js/Express Backend Structure

src/ ├── api/ # API layer │ ├── routes/ │ │ ├── auth.routes.ts │ │ ├── user.routes.ts │ │ └── index.ts │ ├── controllers/ │ │ ├── auth.controller.ts │ │ └── user.controller.ts │ └── middlewares/ │ ├── auth.middleware.ts │ ├── errorHandler.ts │ └── validation.ts │ ├── services/ # Business logic │ ├── auth.service.ts │ ├── user.service.ts │ └── email.service.ts │ ├── repositories/ # Data access layer │ ├── user.repository.ts │ └── session.repository.ts │ ├── models/ # Database models │ ├── User.ts │ └── Session.ts │ ├── database/ # Database setup │ ├── connection.ts │ ├── migrations/ │ └── seeds/ │ ├── utils/ # Utilities │ ├── logger.ts │ ├── crypto.ts │ └── validators.ts │ ├── config/ # Configuration │ ├── index.ts │ ├── database.ts │ └── env.ts │ ├── types/ # TypeScript types │ ├── express.d.ts │ └── models.ts │ ├── tests/ # Tests │ ├── unit/ │ ├── integration/ │ └── e2e/ │ └── index.ts # Entry point

Step 3: Feature-Based Structure (Large-Scale Apps)

src/ ├── features/ │ ├── auth/ │ │ ├── components/ │ │ │ ├── LoginForm.tsx │ │ │ └── SignupForm.tsx │ │ ├── hooks/ │ │ │ └── useAuth.ts │ │ ├── api/ │ │ │ └── authApi.ts │ │ ├── store/ │ │ │ └── authSlice.ts │ │ ├── types/ │ │ │ └── auth.types.ts │ │ └── index.ts │ │ │ ├── products/ │ │ ├── components/ │ │ ├── hooks/ │ │ ├── api/ │ │ └── types/ │ │ │ └── orders/ │ ├── shared/ # Shared across features │ ├── components/ │ ├── hooks/ │ ├── utils/ │ └── types/ │ └── core/ # App-wide ├── store/ ├── router/ └── config/

Step 4: Naming Conventions

File Names:

Components: PascalCase.tsx Hooks: camelCase.ts (useAuth.ts) Utils: camelCase.ts (formatDate.ts) Constants: UPPER_SNAKE_CASE.ts (API_ENDPOINTS.ts) Types: camelCase.types.ts (user.types.ts) Tests: *.test.ts, *.spec.ts

Folder Names:

kebab-case: user-profile/ camelCase: userProfile/ (optional: hooks/, utils/) PascalCase: UserProfile/ (optional: components/)

✅ Consistency is key (entire team uses the same rules)

Variable/Function Names:

// Components: PascalCase const UserProfile = () => {};

// Functions: camelCase function getUserById() {}

// Constants: UPPER_SNAKE_CASE const API_BASE_URL = 'https://api.example.com';

// Private: _prefix (optional) class User { private _id: string;

private _hashPassword() {} }

// Booleans: is/has/can prefix const isAuthenticated = true; const hasPermission = false; const canEdit = true;

Step 5: index.ts Barrel Files

components/ui/index.ts:

// ✅ Good example: Re-export named exports export { Button } from './Button/Button'; export { Input } from './Input/Input'; export { Modal } from './Modal/Modal';

// Usage: import { Button, Input } from '@/components/ui';

❌ Bad example:

// Re-export everything (impairs tree-shaking) export * from './Button'; export * from './Input';

Output format

Project Template

my-app/ ├── .github/ │ └── workflows/ ├── public/ ├── src/ │ ├── app/ │ ├── components/ │ ├── lib/ │ ├── types/ │ └── config/ ├── tests/ ├── docs/ ├── scripts/ ├── .env.example ├── .gitignore ├── .eslintrc.json ├── .prettierrc ├── tsconfig.json ├── package.json └── README.md

Constraints

Required Rules (MUST)

• Consistency: Entire team uses the same rules

• Clear Folder Names: Roles must be explicit

• Max Depth: Recommend 5 levels or fewer

Prohibited (MUST NOT)

• Excessive Nesting: Avoid 7+ levels of folder depth

• Vague Names: Avoid utils2/, helpers/, misc/

• Circular Dependencies: Prohibit A → B → A references

Best practices

• Colocation: Keep related files close (component + styles + tests)

• Feature-Based: Modularize by feature

• Path Aliases: Simplify imports with @/

tsconfig.json:

{ "compilerOptions": { "baseUrl": ".", "paths": { "@/": ["./src/"], "@/components/": ["./src/components/"], "@/lib/": ["./src/lib/"] } } }

Usage:

// ❌ Bad example import { Button } from '../../../components/ui/Button';

// ✅ Good example import { Button } from '@/components/ui';

References

• React File Structure

• Node.js Best Practices

• Clean Architecture

Metadata

Version

• Current Version: 1.0.0

• Last Updated: 2025-01-01

• Compatible Platforms: Claude, ChatGPT, Gemini

Tags

#file-organization #project-structure #folder-structure #naming-conventions #utilities

Examples

Example 1: Basic usage

Example 2: Advanced usage