---
name: directory-structure
description: Nuxt project folder structure, conventions, and file organization
---

# Directory Structure

Nuxt uses conventions-based directory structure. Understanding it is key to effective development.

## Standard Project Structure (Nuxt 4)

In Nuxt 4, the **`app/` directory is the default source directory** (`srcDir` defaults to `app/`).

```
my-nuxt-app/
├── app/                    # Application source (default srcDir in Nuxt 4)
│   ├── app.vue             # Root component
│   ├── app.config.ts       # App configuration (runtime)
│   ├── error.vue           # Error page
│   ├── router.options.ts   # Vue Router options (Nuxt 4)
│   ├── components/         # Auto-imported Vue components
│   ├── composables/        # Auto-imported composables
│   ├── layouts/            # Layout components
│   ├── middleware/         # Route middleware
│   ├── pages/              # File-based routing
│   ├── plugins/            # Vue plugins
│   └── utils/              # Auto-imported utilities
├── assets/                 # Build-processed assets (CSS, images) — stays at root
├── public/                 # Static assets (served as-is) — stays at root
├── server/                 # Server-side code — stays at root
│   ├── api/                # API routes (/api/*)
│   ├── routes/             # Server routes
│   ├── middleware/         # Server middleware
│   ├── plugins/            # Nitro plugins
│   └── utils/              # Server utilities (auto-imported)
├── shared/                 # Shared code between app and server (Nuxt 4)
│   ├── utils/              # Auto-imported in both app and server
│   └── types/              # Shared TypeScript types
├── content/                # Content files (@nuxt/content)
├── layers/                 # Local layers (auto-scanned)
├── modules/                # Local modules
├── nuxt.config.ts          # Nuxt configuration
├── package.json
└── tsconfig.json
```

## Key Directories

### `app/` Directory

In Nuxt 4, this is the default source directory (`srcDir: 'app/'`). All application code goes here.

```ts
// nuxt.config.ts - override source directory
export default defineNuxtConfig({
  srcDir: 'src/', // Change from default 'app/' to 'src/'
})
```

### `shared/` Directory (New in Nuxt 4)

Code shared between the Vue app and the Nitro server:

```
shared/
├── utils/
│   └── format.ts     → auto-imported in both app/ and server/
└── types/
    └── user.ts       → shared TypeScript interfaces
```

### `app/components/`

Vue components auto-imported by name:

```
components/
├── Button.vue           → <Button />
├── Card.vue             → <Card />
├── base/
│   └── Button.vue       → <BaseButton />
├── ui/
│   ├── Input.vue        → <UiInput />
│   └── Modal.vue        → <UiModal />
└── TheHeader.vue        → <TheHeader />
```

**Lazy loading**: Prefix with `Lazy` for dynamic import:

```vue
<template>
  <LazyHeavyChart v-if="showChart" />
</template>
```

**Client/Server only**:

```
components/
├── Comments.client.vue  → Only rendered on client
└── ServerData.server.vue → Only rendered on server
```

### `app/composables/`

Vue composables auto-imported (top-level files only):

```
composables/
├── useAuth.ts           → useAuth()
├── useFoo.ts            → useFoo()
└── nested/
    └── utils.ts         → NOT auto-imported
```

Re-export nested composables:

```ts
// composables/index.ts
export { useHelper } from './nested/utils'
```

### `app/pages/`

File-based routing:

```
pages/
├── index.vue            → /
├── about.vue            → /about
├── blog/
│   ├── index.vue        → /blog
│   └── [slug].vue       → /blog/:slug
├── users/
│   └── [id]/
│       └── profile.vue  → /users/:id/profile
├── [...slug].vue        → /* (catch-all)
├── [[optional]].vue     → /:optional? (optional param)
└── (marketing)/         → Route group (not in URL)
    └── pricing.vue      → /pricing
```

**Pages are optional**: Without `pages/`, no vue-router is included.

### `app/layouts/`

Layout components wrapping pages:

```
layouts/
├── default.vue          → Default layout
├── admin.vue            → Admin layout
└── blank.vue            → No layout
```

```vue
<!-- layouts/default.vue -->
<template>
  <div>
    <TheHeader />
    <slot />
    <TheFooter />
  </div>
</template>
```

Use in pages:

```vue
<script setup>
definePageMeta({
  layout: 'admin',
  // layout: false // Disable layout
})
</script>
```

### `app/middleware/`

Route middleware:

```
middleware/
├── auth.ts              → Named middleware
├── admin.ts             → Named middleware
└── logger.global.ts     → Global middleware (runs on every route)
```

### `app/plugins/`

Nuxt plugins (auto-registered):

```
plugins/
├── 01.analytics.ts      → Order with number prefix
├── 02.auth.ts
├── vue-query.client.ts  → Client-only plugin
└── server-init.server.ts → Server-only plugin
```

### `server/` Directory

Nitro server code:

```
server/
├── api/
│   ├── users.ts         → GET /api/users
│   ├── users.post.ts    → POST /api/users
│   └── users/[id].ts    → /api/users/:id
├── routes/
│   └── sitemap.xml.ts   → /sitemap.xml
├── middleware/
│   └── auth.ts          → Runs on every request
├── plugins/
│   └── db.ts            → Server startup plugins
└── utils/
    └── db.ts            → Auto-imported server utilities
```

### `public/` Directory

Static assets served at root URL:

```
public/
├── favicon.ico          → /favicon.ico
├── robots.txt           → /robots.txt
└── images/
    └── logo.png         → /images/logo.png
```

### `assets/` Directory

Build-processed assets:

```
assets/
├── css/
│   └── main.css
├── images/
│   └── hero.png
└── fonts/
    └── custom.woff2
```

Reference in components:

```vue
<template>
  <img src="~/assets/images/hero.png" />
</template>

<style>
@import '~/assets/css/main.css';
</style>
```

## Special Files

| File | Purpose |
|------|---------|
| `app/app.vue` | Root component (optional with pages/) |
| `app/app.config.ts` | Runtime app configuration |
| `app/error.vue` | Custom error page |
| `app/router.options.ts` | Vue Router configuration (Nuxt 4) |
| `app/spa-loading-template.html` | SPA loading UI |
| `nuxt.config.ts` | Build-time configuration |
| `.nuxtignore` | Ignore files from Nuxt |
| `.env` | Environment variables |

## File Naming Conventions

| Pattern | Meaning |
|---------|---------|
| `[param]` | Dynamic route parameter |
| `[[param]]` | Optional parameter |
| `[...slug]` | Catch-all route |
| `(group)` | Route group (not in URL) |
| `.client.vue` | Client-only component |
| `.server.vue` | Server-only component |
| `.global.ts` | Global middleware |

<!-- 
Source references:
- https://nuxt.com/docs/directory-structure
- https://nuxt.com/docs/directory-structure/app
- https://nuxt.com/docs/directory-structure/server
-->