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