Registry / web-framework / vite-plugin-vue-layouts-next

vite-plugin-vue-layouts-next

library2.1.0jsnpmunverified

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.

web-framework

npm install vite-plugin-vue-layouts-next

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-VUE-LA

vite-plugin-vue-layouts-next

web-frameworkjavascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Layouts

✓ import Layouts from 'vite-plugin-vue-layouts-next'

✗ const Layouts = require('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`.

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 ] } } */

Debug

Known issues

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

affects: >=2.0.0

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

affects: >=2.1.0

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'virtual:generated-layouts' or its corresponding type declarations.

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')

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

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

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

viterequiredPeer dependency for the Vite build tool, required for the plugin to function.

vuerequiredPeer dependency for the Vue.js framework, as the plugin generates Vue-specific code.

vue-routerrequiredPeer dependency for Vue Router, which the plugin integrates with to manage layouts per route.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/loicduong/vite-plugin-vue-layouts-next ↗

packagehttps://www.npmjs.com/package/vite-plugin-vue-layouts-next ↗