Skip to main content

CODITECT Production Folder Standard - Frontend Projects

Version: 1.0.0 Last Updated: 2025-12-04 Applies To: React, Vue, Svelte, Next.js, Angular frontend projects Status: Production Standard

Overview​

This standard defines the production-ready folder structure for frontend web applications. It applies to single-page applications (SPAs), server-side rendered (SSR) apps, and static site generators.

Key Principles:

  • Component-centric organization - UI components are primary
  • Feature-based grouping - Business logic grouped by domain
  • Colocation - Tests and styles live WITH components
  • Shallow nesting - Maximum 3-4 levels deep
  • Clear separation - Shared UI vs feature-specific code

Required Root Directory Structure​

✅ Must Have in Root​

project-root/
├── README.md                    # User documentation
├── CLAUDE.md                    # AI agent context
├── CONTRIBUTING.md              # Contribution guidelines
├── CHANGELOG.md                 # Version history
├── LICENSE                      # License file
├── SECURITY.md                  # Security policy
├── package.json                 # Dependencies and scripts
├── package-lock.json            # Locked dependency versions
├── tsconfig.json                # TypeScript configuration
├── .gitignore                   # Git ignore rules
├── .eslintrc.js                 # ESLint configuration
├── .prettierrc                  # Prettier formatting
├── .editorconfig                # Editor consistency
├── .env.example                 # Environment template
└── index.html                   # HTML entry (Vite/SPA)

❌ Must NOT Have in Root​

❌ Component files (*.tsx, *.vue)
❌ Test files (*test.ts, *.spec.js)
❌ Session exports (EXPORT-*.txt)
❌ Research documents (RESEARCH-*.md)
❌ Build artifacts (dist/, build/ contents)
❌ Temporary files (*.tmp, *.bak)
❌ Analysis documents (ANALYSIS-*.md)
❌ Implementation plans (PLAN-*.md, CHECKPOINT-*.md)

Source Code Organization​

Option 1: Next.js App Router (Modern - 2024+)​

app/                             # Next.js App Router
├── (marketing)/                 # Route group (not in URL)
│   ├── page.tsx                 # Creates /marketing route
│   └── layout.tsx               # Shared layout
├── dashboard/
│   ├── page.tsx                 # Creates /dashboard route
│   ├── layout.tsx               # Dashboard layout
│   ├── loading.tsx              # Loading skeleton
│   ├── error.tsx                # Error boundary
│   └── _components/             # Private components (no routing)
│       ├── DashboardWidget.tsx
│       └── DashboardWidget.test.tsx
├── api/                         # API routes (if full-stack)
│   └── users/
│       └── route.ts             # /api/users endpoint
├── _components/                 # Shared private components
└── layout.tsx                   # Root layout

src/                             # Optional: separate source
├── components/                  # Shared UI components ONLY
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx      # Co-located tests
│   │   ├── Button.module.css    # Component styles
│   │   └── index.ts             # Barrel export
│   └── Card/
├── features/                    # Business domain features
│   ├── auth/
│   │   ├── LoginForm.tsx
│   │   ├── useAuth.ts           # Feature hooks
│   │   └── authService.ts       # API calls
│   └── posts/
├── hooks/                       # Shared custom hooks
├── context/                     # React Context providers
├── lib/                         # Utility libraries
│   ├── api-client.ts
│   └── utils.ts
├── styles/                      # Global styles
│   ├── globals.css
│   └── themes/
└── types/                       # Shared TypeScript types

public/                          # Static assets (served at /)
├── images/
├── fonts/
├── favicon.ico
└── robots.txt

Option 2: Create React App / Vite (SPA)​

src/
├── components/                  # Shared UI components
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx
│   │   ├── Button.module.css
│   │   └── index.ts
│   ├── Card/
│   └── Layout/
├── features/                    # Feature modules
│   ├── auth/
│   │   ├── components/          # Auth-specific components
│   │   │   ├── LoginForm.tsx
│   │   │   └── LoginForm.test.tsx
│   │   ├── hooks/
│   │   │   └── useAuth.ts
│   │   ├── services/            # API calls
│   │   │   └── authService.ts
│   │   └── types/
│   │       └── auth.types.ts
│   ├── user/
│   └── posts/
├── pages/                       # Page components (routing)
│   ├── HomePage.tsx
│   ├── DashboardPage.tsx
│   └── NotFoundPage.tsx
├── routes/                      # Route configuration
│   └── AppRoutes.tsx
├── hooks/                       # Shared custom hooks
│   ├── useLocalStorage.ts
│   └── useDebounce.ts
├── context/                     # Global state (Context API)
│   ├── AuthContext.tsx
│   └── ThemeContext.tsx
├── store/                       # State management (Redux/Zustand)
│   ├── slices/
│   └── store.ts
├── services/                    # API clients
│   ├── api.ts
│   └── endpoints/
├── utils/                       # Helper functions
│   ├── formatters.ts
│   └── validators.ts
├── constants/                   # App constants
├── styles/                      # Global styles
│   ├── index.css
│   └── themes/
├── assets/                      # Images, icons (imported)
│   ├── icons/
│   └── images/
├── types/                       # TypeScript type definitions
├── App.tsx                      # Root component
├── main.tsx                     # Entry point
└── index.css                    # Global styles

