{"id":12377,"library":"vite-plugin-vue-layouts-next","title":"Vite Vue Layouts Next Plugin","description":"vite-plugin-vue-layouts-next is a Vite plugin designed to streamline layout management for Vue 3 applications, particularly when integrated with Vue Router. It's a maintained and improved fork of the original `vite-plugin-vue-layouts`, providing robust support for the latest ecosystem versions including Vite 8, Vue 3, and Vue Router 5. The plugin automatically processes Vue components in a designated `layouts` directory, allowing pages to declare their desired layout via route meta fields (e.g., using `lang=\"yaml\"` blocks). It currently stands at version 2.1.0, with a recent release cadence demonstrating active development to keep pace with its peer dependencies. A key differentiator is its explicit compatibility with newer major versions of Vite and Vue Router, making it a suitable choice for projects on these updated stacks. It is also designed to work seamlessly with `vite-plugin-pages` for comprehensive auto-routing and layout solutions.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/loicduong/vite-plugin-vue-layouts-next","tags":["javascript","typescript","vite-plugin","vite","vue-router","vue"],"install":[{"cmd":"npm install vite-plugin-vue-layouts-next","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-vue-layouts-next","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-vue-layouts-next","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the Vite build tool, required for the plugin to function.","package":"vite","optional":false},{"reason":"Peer dependency for the Vue.js framework, as the plugin generates Vue-specific code.","package":"vue","optional":false},{"reason":"Peer dependency for Vue Router, which the plugin integrates with to manage layouts per route.","package":"vue-router","optional":false}],"imports":[{"note":"This is the default export for the plugin itself, used in `vite.config.ts`. The package is ESM-first.","wrong":"const Layouts = require('vite-plugin-vue-layouts-next')","symbol":"Layouts","correct":"import Layouts from 'vite-plugin-vue-layouts-next'"},{"note":"This function is generated by the plugin and imported from a virtual module in your `main.ts` or router setup file. It wraps your auto-generated routes with layout logic.","symbol":"setupLayouts","correct":"import { setupLayouts } from 'virtual:generated-layouts'"},{"note":"For TypeScript users, add `vite-plugin-vue-layouts-next/client` to your `tsconfig.json`'s `compilerOptions.types` array to get type definitions for `virtual:generated-layouts`.","symbol":"Client Types","correct":"/// <reference types=\"vite-plugin-vue-layouts-next/client\" />"}],"quickstart":{"code":"import Vue from '@vitejs/plugin-vue'\nimport { defineConfig } from 'vite'\nimport Pages from 'vite-plugin-pages'\nimport Layouts from 'vite-plugin-vue-layouts-next'\n\nexport default defineConfig({\n  plugins: [Vue(), Pages(), Layouts()],\n})\n\n// main.ts (or your router setup file)\nimport { setupLayouts } from 'virtual:generated-layouts'\nimport { createRouter, createWebHistory } from 'vue-router'\nimport generatedRoutes from '~pages'\n\n// For vite-plugin-pages integration\nconst routes = setupLayouts(generatedRoutes)\n\n// Or for vue-router 5's auto-routes:\n// import { routes } from 'vue-router/auto-routes'\n// const routes = setupLayouts(routes)\n\nconst router = createRouter({\n  history: createWebHistory(),\n  routes,\n})\n\n// In your tsconfig.json:\n/*\n{\n  \"compilerOptions\": {\n    \"types\": [\n      \"vite-plugin-vue-layouts-next/client\",\n      // ... other types\n    ]\n  }\n}\n*/","lang":"typescript","description":"This quickstart demonstrates how to integrate `vite-plugin-vue-layouts-next` into a Vite project using `vite.config.ts` and how to set up the generated layouts with Vue Router, specifically showing integration with `vite-plugin-pages` generated routes and the necessary TypeScript client types."},"warnings":[{"fix":"Review the official Vue Router 5 migration guide if upgrading your router. If staying on Vue Router 4, consider pinning `vite-plugin-vue-layouts-next` to `<2.0.0` or ensure your setup (`main.ts`) correctly handles the `setupLayouts` function's expected input for your Vue Router version.","message":"Version 2.0.0 introduced breaking changes by adding support for Vue Router 5. If you are upgrading from an earlier version and using Vue Router 4, ensure your `vue-router` peer dependency aligns with v4 or update your router configuration to be compatible with Vue Router 5.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update your Vite installation to a compatible version (6, 7, or 8) or ensure your `package.json`'s `vite` entry aligns with the plugin's peer dependency requirements.","message":"Version 2.1.0 added support for Vite 8. While this is an enhancement, ensure your project's Vite version is compatible with the plugin's peer dependency range `^6.0.0 || ^7.0.0 || ^8.0.0` to avoid potential build issues.","severity":"breaking","affected_versions":">=2.1.0"},{"fix":"Consider installing and configuring `vite-plugin-pages` for a more integrated and automated routing experience. If not using `vite-plugin-pages`, ensure your manual route definitions are compatible with the `setupLayouts` function.","message":"The plugin is designed to work best alongside `vite-plugin-pages`. While not strictly required, using it without an auto-page generation plugin might necessitate more manual route configuration to leverage its full capabilities.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you have a `default.vue` component in your `src/layouts` directory (or specified `layoutsDirs`). Alternatively, configure the `defaultLayout` option in the plugin's settings to point to your desired fallback layout file name.","message":"By default, pages without a specified layout will use `default.vue` from your `layoutsDirs`. If this file is missing or named differently, your pages might not render correctly or fall back to an unexpected layout.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `\"vite-plugin-vue-layouts-next/client\"` to the `types` array in your `tsconfig.json` under `compilerOptions`.","message":"For TypeScript users, to get proper type definitions for the `virtual:generated-layouts` module, you must explicitly add `vite-plugin-vue-layouts-next/client` to the `compilerOptions.types` array in your `tsconfig.json`.","severity":"gotcha","affected_versions":">=1.0.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-next/client\"` to the `compilerOptions.types` array in your `tsconfig.json`.","cause":"TypeScript cannot locate the type definitions for the virtual module generated by the plugin.","error":"Cannot find module 'virtual:generated-layouts' or its corresponding type declarations."},{"fix":"Ensure `vite-plugin-pages` is correctly configured and running before `vite-plugin-vue-layouts-next`, and that `setupLayouts` is passed the output of your page generation. Also, verify that your default layout (`default.vue`) and any specified layouts exist in your `layoutsDirs`.","cause":"This often occurs when `setupLayouts` receives routes that haven't been processed by `vite-plugin-pages` or are not in the expected format, or when a layout file is missing.","error":"[vite] Internal server error: Cannot read properties of undefined (reading 'meta')"},{"fix":"Ensure `Layouts()` is called as `plugins: [Vue(), Pages(), Layouts()]` where `Pages()` comes before `Layouts()` if you are using `vite-plugin-pages`. Verify all plugin calls are correctly array members within `defineConfig`.","cause":"This can happen if the `plugins` array in `vite.config.ts` has an incorrect order or if `Layouts()` is called without being wrapped as part of a Vite plugin configuration.","error":"Error: [vite] Cannot read properties of undefined (reading 'indexOf') in vite-plugin-vue-layouts-next"}],"ecosystem":"npm"}