{"id":12379,"library":"vite-plugin-vue-layouts","title":"Vite Plugin for Vue Router Layouts","description":"vite-plugin-vue-layouts is a Vite plugin designed to simplify the implementation of router-based layouts in Vue 3 applications. It is currently at version 0.11.0 and is actively maintained, with regular updates and fixes. The plugin works by transforming Vue Router configurations, effectively wrapping page components within specified layout components as nested routes. It integrates seamlessly with `vite-plugin-pages` and `unplugin-vue-router`, allowing developers to define layouts for individual pages using route blocks (e.g., `<route lang=\"yaml\"> meta: { layout: 'my-layout' } </route>`). Layout components, typically stored in `src/layouts`, are automatically discovered and asynchronously imported, providing a structured approach to managing application layouts.","status":"active","version":"0.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/johncampionjr/vite-plugin-vue-layouts","tags":["javascript","typescript"],"install":[{"cmd":"npm install vite-plugin-vue-layouts","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-vue-layouts","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-vue-layouts","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the build toolchain.","package":"vite","optional":false},{"reason":"Peer dependency for the Vue.js framework.","package":"vue","optional":false},{"reason":"Peer dependency for Vue Router integration.","package":"vue-router","optional":false}],"imports":[{"note":"The plugin is an ESM module and should be imported using `import` syntax in `vite.config.js` or `vite.config.ts`.","wrong":"const Layouts = require('vite-plugin-vue-layouts')","symbol":"Layouts","correct":"import Layouts from 'vite-plugin-vue-layouts'"},{"note":"This function is provided via a virtual module generated by the plugin at build time, not directly from the package itself.","wrong":"import { setupLayouts } from 'vite-plugin-vue-layouts'","symbol":"setupLayouts","correct":"import { setupLayouts } from 'virtual:generated-layouts'"},{"note":"To get TypeScript declarations for 'virtual:generated-layouts', add 'vite-plugin-vue-layouts/client' to `compilerOptions.types` in your `tsconfig.json`.","symbol":"Client-side Types","correct":"/// <reference types=\"vite-plugin-vue-layouts/client\" />"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport Vue from '@vitejs/plugin-vue';\nimport Pages from 'vite-plugin-pages'; // Recommended companion plugin\nimport Layouts from 'vite-plugin-vue-layouts';\n\nexport default defineConfig({\n  plugins: [\n    Vue(),\n    Pages(), // Optional, but commonly used with this plugin\n    Layouts({\n      layoutsDirs: 'src/layouts',\n      defaultLayout: 'default'\n    })\n  ]\n});\n\n// src/main.ts\nimport { createApp } from 'vue';\nimport { createRouter, createWebHistory } from 'vue-router';\nimport { setupLayouts } from 'virtual:generated-layouts';\nimport generatedRoutes from '~pages'; // From vite-plugin-pages\nimport App from './App.vue';\n\n// Transform generated routes with layouts\nconst routes = setupLayouts(generatedRoutes);\n\nconst router = createRouter({\n  history: createWebHistory(),\n  routes,\n});\n\ncreateApp(App).use(router).mount('#app');","lang":"typescript","description":"Demonstrates basic setup, integrating the plugin with Vite, Vue, and Vue Router to enable router-based layouts using `vite-plugin-pages`."},"warnings":[{"fix":"Ensure your project's `vite`, `vue`, and `vue-router` versions meet the new peer dependency requirements (Vite ^4.0.0 || ^5.0.0, Vue ^3.2.4, Vue Router ^4.0.11). Revert to an earlier version of `vite-plugin-vue-layouts` if older environment support is strictly necessary.","message":"Version 0.9.0 introduced significant breaking changes by removing support for Vue 2, Vite 2, and Vite 3. The plugin now strictly requires Vite 4 or 5 and Vue 3.2.4 or newer.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Set `pagesDir: null` in the plugin configuration to revert to the old behavior of watching all files, or specify an array of paths/globs if your pages are in multiple non-default locations, e.g., `pagesDir: ['src/pages', 'src/**/pages']`.","message":"The default value for the `pagesDir` option changed in version 0.9.0 from `null` (watching all files) to `'src/pages'`. If you rely on the plugin watching page files outside of `src/pages` or in multiple directories, you must explicitly configure `pagesDir`.","severity":"gotcha","affected_versions":">=0.9.0"},{"fix":"Always define a `default.vue` layout component in your `layoutsDirs` (e.g., `src/layouts/default.vue`) to ensure all pages have a fallback layout. Alternatively, explicitly set the `defaultLayout` option in the plugin configuration.","message":"Layouts are configured via `meta.layout` in route blocks. If a page does not specify a layout, it will default to the layout component named 'default.vue' in your `layoutsDirs`.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `\"vite-plugin-vue-layouts/client\"` to the `compilerOptions.types` array in your `tsconfig.json`. Ensure the plugin is correctly instantiated in `vite.config.ts` and that your `main.ts` imports `setupLayouts` from `virtual:generated-layouts`.","cause":"The TypeScript compiler or runtime cannot resolve the virtual module. This is often due to missing type definitions in `tsconfig.json` or incorrect plugin setup in `vite.config.js`.","error":"Cannot find module 'virtual:generated-layouts' or its corresponding type declarations."},{"fix":"Verify that `Layouts()` is included in your `plugins` array in `vite.config.js` (or `.ts`). Ensure there are no syntax errors in your Vite configuration file that might prevent the plugin from initializing.","cause":"The Vite development server failed to generate or resolve the virtual module. This typically indicates that `vite-plugin-vue-layouts` is not correctly configured or loaded in `vite.config.js`.","error":"[vite] Internal server error: Failed to resolve import \"virtual:generated-layouts\" from \"src/main.ts\". Does the file exist?"},{"fix":"Double-check your `pagesDir` and `layoutsDirs` options in the plugin configuration. If you moved your pages or layouts, update these paths. Remember that `pagesDir` changed default in v0.9.0; setting `pagesDir: null` might resolve issues if you need broader file watching.","cause":"This can happen if the `pagesDir` or `layoutsDirs` options are not correctly configured, preventing the plugin from watching the relevant directories for changes.","error":"Hot Module Replacement (HMR) for new pages or layout components is not working as expected."}],"ecosystem":"npm"}