# Organizing Project Files

> Provides file organization conventions for React and Next.js projects. Use when creating new files, components, hooks, utilities, or services. Triggers on questions like "where should this go?", "where do I put this?", or when deciding between colocating vs grouping files.

- Skill: `augmnt/organizing-project-files` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add augmnt/organizing-project-files`
- Raw SKILL.md: https://api.skillmd.com/api/skills/augmnt/organizing-project-files/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: augmnt (https://skillmd.com/u/augmnt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/augmnt/organizing-project-files

---


# Organizing Project Files

Colocate by feature when possible. Group by type only for truly shared code.

## Standard Layout

```
src/
├── app/                    # Next.js App Router (or pages/)
├── components/
│   ├── ui/                 # Reusable primitives (Button, Modal)
│   └── [feature]/          # Feature-specific (auth/, dashboard/)
├── hooks/                  # Custom React hooks
├── lib/                    # Core utilities, clients, constants
├── services/               # API calls, external integrations
├── stores/                 # State management
└── types/                  # TypeScript definitions
```

## Placement Quick Reference

| "I need..." | Location |
|-------------|----------|
| A button | `components/ui/Button.tsx` |
| A login form | `components/auth/LoginForm.tsx` |
| User data fetching | `services/user.ts` or `hooks/queries/useUser.ts` |
| Date formatter | `lib/utils.ts` |
| Auth state | `stores/auth.ts` |
| Supabase types | `types/supabase.ts` (generated) |
| Custom type | `types/index.ts` or colocate |

## Naming

- Components: `PascalCase.tsx`
- Hooks: `useCamelCase.ts`
- Utilities: `camelCase.ts`
- Types: `camelCase.ts`

## Colocation Pattern

For complex features, keep related files together:

```
components/auth/
├── LoginForm.tsx
├── LoginForm.test.tsx
├── useLoginForm.ts
└── login-schema.ts
```

## Advanced Patterns

For App Router specifics, barrel files, and monorepo structures, see [PATTERNS.md](PATTERNS.md).