Folder Structure

Understanding the frontend project organization.

Project Structure

apps/frontend/
  app/
    ├── components/        # Reusable components (auto-imported)
    ├── composables/       # Composables (auto-imported)
    ├── layouts/           # Layout wrappers
    ├── middleware/        # Route middleware
    ├── pages/             # File-based routes
    ├── plugins/           # App plugins
    ├── types/             # TypeScript types
    ├── utils/             # Utility functions (auto-imported)
    └── app.vue            # Root component
  i18n/locales/            # Translation files
  public/                  # Static assets

Auto-Imports

These folders are automatically imported - no import statements needed:

• ✅ components/ - All components
• ✅ composables/ - All composables
• ✅ utils/ - All utilities

<script setup>
// ✅ No imports needed - auto-imported
const { data } = useApi('/api/endpoint')
const result = someUtilFunction()
</script>

<template>
  <!-- ✅ No import needed -->
  <UiButton>Click me</UiButton>
</template>

Components Organization

Global Components (components/)

Reusable components available throughout the app:

components/
  ├── ui/                  # shadcn-vue UI components
  │   ├── button/
  │   ├── input/
  │   └── dialog/
  ├── app-shell/           # App layout components
  ├── chevron/             # RTL-aware chevrons
  └── route-dialog/        # Route dialog utilities

Page-Specific Components (_components/)

Components specific to a page or feature:

pages/
  employees/
    index.vue              # Parent page
    _components/           # Components for employees pages
      EmployeeTable.vue
      EmployeeRow.vue
      EmployeeFilters.vue

Component Names Must Be UNIQUE

Important: _components folders are auto-imported but NOT scoped!

pages/
  employees/
    _components/
      EmployeeTable.vue    # ❌ Conflict!
  
  departments/
    _components/
      EmployeeTable.vue    # ❌ Same name - will conflict!

Solution: Use unique names:

employees/_components/EmployeeTable.vue     # ✅ Unique
departments/_components/DepartmentTable.vue  # ✅ Unique

Optional Explicit Imports

For local components, you can optionally use explicit imports for clarity:

<script setup>
// ✅ Optional - makes it clear where component comes from
import EmployeeTable from './_components/EmployeeTable.vue'

// ✅ Also valid - auto-import (works because of unique names)
// No import needed
</script>

<template>
  <EmployeeTable />
</template>

When to Use Explicit Imports

Use explicit imports when:

• You want to make the component source obvious
• Working with unfamiliar code
• Prefer explicit over implicit

Types Organization

Global Types (types/)

Shared types available throughout the app:

types/
  ├── api-types.ts         # Auto-generated from OpenAPI
  ├── api-type-utils.ts    # API type helpers
  ├── employee.ts          # Employee types
  └── index.d.ts           # Global declarations

Local Types Files

For page or feature-specific types, create a local types.ts:

pages/
  employees/
    [id]/
      profile/
        index.vue
        _components/
          ProfileCard.vue
        types.ts           # Local types for profile page

When to use local types:

• Types only used in this page/feature
• Not needed elsewhere in the app
• Keep types close to usage

// pages/employees/[id]/profile/types.ts
export interface ProfileFormData {
  firstName: string
  lastName: string
  email: string
}

export type ProfileSection = 'personal' | 'contact' | 'employment'

Composables (composables/)

Auto-imported composables:

composables/
  ├── useApi.ts            # API calls
  ├── useConfirm.ts        # Confirmation dialogs
  ├── useRtl.ts            # RTL support
  ├── useEdit.ts           # Edit mode management
  └── state/               # State management
      ├── auth.ts
      └── organizationData.ts

Usage:

<script setup>
// ✅ No import needed
const { data } = useApi('/api/endpoint')
const { confirm } = useConfirm()
</script>

Utils (utils/)

Auto-imported utility functions:

utils/
  ├── apiTypes.ts          # API type shortcuts
  ├── errorHandling.ts     # Error utilities
  ├── fireAndForget.ts     # Async helpers
  ├── i18n-keys.ts         # r() function
  └── validation.ts        # Validation helpers

Usage:

<script setup>
// ✅ No import needed
fireAndForget(saveData, 'Failed to save')

if (isApiError(error)) {
  // Handle error
}
</script>

Layouts (layouts/)

Layout wrappers for different page types:

layouts/
  ├── default.vue          # Default layout
  ├── auth.vue             # Auth pages layout
  └── hr.vue               # HR app layout

Usage in pages:

<script setup>
definePageMeta({
  layout: 'hr'
})
</script>

Middleware (middleware/)

Route middleware for navigation guards:

middleware/
  ├── 01-initUser.global.ts    # Global middleware (runs on every route)
  └── auth-step.ts              # Named middleware

Plugins (plugins/)

App-wide plugins:

plugins/
  ├── api.ts               # API setup ($api, $apiFetch)
  ├── focus.ts             # Focus management
  └── maska.ts             # Input masking

Internationalization (i18n/locales/)

Translation files organized by language:

i18n/locales/
  ├── en/
  │   ├── common.json
  │   ├── employees.json
  │   └── index.ts
  ├── es/
  │   └── [same structure]
  └── he/
      └── [same structure]

See Internationalization → for details.

Best Practices

Do's ✅

• Use _components for page-specific components
• Give components unique names across the app
• Use local types.ts for page-specific types
• Optionally use explicit imports for clarity
• Keep related files close together

Don'ts ❌

• Don't duplicate component names in different _components folders
• Don't create global types for page-specific data
• Don't import composables/utils (they're auto-imported)
• Don't put shared components in _components

Quick Reference

Need	Location	Import?
Reusable component	components/	❌ Auto
Page-specific component	pages/.../\_components/	❌ Auto (optional explicit)
Composable	composables/	❌ Auto
Utility function	utils/	❌ Auto
Shared type	types/	✅ Manual
Page-specific type	Local types.ts	✅ Manual
Layout	layouts/	❌ Via definePageMeta
Route	pages/	❌ File-based

---

Related: Routing & Navigation → | UI Components → | Composables →