1---
2name: nuxt-modules
3description: Creating and using Nuxt modules to extend framework functionality
4---
5 
6# Nuxt Modules
7 
8Modules extend Nuxt's core functionality. They run at build time and can add components, composables, plugins, and configuration.
9 
10## Using Modules
11 
12Install and add to `nuxt.config.ts`:
13 
14```ts
15// nuxt.config.ts
16export default defineNuxtConfig({
17  modules: [
18    // npm package
19    '@nuxt/ui',
20    // Local module
21    './modules/my-module',
22    // Inline module
23    (options, nuxt) => {
24      console.log('Inline module')
25    },
26    // With options
27    ['@nuxt/image', { provider: 'cloudinary' }],
28  ],
29})
30```
31 
32## Creating Modules
33 
34### Basic Module
35 
36```ts
37// modules/my-module.ts
38export default defineNuxtModule({
39  meta: {
40    name: 'my-module',
41    configKey: 'myModule',
42  },
43  defaults: {
44    enabled: true,
45  },
46  setup(options, nuxt) {
47    if (!options.enabled) return
48 
49    console.log('My module is running!')
50  },
51})
52```
53 
54### Adding Components
55 
56```ts
57// modules/ui/index.ts
58import { addComponent, createResolver } from '@nuxt/kit'
59 
60export default defineNuxtModule({
61  setup(options, nuxt) {
62    const { resolve } = createResolver(import.meta.url)
63 
64    // Add single component
65    addComponent({
66      name: 'MyButton',
67      filePath: resolve('./runtime/components/MyButton.vue'),
68    })
69 
70    // Add components directory
71    addComponentsDir({
72      path: resolve('./runtime/components'),
73      prefix: 'My',
74    })
75  },
76})
77```
78 
79### Adding Composables
80 
81```ts
82// modules/utils/index.ts
83import { addImports, createResolver } from '@nuxt/kit'
84 
85export default defineNuxtModule({
86  setup() {
87    const { resolve } = createResolver(import.meta.url)
88 
89    // Add auto-imported composable
90    addImports({
91      name: 'useMyUtil',
92      from: resolve('./runtime/composables/useMyUtil'),
93    })
94 
95    // Add directory for auto-imports
96    addImportsDir(resolve('./runtime/composables'))
97  },
98})
99```
100 
101### Adding Plugins
102 
103```ts
104// modules/analytics/index.ts
105import { addPlugin, createResolver } from '@nuxt/kit'
106 
107export default defineNuxtModule({
108  setup() {
109    const { resolve } = createResolver(import.meta.url)
110 
111    addPlugin({
112      src: resolve('./runtime/plugin'),
113      mode: 'client', // 'client', 'server', or 'all'
114    })
115  },
116})
117```
118 
119Plugin file:
120 
121```ts
122// modules/analytics/runtime/plugin.ts
123export default defineNuxtPlugin((nuxtApp) => {
124  nuxtApp.hook('page:finish', () => {
125    console.log('Page loaded')
126  })
127})
128```
129 
130### Adding Server Routes
131 
132```ts
133// modules/api/index.ts
134import { addServerHandler, createResolver } from '@nuxt/kit'
135 
136export default defineNuxtModule({
137  setup() {
138    const { resolve } = createResolver(import.meta.url)
139 
140    addServerHandler({
141      route: '/api/my-endpoint',
142      handler: resolve('./runtime/server/api/my-endpoint'),
143    })
144  },
145})
146```
147 
148### Extending Config
149 
150```ts
151// modules/config/index.ts
152export default defineNuxtModule({
153  setup(options, nuxt) {
154    // Add CSS
155    nuxt.options.css.push('my-module/styles.css')
156 
157    // Add runtime config
158    nuxt.options.runtimeConfig.public.myModule = {
159      apiUrl: options.apiUrl,
160    }
161 
162    // Extend Vite config
163    nuxt.options.vite.optimizeDeps ||= {}
164    nuxt.options.vite.optimizeDeps.include ||= []
165    nuxt.options.vite.optimizeDeps.include.push('some-package')
166  },
167})
168```
169 
170## Module Hooks
171 
172```ts
173export default defineNuxtModule({
174  setup(options, nuxt) {
175    // Build-time hooks
176    nuxt.hook('modules:done', () => {
177      console.log('All modules loaded')
178    })
179 
180    nuxt.hook('components:dirs', (dirs) => {
181      dirs.push({ path: '~/extra-components' })
182    })
183 
184    nuxt.hook('pages:extend', (pages) => {
185      pages.push({
186        name: 'custom-page',
187        path: '/custom',
188        file: resolve('./runtime/pages/custom.vue'),
189      })
190    })
191 
192    nuxt.hook('imports:extend', (imports) => {
193      imports.push({ name: 'myHelper', from: 'my-package' })
194    })
195  },
196})
197```
198 
199## Module Options
200 
201Type-safe options with defaults:
202 
203```ts
204export interface ModuleOptions {
205  apiKey: string
206  enabled?: boolean
207  prefix?: string
208}
209 
210export default defineNuxtModule<ModuleOptions>({
211  meta: {
212    name: 'my-module',
213    configKey: 'myModule',
214  },
215  defaults: {
216    enabled: true,
217    prefix: 'My',
218  },
219  setup(options, nuxt) {
220    // options is typed as ModuleOptions
221    if (!options.apiKey) {
222      console.warn('API key not provided')
223    }
224  },
225})
226```
227 
228Usage:
229 
230```ts
231// nuxt.config.ts
232export default defineNuxtConfig({
233  modules: ['my-module'],
234  myModule: {
235    apiKey: 'xxx',
236    prefix: 'Custom',
237  },
238})
239```
240 
241## Local Modules
242 
243Place in `modules/` directory:
244 
245```
246modules/
247├── my-module/
248│   ├── index.ts
249│   └── runtime/
250│       ├── components/
251│       ├── composables/
252│       └── plugin.ts
253```
254 
255Auto-registered or manually added:
256 
257```ts
258// nuxt.config.ts
259export default defineNuxtConfig({
260  modules: [
261    '~/modules/my-module', // Explicit
262  ],
263})
264```
265 
266## Module Dependencies
267 
268```ts
269export default defineNuxtModule({
270  meta: {
271    name: 'my-module',
272  },
273  moduleDependencies: {
274    '@nuxt/image': {
275      version: '>=1.0.0',
276      defaults: {
277        provider: 'ipx',
278      },
279    },
280  },
281  setup() {
282    // @nuxt/image is guaranteed to be installed
283  },
284})
285```
286 
287<!-- 
288Source references:
289- https://nuxt.com/docs/guide/modules
290- https://nuxt.com/docs/guide/modules/module-anatomy
291- https://nuxt.com/docs/api/kit
292-->
293