1---
2name: directory-structure
3description: Nuxt project folder structure, conventions, and file organization
4---
5 
6# Directory Structure
7 
8Nuxt uses conventions-based directory structure. Understanding it is key to effective development.
9 
10## Standard Project Structure
11 
12```
13my-nuxt-app/
14├── app/                    # Application source (can be at root level)
15│   ├── app.vue             # Root component
16│   ├── app.config.ts       # App configuration (runtime)
17│   ├── error.vue           # Error page
18│   ├── components/         # Auto-imported Vue components
19│   ├── composables/        # Auto-imported composables
20│   ├── layouts/            # Layout components
21│   ├── middleware/         # Route middleware
22│   ├── pages/              # File-based routing
23│   ├── plugins/            # Vue plugins
24│   └── utils/              # Auto-imported utilities
25├── assets/                 # Build-processed assets (CSS, images)
26├── public/                 # Static assets (served as-is)
27├── server/                 # Server-side code
28│   ├── api/                # API routes (/api/*)
29│   ├── routes/             # Server routes
30│   ├── middleware/         # Server middleware
31│   ├── plugins/            # Nitro plugins
32│   └── utils/              # Server utilities (auto-imported)
33├── content/                # Content files (@nuxt/content)
34├── layers/                 # Local layers (auto-scanned)
35├── modules/                # Local modules
36├── nuxt.config.ts          # Nuxt configuration
37├── package.json
38└── tsconfig.json
39```
40 
41## Key Directories
42 
43### `app/` Directory
44 
45Contains all application code. Can also be at root level (without `app/` folder).
46 
47```ts
48// nuxt.config.ts - customize source directory
49export default defineNuxtConfig({
50  srcDir: 'src/', // Change from 'app/' to 'src/'
51})
52```
53 
54### `app/components/`
55 
56Vue components auto-imported by name:
57 
58```
59components/
60├── Button.vue           → <Button />
61├── Card.vue             → <Card />
62├── base/
63│   └── Button.vue       → <BaseButton />
64├── ui/
65│   ├── Input.vue        → <UiInput />
66│   └── Modal.vue        → <UiModal />
67└── TheHeader.vue        → <TheHeader />
68```
69 
70**Lazy loading**: Prefix with `Lazy` for dynamic import:
71 
72```vue
73<template>
74  <LazyHeavyChart v-if="showChart" />
75</template>
76```
77 
78**Client/Server only**:
79 
80```
81components/
82├── Comments.client.vue  → Only rendered on client
83└── ServerData.server.vue → Only rendered on server
84```
85 
86### `app/composables/`
87 
88Vue composables auto-imported (top-level files only):
89 
90```
91composables/
92├── useAuth.ts           → useAuth()
93├── useFoo.ts            → useFoo()
94└── nested/
95    └── utils.ts         → NOT auto-imported
96```
97 
98Re-export nested composables:
99 
100```ts
101// composables/index.ts
102export { useHelper } from './nested/utils'
103```
104 
105### `app/pages/`
106 
107File-based routing:
108 
109```
110pages/
111├── index.vue            → /
112├── about.vue            → /about
113├── blog/
114│   ├── index.vue        → /blog
115│   └── [slug].vue       → /blog/:slug
116├── users/
117│   └── [id]/
118│       └── profile.vue  → /users/:id/profile
119├── [...slug].vue        → /* (catch-all)
120├── [[optional]].vue     → /:optional? (optional param)
121└── (marketing)/         → Route group (not in URL)
122    └── pricing.vue      → /pricing
123```
124 
125**Pages are optional**: Without `pages/`, no vue-router is included.
126 
127### `app/layouts/`
128 
129Layout components wrapping pages:
130 
131```
132layouts/
133├── default.vue          → Default layout
134├── admin.vue            → Admin layout
135└── blank.vue            → No layout
136```
137 
138```vue
139<!-- layouts/default.vue -->
140<template>
141  <div>
142    <TheHeader />
143    <slot />
144    <TheFooter />
145  </div>
146</template>
147```
148 
149Use in pages:
150 
151```vue
152<script setup>
153definePageMeta({
154  layout: 'admin',
155  // layout: false // Disable layout
156})
157</script>
158```
159 
160### `app/middleware/`
161 
162Route middleware:
163 
164```
165middleware/
166├── auth.ts              → Named middleware
167├── admin.ts             → Named middleware
168└── logger.global.ts     → Global middleware (runs on every route)
169```
170 
171### `app/plugins/`
172 
173Nuxt plugins (auto-registered):
174 
175```
176plugins/
177├── 01.analytics.ts      → Order with number prefix
178├── 02.auth.ts
179├── vue-query.client.ts  → Client-only plugin
180└── server-init.server.ts → Server-only plugin
181```
182 
183### `server/` Directory
184 
185Nitro server code:
186 
187```
188server/
189├── api/
190│   ├── users.ts         → GET /api/users
191│   ├── users.post.ts    → POST /api/users
192│   └── users/[id].ts    → /api/users/:id
193├── routes/
194│   └── sitemap.xml.ts   → /sitemap.xml
195├── middleware/
196│   └── auth.ts          → Runs on every request
197├── plugins/
198│   └── db.ts            → Server startup plugins
199└── utils/
200    └── db.ts            → Auto-imported server utilities
201```
202 
203### `public/` Directory
204 
205Static assets served at root URL:
206 
207```
208public/
209├── favicon.ico          → /favicon.ico
210├── robots.txt           → /robots.txt
211└── images/
212    └── logo.png         → /images/logo.png
213```
214 
215### `assets/` Directory
216 
217Build-processed assets:
218 
219```
220assets/
221├── css/
222│   └── main.css
223├── images/
224│   └── hero.png
225└── fonts/
226    └── custom.woff2
227```
228 
229Reference in components:
230 
231```vue
232<template>
233  <img src="~/assets/images/hero.png" />
234</template>
235 
236<style>
237@import '~/assets/css/main.css';
238</style>
239```
240 
241## Special Files
242 
243| File | Purpose |
244|------|---------|
245| `app.vue` | Root component (optional with pages/) |
246| `app.config.ts` | Runtime app configuration |
247| `error.vue` | Custom error page |
248| `nuxt.config.ts` | Build-time configuration |
249| `.nuxtignore` | Ignore files from Nuxt |
250| `.env` | Environment variables |
251 
252## File Naming Conventions
253 
254| Pattern | Meaning |
255|---------|---------|
256| `[param]` | Dynamic route parameter |
257| `[[param]]` | Optional parameter |
258| `[...slug]` | Catch-all route |
259| `(group)` | Route group (not in URL) |
260| `.client.vue` | Client-only component |
261| `.server.vue` | Server-only component |
262| `.global.ts` | Global middleware |
263 
264<!-- 
265Source references:
266- https://nuxt.com/docs/directory-structure
267- https://nuxt.com/docs/directory-structure/app
268- https://nuxt.com/docs/directory-structure/server
269-->
270