Virtual File System in .nuxt
Nuxt provides a Virtual File System (VFS) for modules to add templates to the .nuxt directory without writing them to disk.
directory-structure
251 notes in this subject, read out of this brain and free to use. This is page 1 of 5.
Exploring .nuxt generated files
Generated files in the .nuxt directory can be explored by opening the Nuxt DevTools in development mode and navigating to the Virtual Files tab.
.nuxt directory purpose
The .nuxt/ directory is generated by Nuxt during development to generate the Vue application. This directory should be added to .gitignore to avoid pushing dev build output to the repository.
.nuxt directory regeneration warning
Files inside the .nuxt directory should not be modified because the entire directory is re-created when running the nuxt dev command.
.output directory should be in .gitignore
The .output/ directory should be added to your .gitignore file to avoid pushing the build output to your repository.
.output directory is regenerated on build
You should not manually edit any files inside the .output/ directory since the whole directory will be re-created when running 'nuxt build'.
.output directory purpose
Nuxt creates the .output/ directory when building your application for production. This directory contains the build output and should be used to deploy your Nuxt application to production.
assets/ directory purpose and contents
The assets/ directory is used to add all the website's assets that the build tool will process. It usually contains stylesheets (CSS, SASS, etc.), fonts, and images that won't be served from the public/ directory.
When to use assets/ vs public/ directory
Use the assets/ directory for assets that need to be processed by the build tool, such as stylesheets, fonts, and images. Use the public/ directory to serve assets directly from the server.
Lazy hydration strategies overview
Nuxt supports lazy (delayed) hydration to control when components become interactive. Only one strategy can be used per lazy component. Any prop change on a lazily hydrated component triggers hydration immediately. Lazy hydration currently only works in single-file components (SFCs) with props defined in the template, not via v-bind spreading or direct imports from #components.
Direct imports from #components
Components can be explicitly imported from '#components' to bypass Nuxt's auto-importing functionality. Example: import { LazyMountainsList, NuxtLink } from '#components'.
hydrate-never strategy
The hydrate-never strategy prevents a component from ever being hydrated. Usage: <LazyMyComponent hydrate-never />. This should not be used on interactive components that require user interaction.
components directory auto-imports Vue components
Nuxt automatically imports any components in the components/ directory, along with components registered by any modules. Components are made available throughout the application without manual import statements.
hydrate-after strategy
The hydrate-after strategy hydrates a component after a specified delay in milliseconds. Usage: <LazyMyComponent :hydrate-after="2000" />.
Auto-importing components from npm packages
To auto-import components from an npm package, use the addComponent function from @nuxt/kit in a local Nuxt module. This allows registering components by name, export name, and file path from the npm package.
addComponentsDir example for library authors
Example in awesome-ui/nuxt.ts: import { addComponentsDir, createResolver, defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ setup () { const resolver = createResolver(import.meta.url) addComponentsDir({ path: resolver.resolve('./components'), prefix: 'awesome', }) }, }) Then in nuxt.config.ts: modules: ['awesome-ui/nuxt']. Components from awesome-ui/components/ are auto-imported with 'awesome-' prefix, e.g., <AwesomeButton /> and <awesome-alert />.
Pattern and ignore glob options for components
The components configuration accepts pattern and ignore glob options to control which files are scanned within a path. This is useful for non-standard component layouts like domain-driven structures. When pattern is specified, the extensions option has no effect, so the pattern must match the desired file extensions.
Global component registration
Set components.global: true in nuxt.config.ts to register all components globally. This creates async chunks for all components but makes them available throughout the application. Alternatively, place components in ~/components/global directory or use .global.vue suffix to selectively register components globally.
pathPrefix false option disables path-based naming
Set pathPrefix: false in the components configuration to auto-import components based on filename only, not their directory path. For example, ~/components/Some/MyComponent.vue becomes <MyComponent /> instead of <SomeMyComponent />. This matches Nuxt 2 naming strategy.
Lazy prefix for dynamic component imports
Add the Lazy prefix to a component name to lazy-load (dynamically import) it. For example, <LazyMountainsList /> delays loading the component code until needed, which helps optimize JavaScript bundle size. Lazy components are particularly useful for components that are not always needed.
Library authors: addComponentsDir for Nuxt modules
Vue component library authors can use the addComponentsDir method from @nuxt/kit to register a components directory in their Nuxt module. This enables automatic tree-shaking and component registration with HMR support.
Dynamic components with resolveComponent helper
To use Vue's <component :is="someComputedComponent"> syntax, use the resolveComponent helper provided by Vue or import components directly from '#components' and pass them to the is prop. With resolveComponent, only a literal string component name can be used; variables are not allowed as the string is statically analyzed at compilation.
hydrate-when strategy
The hydrate-when strategy hydrates a component based on a boolean condition. Usage: <LazyMyComponent :hydrate-when="isReady" /> where isReady is a reactive boolean that can be updated to trigger hydration.
Custom component directories configuration
By default, only ~/components is scanned. Additional directories can be configured in nuxt.config.ts using the components array. Each directory entry accepts: path (required), pathPrefix (boolean, optional), prefix (string, optional), pattern (glob pattern, optional), and ignore (glob pattern, optional). Nested directories must be added first as they are scanned in order.
addComponent example for npm package components
Example module registering a component from an npm package: import { addComponent, defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ setup () { addComponent({ name: 'MyAutoImportedComponent', export: 'MyComponent', filePath: 'my-npm-package', }) }, }) Then in app/app.vue, use <MyAutoImportedComponent /> which is automatically imported.
Grouping directories with parentheses
Use parentheses in directory names to group components without affecting their name. For example, components/base/(foo)/Button.vue results in <BaseButton />, skipping the grouping directory from the name.
Paired server and client components
Create .server and .client component pairs for advanced use cases with separate implementations on server and client side. For example, components/Comments.server.vue and components/Comments.client.vue. When used, the component renders Comments.server on the server, then Comments.client once mounted in the browser.
Server components with .server suffix
Add the .server suffix to a component filename to create a server-only component (Islands component) that always renders on the server. For example, components/HighlightedMarkdown.server.vue. When props update, a network request updates the rendered HTML in-place. Server-only components use <NuxtIsland> under the hood and must have a single root element (HTML comments count as elements).
Pattern glob option example
Example using pattern option in nuxt.config.ts: export default defineNuxtConfig({ components: [ { path: '~/domains', pattern: '*/components/**', pathPrefix: false, }, ], }) This configuration scans ~/domains/*/components/** and registers files without path prefix. For example, ~/domains/blog/components/PostCard.vue becomes <PostCard />.
Client components with .client suffix
Add the .client suffix to a component filename to render it only on the client side. For example, components/Comments.client.vue. This feature only works with Nuxt auto-imports and #components imports. Explicit imports from real file paths do not convert components to client-only. Client components are rendered only after being mounted; use await nextTick() in onMounted() to access the rendered template.
Component naming from nested directories
Component names are based on their path directory and filename, with duplicate segments removed. For example, components/base/foo/Button.vue becomes <BaseFooButton />. The component's filename should match its auto-generated name for clarity.
Custom component directories example configuration
Example nuxt.config.ts configuration with multiple component directories: export default defineNuxtConfig({ components: [ { path: '~/calendar-module/components' }, { path: '~/user-module/components', pathPrefix: false }, { path: '~/components/special-components', prefix: 'Special' }, '~/components', ], }) This registers: ~/calendar-module/components/event/Update.vue as <EventUpdate />, ~/user-module/components/account/UserDeleteDialog.vue as <UserDeleteDialog />, ~/components/special-components/Btn.vue as <SpecialBtn />, and ~/components/Btn.vue as <Btn /> with ~/components/base/Btn.vue as <BaseBtn />.
Component extensions configuration
By default, any file with an extension specified in the extensions key of nuxt.config.ts is treated as a component. To restrict file extensions registered as components, use the extended form: components: [{ path: '~/components', extensions: ['.vue'] }].
composables access to plugin injections
Composables can access plugin injections using useNuxtApp(). For example: export const useHello = () => { const nuxtApp = useNuxtApp(); return nuxtApp.$hello }
composables reactivity scope
The app/composables/ directory does not provide additional reactivity capabilities. Any reactivity is achieved using Vue's Composition API mechanisms like ref and reactive. Reactivity features are not limited to the composables directory and can be used wherever needed in the application.
composables nested directory configuration
To scan nested directories in composables/, configure the imports.dirs option in nuxt.config.ts. Examples: '~/composables' scans top-level, '~/composables/*/index.{ts,js,mjs,mts}' scans one level deep with specific name and extension, '~/composables/**' scans all nested directories.
composables nested directory re-export pattern
To enable auto-imports for nested composables, re-export them from app/composables/index.ts. For example: export { utils } from './nested/utils.ts'
composables type generation
Nuxt auto generates the file .nuxt/imports.d.ts to declare the types for auto-imported composables. You must run nuxt prepare, nuxt dev, or nuxt build for Nuxt to generate these types. If you create a composable without running the dev server, TypeScript will throw an error such as 'Cannot find name useBar'.
composables default export syntax
Composables can use default exports. A file named app/composables/use-foo.ts or composables/useFoo.ts with a default export will be available as useFoo() (camelCase of file name without extension). For example: export default function () { return useState('foo', () => 'bar') }
composables named export syntax
Composables can use named exports. For example, a file app/composables/useFoo.ts can export a named function: export const useFoo = () => { return useState('foo', () => 'bar') }
composables directory auto-import
The composables/ directory is used to auto-import Vue composables into your application. Files placed here are automatically imported and made available throughout your app without manual import statements.
composables scanning rules
Nuxt only scans files at the top level of the app/composables/ directory. Files like app/composables/index.ts and app/composables/useFoo.ts are scanned, but nested files like app/composables/nested/utils.ts are not automatically scanned.
named views for multiple outlets
A single route can render into multiple <NuxtPage> outlets using the name@view.vue filename convention. For example, child.vue renders into the default outlet and child@sidebar.vue renders into <NuxtPage name="sidebar" />. definePageMeta is only read from the default route file.
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.
nested routes with parent component
Nested routes are created by organizing pages in subdirectories. To display nested routes, use the <NuxtPage> component inside the parent page component. For example, pages/parent/child.vue creates a child route that displays within pages/parent.vue.
catch-all routes with bracket syntax
A file named [...slug].vue creates a catch-all route that matches all routes under that path. The slug parameter becomes an array of path segments. For example, navigating to /hello/world with a catch-all page makes $route.params.slug equal to ["hello", "world"].
dynamic route parameters with square brackets
Anything placed within square brackets in a page filename becomes a dynamic route parameter. For example, ~/pages/users-[group]/[id].vue creates a route where group and id are accessible via route.params. Parameters can be accessed using $route.params or the useRoute() composable.
pages must have single root element
Pages must have a single root element to allow route transitions between pages. HTML comments are considered elements. Multiple root elements or comments at the template root will cause client-side navigation to fail and the route will not render when navigating.
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.
automatic route creation from pages
Nuxt automatically creates a route for every page file in the ~/pages/ directory. The app/pages/index.vue file is mapped to the / route.
pages file extensions supported
Pages are Vue components and can have any of these extensions: .vue, .js, .jsx, .mjs, .ts, or .tsx.
pages directory is optional
The pages directory is optional. If you only use app.vue and don't have a pages directory, vue-router won't be included in your bundle. To force the pages system, set pages: true in nuxt.config or create a router.options.ts file.
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.
optional dynamic route parameters
To make a dynamic route parameter optional, enclose it in double square brackets. For example, ~/pages/[[slug]]/index.vue or ~/pages/[[slug]].vue will match both / and /test.
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.
route groups accessible in route metadata
Route groups are automatically available in route.meta.groups. This allows conditional logic based on which group a route belongs to. For example, route.meta.groups?.includes('marketing') returns true for pages in the (marketing) group.
route groups with parentheses
Folders wrapped in parentheses like (marketing) create route groups that don't affect file-based routing. For example, pages/(marketing)/about.vue produces /about, not /marketing/about.
definePageMeta key property for child route re-rendering
Inside a page component, definePageMeta({ key: route => route.fullPath }) can be used to control re-rendering of that page. This is an alternative to using the pageKey prop on <NuxtPage>.
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.
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.