NuxtLink component for navigation
The <NuxtLink> component is included with Nuxt and requires no import. It is used to navigate between pages. Example: <NuxtLink to="/">Home page</NuxtLink>.
directory-structure
251 notes in this subject, read out of this brain and free to use. This is page 2 of 5.
definePageMeta macro for page metadata
definePageMeta() is a compiler macro that defines metadata for a page route. It works in both <script> and <script setup>. The metadata is hoisted out of the component and cannot reference reactive data or side-effect functions. It can reference imported bindings and pure functions.
pageKey prop for NuxtPage re-rendering control
The pageKey prop on <NuxtPage> can be passed a string or function to control when the component is re-rendered. For example, :page-key="route => route.fullPath" causes re-render on every path change.
definePageMeta path property
The path property in definePageMeta allows defining a custom path matcher for complex patterns that cannot be expressed with the filename. See vue-router docs for custom regex patterns.
definePageMeta name property
The name property in definePageMeta defines a name for the page's route.
definePageMeta middleware property
The middleware property in definePageMeta defines middleware to apply before loading the page. It can be a string, function (anonymous/inlined following the global before guard pattern), or array of strings/functions. Middleware is merged with parent/child route middleware.
definePageMeta layoutTransition and pageTransition
definePageMeta can include layoutTransition and pageTransition properties that define transition properties for the <transition> component wrapping pages and layouts. Pass false to disable the transition wrapper for that route.
definePageMeta layout property
The layout property in definePageMeta defines which layout renders the route. It can be false to disable layout, a string for a named layout, or a ref/computed to make it reactive.
definePageMeta keepalive property
Setting keepalive: true in definePageMeta wraps the page in Vue's <KeepAlive> component to preserve page state across route changes. Alternatively, use <NuxtPage keepalive /> on the parent. Props can be passed to <KeepAlive> and defaults can be set in nuxt.config.
definePageMeta props property
The props property in definePageMeta allows accessing route params as props passed to the page component, as documented in vue-router.
definePageMeta alias property
The alias property in definePageMeta allows defining page aliases as a string or array of strings, enabling access to the same page from different paths as documented in vue-router.
Utils scope limitation
Utilities from app/utils/ are only available within the Vue part of the application. Only server/utils are auto-imported in the server/ directory.
Utils named export syntax
Utility functions can be exported using named exports. Example: export const { format: formatNumber } = Intl.NumberFormat('en-GB', { notation: 'compact', maximumFractionDigits: 1 }). Named exports preserve their export name when auto-imported.
Types auto-import directory structure
Types can be auto-imported the same way as utilities. App-only types should be placed in app/types/, server-only types in server/types/, and types shared between app and server in shared/types/.
Utils scanning identical to composables
The way app/utils/ auto-imports work and are scanned is identical to the app/composables/ directory.
Utils auto-import availability
Auto-imported utility functions from app/utils/ are available in .js, .ts, and .vue files.
Utils default export syntax
Utility functions can be exported as default exports. When using default export, the function becomes available as camelCase version of the file name without extension. Example: a file utils/random-entry.ts or utils/randomEntry.ts with default export is available as randomEntry().
utils directory auto-import purpose
The app/utils/ directory allows semantic distinction between Vue composables and other auto-imported utility functions. Utility functions in this directory are automatically imported throughout the application.
Without app/pages/, Nuxt does not include vue-router
If the app/pages/ directory is not present, Nuxt will not include the vue-router dependency. This is useful when building a landing page or an application that does not require routing.
Minimal app.vue example without routing
When building a landing page without routing, app.vue can contain only template content without the <NuxtPage /> component.
app.vue can include global elements like header and footer
You can define the common structure of your application directly in app.vue. This is useful when you want to include global elements such as a header or footer that appear on every page.
Use NuxtPage component to display the current page
When you have an app/pages/ directory, you need to use the <NuxtPage /> component in app.vue to display the current page.
app.vue is optional if app/pages/ directory exists
If you have an app/pages/ directory, the app.vue file is optional. Nuxt will automatically include a default app.vue, but you can still add your own to customize the structure and content as needed.
app.vue is the main component of your Nuxt application
The app.vue file is the main component of your Nuxt application. Anything you add to it (JS and CSS) will be global and included in every page.
useAppConfig composable
The useAppConfig composable is used to universally access app config both when server-rendering the page and in the browser.
app.config merging strategy with layers
Nuxt uses a custom merging strategy for AppConfig within the layers of your application. The strategy is implemented using a Function Merger, which allows defining a custom merging strategy for every key in app.config that has an array as value. The function merger can only be used in extended layers and not the main app.config in project. Example: in layer/app/app.config.ts: export default defineAppConfig({ array: ['hello'] }); in app/app.config.ts: export default defineAppConfig({ array: () => ['bonjour'] });
app.config typing availability by context
Nuxt automatically generates a TypeScript interface from provided app config. The fully inferred type is only available in app code (components, composables, plugins). In server routes, shared/ directory code, and nuxt.config, keys are typed as unknown instead. Keys defined inline in the appConfig option of nuxt.config are typed everywhere. A .d.ts file in the shared/ directory covers app code, shared code, and server routes.
AppConfig interface for typing useAppConfig output
To type the result of calling useAppConfig(), extend the AppConfig interface. Warning: typing AppConfig will overwrite the types Nuxt infers from your actually defined app config. Example: declare module 'nuxt/schema' { interface AppConfig { theme: { primaryColor?: 'red' | 'blue' } } } export {}
AppConfigInput interface for module authors
AppConfigInput is used by module authors to declare what valid input options are when setting app config. It does not affect the type of useAppConfig(). Example: declare module 'nuxt/schema' { interface AppConfigInput { theme?: { primaryColor?: string } } } export {}
updateAppConfig utility
The updateAppConfig utility can be used to update the app.config at runtime. Example: const appConfig = useAppConfig(); const newAppConfig = { foo: 'baz' }; updateAppConfig(newAppConfig); console.log(appConfig); // { foo: 'baz' }
app.config location with custom srcDir
When configuring a custom srcDir, make sure to place the app.config file at the root of the new srcDir path.
app.config security: no secret values
Do not put any secret values inside app.config file because it is exposed to the user client bundle.
app.config.ts basic syntax
The app.config.ts file uses the defineAppConfig function to define configuration. Example: export default defineAppConfig({ foo: 'bar' })
app.config.ts file location and purpose
The app.config.ts file is located at app/app.config.ts and exposes reactive configuration within your application with the ability to update it at runtime within lifecycle or using a nuxt plugin. It supports HMR (hot-module-replacement). The file can have .ts, .js, or .mjs extensions.
app.config.ts limitations with Nitro
As of Nuxt v3.3, app.config.ts is shared with Nitro, resulting in these limitations: 1) You cannot import Vue components directly in app.config.ts. 2) Some auto-imports are not available in the Nitro context. Nitro v3 will resolve these limitations by removing support for app config.
error.vue component example
Example of a basic error.vue component: ```vue [error.vue] <script setup lang="ts"> import type { NuxtError } from '#app' const props = defineProps<{ error: NuxtError }>() </script> <template> <div> <h1>{{ error.status }}</h1> <NuxtLink to="/">Go back home</NuxtLink> </div> </template> ```
error.vue example with custom data
Example of throwing an error with custom data: ```ts throw createError({ status: 404, statusText: 'Page Not Found', data: { myCustomField: true, }, }) ```
error.vue with custom fields using createError
Custom fields should not be added directly to the error object as they will be lost. Instead, custom data should be assigned to the 'data' field of the error object created with createError().
NuxtError interface fields
The NuxtError interface has the following fields: status (number, required), fatal (boolean, required), unhandled (boolean, required), statusText (string, optional), data (unknown, optional), and cause (unknown, optional).
error.vue can use layouts
Although error.vue is not a route, you can still use layouts in the error file by utilizing the NuxtLayout component and specifying the name of the layout.
error.vue props
The error.vue component receives a single prop named 'error' of type NuxtError, which contains the error information to handle.
error.vue file purpose and placement
The error.vue file is used to override the default error page and display errors nicely during runtime in a Nuxt application. It should not be placed in the ~/pages directory and should not use definePageMeta, as it is not a route.
Nuxt Content key features
Nuxt Content provides the following capabilities: render content with built-in components, query content with a MongoDB-like API, use Vue components in Markdown files with MDC syntax, and automatically generate navigation.
content/ directory purpose
The content/ directory is used to create a file-based CMS for your application. Nuxt Content reads this directory and parses .md, .yml, .csv and .json files.
Render content pages with ContentRenderer
To render content pages, use a catch-all route at app/pages/[...slug].vue with the ContentRenderer component. Query the content using queryCollection('content').path(route.path).first() and pass the result to the ContentRenderer :value prop.
Create content files
Place markdown files inside the content/ directory. For example, a file at content/index.md with content # Hello Content will be automatically loaded and parsed by the module.
Enable Nuxt Content module
To enable Nuxt Content, run the command: npx nuxt module add content. This installs the @nuxt/content module and adds it to nuxt.config.ts.
Layer directory structure
Each subdirectory within layers/ is treated as a separate layer and can contain the same structure as a standard Nuxt application, including: nuxt.config.ts, app/components/, app/composables/, app/utils/, app/pages/, app/layouts/, app/middleware/, app/plugins/, server/, and shared/.
Named layer aliases with #layers/ prefix
Named layer aliases to the srcDir of each layer are automatically created. You can access a layer using the #layers/[name] alias, such as import something from '#layers/base/path/to/file' or import { useAdmin } from '#layers/admin/composables/useAdmin'. This feature was introduced in Nuxt v3.16.0.
Layer priority order and alphabetical sorting
When multiple layers define the same resource (component, composable, page, etc.), the layer with higher priority wins. Layers are sorted alphabetically, with later letters having higher priority (Z has higher priority than A).
Control layer priority with extends in nuxt.config
You can reference directories in the extends option of nuxt.config.ts (e.g., extends: ['~~/layers/admin', '~~/layers/base']) to order layers without renaming them. The first entry in the extends array takes the highest priority.
Layer use cases
Layers are ideal for organizing large codebases with Domain-Driven Design (DDD), creating reusable UI libraries or themes, sharing configuration presets across projects, and separating concerns like admin panels or feature modules.
Layer must contain nuxt.config.ts
Every layer must have a nuxt.config.ts file to be recognized as a valid layer, even if the file is empty.
Layer content types
Each layer can include: nuxt.config.ts (layer-specific configuration merged with main config), app.config.ts (reactive application configuration), app/components/ (Vue components auto-imported), app/composables/ (Vue composables auto-imported), app/utils/ (utility functions auto-imported), app/pages/ (application pages), app/layouts/ (application layouts), app/middleware/ (route middleware), app/plugins/ (Nuxt plugins), server/ (server routes, middleware, and utilities), and shared/ (shared code between app and server).
layers/ directory auto-registration
The layers/ directory allows you to organize and share reusable code, components, composables, and configurations across your Nuxt application. Any subdirectories within layers/ are automatically registered as separate layers. This feature is available in Nuxt v3.12.0 and later.
Control layer priority with number prefixes
To control the order of layers without relying on alphabetical sorting, prefix directories with numbers such as 1.base/, 2.features/, 3.admin/.
node_modules directory purpose
The node_modules directory is created and maintained by package managers (npm, yarn, pnpm, bun, or deno) to store all project dependencies.
node_modules should be added to .gitignore
The node_modules directory should be added to the .gitignore file to prevent pushing dependencies to the repository.
Local module runtime structure
All components, pages, composables, and other files that would normally be placed in the app/ directory must be placed in modules/your-module/runtime/app/. This ensures they can be type-checked properly.
nuxt/kit helper subpath import
The nuxt/kit helper subpath import provides utilities like addComponentsDir, addServerHandler, createResolver, and defineNuxtModule for defining local modules. Using nuxt/kit means you do not need to add @nuxt/kit to your project's dependencies separately.