Vite Vue Layouts Next Plugin

2.1.0 · active · verified Sun Apr 19

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.

Common errors

```
Cannot find module 'virtual:generated-layouts' or its corresponding type declarations.
```
cause TypeScript cannot locate the type definitions for the virtual module generated by the plugin.

fix Add `"vite-plugin-vue-layouts-next/client"` to the `compilerOptions.types` array in your `tsconfig.json`.
```
[vite] Internal server error: Cannot read properties of undefined (reading 'meta')
```
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.

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`.
```
Error: [vite] Cannot read properties of undefined (reading 'indexOf') in vite-plugin-vue-layouts-next
```
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.

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`.

Warnings

breaking 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.
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.
breaking 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.
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.
gotcha 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.
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.
gotcha 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.
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.
gotcha 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`.
Fix: Add `"vite-plugin-vue-layouts-next/client"` to the `types` array in your `tsconfig.json` under `compilerOptions`.

Install

npm install vite-plugin-vue-layouts-next npm
yarn add vite-plugin-vue-layouts-next yarn
pnpm add vite-plugin-vue-layouts-next pnpm

Imports

Layouts
wrong:
```
const Layouts = require('vite-plugin-vue-layouts-next')
```
correct:
```
import Layouts from 'vite-plugin-vue-layouts-next'
```
This is the default export for the plugin itself, used in `vite.config.ts`. The package is ESM-first.
setupLayouts
```
import { setupLayouts } from 'virtual:generated-layouts'
```
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.
Client Types
```
/// <reference types="vite-plugin-vue-layouts-next/client" />
```
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`.

Quickstart

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.

import Vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'
import Pages from 'vite-plugin-pages'
import Layouts from 'vite-plugin-vue-layouts-next'

export default defineConfig({
  plugins: [Vue(), Pages(), Layouts()],
})

// main.ts (or your router setup file)
import { setupLayouts } from 'virtual:generated-layouts'
import { createRouter, createWebHistory } from 'vue-router'
import generatedRoutes from '~pages'

// For vite-plugin-pages integration
const routes = setupLayouts(generatedRoutes)

// Or for vue-router 5's auto-routes:
// import { routes } from 'vue-router/auto-routes'
// const routes = setupLayouts(routes)

const router = createRouter({
  history: createWebHistory(),
  routes,
})

// In your tsconfig.json:
/*
{
  "compilerOptions": {
    "types": [
      "vite-plugin-vue-layouts-next/client",
      // ... other types
    ]
  }
}
*/

view raw JSON →