public/                          # Static assets
├── favicon.ico
├── robots.txt
└── manifest.json

Option 3: Vue 3 (Composition API)​

src/
├── components/                  # Reusable components
│   ├── base/                    # Base UI components
│   │   ├── BaseButton.vue
│   │   └── BaseCard.vue
│   └── shared/                  # Shared business components
├── features/                    # Feature modules
│   ├── auth/
│   │   ├── components/
│   │   ├── composables/         # Vue composables
│   │   └── services/
│   └── posts/
├── views/                       # Page components
│   ├── HomeView.vue
│   └── DashboardView.vue
├── router/                      # Vue Router configuration
│   └── index.ts
├── stores/                      # Pinia stores
│   ├── auth.ts
│   └── user.ts
├── composables/                 # Shared composables
├── services/                    # API clients
├── utils/                       # Utilities
├── styles/                      # Global styles
├── types/                       # TypeScript types
├── App.vue                      # Root component
└── main.ts                      # Entry point

public/                          # Static assets

Documentation Organization​

docs/
├── api/                         # API documentation
│   ├── endpoints.md
│   └── authentication.md
├── architecture/                # Architecture docs
│   ├── adrs/                    # Architecture Decision Records
│   │   ├── README.md
│   │   ├── ADR-001-react-18.md
│   │   └── ADR-002-vite.md
│   ├── C4-context.md
│   ├── C4-container.md
│   └── SOFTWARE-DESIGN-DOCUMENT.md
├── deployment/                  # Deployment guides
│   ├── docker.md
│   ├── github-actions.md
│   └── production.md
├── diagrams/                    # Architecture diagrams
│   ├── dataflow-diagrams.md
│   └── workflow-diagrams.md
├── project-management/          # Project planning
│   ├── PROJECT-PLAN.md
│   ├── TASKLIST-WITH-CHECKBOXES.md
│   └── checkpoints/             # Session checkpoints
│       └── 2025-12-04-checkpoint.md
├── testing/                     # Testing documentation
│   ├── TEST-DRIVEN-DEVELOPMENT.md
│   └── test-strategy.md
└── user-guides/                 # User documentation
    ├── getting-started.md
    └── tutorials/

Testing Organization​

src/components/Button/
├── Button.tsx
├── Button.test.tsx              # Co-located unit test
├── Button.stories.tsx           # Storybook stories
└── Button.module.css

Option 2: Separate Tests Directory (E2E/Integration)​

tests/
├── unit/                        # Unit tests (mirrors src/)
│   ├── components/
│   │   └── Button.test.tsx
│   └── utils/
├── integration/                 # Integration tests
│   └── auth-flow.test.tsx
├── e2e/                         # End-to-end tests
│   ├── user-journey.spec.ts
│   └── fixtures/
│       └── test-data.ts
└── mocks/                       # Test mocks
    └── api-mocks.ts

Configuration Files Organization​

Root Level Only​

.eslintrc.js                     # Linting rules
.prettierrc                      # Code formatting
.editorconfig                    # Editor settings
tsconfig.json                    # TypeScript config
vite.config.ts                   # Vite configuration
next.config.js                   # Next.js configuration
postcss.config.js                # PostCSS configuration
tailwind.config.js               # Tailwind CSS config
vitest.config.ts                 # Vitest test config
playwright.config.ts             # Playwright E2E config
.env.example                     # Environment template
.env.local                       # Local environment (gitignored)

Scripts Organization​

scripts/
├── build.sh                     # Production build
├── test-all.sh                  # Run all tests
├── start-dev.sh                 # Start dev server
├── deploy.sh                    # Deploy to production
└── analyze-bundle.sh            # Bundle analysis

Examples Organization​

examples/
├── basic-usage/                 # Simple examples
│   ├── SimpleComponent.tsx
│   └── README.md
└── advanced-patterns/           # Advanced examples
    ├── ComplexFeature.tsx
    └── README.md

Build Output (Gitignored)​

dist/                            # Vite build output
build/                           # CRA build output
.next/                           # Next.js build output
out/                             # Next.js static export
.nuxt/                           # Nuxt build output
coverage/                        # Test coverage reports
playwright-report/               # Playwright test reports
test-results/                    # Test artifacts
node_modules/                    # Dependencies
.cache/                          # Build cache
.parcel-cache/                   # Parcel cache
.turbo/                          # Turborepo cache

Project Type Detection Rules​

Detect as Frontend if:

  • Has package.json with React/Vue/Svelte/Angular dependencies
  • Has src/components/ or app/ directory
  • Has public/ or static/ directory
  • Has index.html or app/page.tsx
  • Has Vite/Next.js/CRA configuration files

Framework Detection:

  • Next.js: Has next.config.js or app/ directory
  • Create React App: Has react-scripts in package.json
  • Vite: Has vite.config.ts
  • Vue: Has App.vue or vue.config.js
  • Svelte: Has svelte.config.js

Production Readiness Checklist​

Root Directory (25 points)​

  • 5 pts: Only essential files in root (max 25 items)
  • 5 pts: All documentation files present (README, CLAUDE, CONTRIBUTING, CHANGELOG, LICENSE, SECURITY)
  • 5 pts: All configuration files present (.eslintrc, .prettierrc, .editorconfig, .env.example)
  • 5 pts: Clean package.json with organized scripts
  • 5 pts: Comprehensive .gitignore

Source Organization (25 points)​

  • 5 pts: Clear src/ structure with components/ and features/
  • 5 pts: Shared components separate from feature components
  • 5 pts: Proper colocation (tests, styles with components)
  • 5 pts: Shallow nesting (max 3-4 levels)
  • 5 pts: Clear separation of concerns

Documentation (25 points)​

  • 5 pts: docs/ directory with proper hierarchy
  • 5 pts: Architecture documentation (ADRs, diagrams)
  • 5 pts: API documentation (if applicable)
  • 5 pts: Testing documentation
  • 5 pts: User guides and tutorials

Infrastructure (25 points)​

  • 5 pts: scripts/ directory with production scripts
  • 5 pts: tests/ directory with proper organization
  • 5 pts: examples/ directory with usage examples
  • 5 pts: public/ directory for static assets
  • 5 pts: Build configuration optimized for production

Total Score: 100 points Production Ready: 90+ points Needs Improvement: 70-89 points Not Ready: <70 points

Common Anti-Patterns to Avoid​

❌ Don't Do This​

❌ Flat structure (all files in src/)
❌ Deep nesting (src/features/auth/components/forms/login/inputs/email/)
❌ Mixed concerns (components and services in same file)
❌ Test files in separate directory for component tests
❌ Global styles mixed with component styles
❌ Hardcoded API URLs in components
❌ No separation between shared and feature components

✅ Do This Instead​

✅ Feature-based organization (src/features/auth/)
✅ Shallow nesting (max 3-4 levels)
✅ Clear separation (components, services, hooks separate)
✅ Co-located tests for components
✅ CSS modules or styled-components for component styles
✅ Environment variables for configuration
✅ Clear distinction between shared UI and business features

Framework-Specific Variations​

Next.js App Router​

  • Use app/ directory for routes
  • Use src/ for shared code (optional)
  • Route groups with (name)/
  • Private folders with _name/

Create React App​

  • Standard src/ structure
  • Router configuration in src/routes/
  • No file-based routing

Vite​

  • Similar to CRA
  • index.html in root
  • Faster build times

Vue 3​

  • Use views/ for pages
  • Use composables/ for reusable logic
  • Pinia for state management

Migration Guide​

If your project doesn't match this standard:

  1. Create target structure - Create missing directories
  2. Categorize files - Identify where each file belongs
  3. Move systematically - Use git mv to preserve history
  4. Update imports - Fix all import paths
  5. Test thoroughly - Verify nothing breaks
  6. Commit atomically - One category per commit

Use: /organize-production command for automated migration

References​

Status: Production Standard ✅ Version: 1.0.0 Last Updated: 2025-12-04 Applies To: React, Vue, Svelte, Next.js, Angular projects