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

vite-plugin-vue-layouts

library0.11.0jsnpmunverified

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.

web-framework

npm install vite-plugin-vue-layouts

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-VUE-LA

vite-plugin-vue-layouts

web-frameworkjavascriptv0.11.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'

✗ const Layouts = require('vite-plugin-vue-layouts')

The plugin is an ESM module and should be imported using `import` syntax in `vite.config.js` or `vite.config.ts`.

setupLayouts

✓ import { setupLayouts } from 'virtual:generated-layouts'

✗ import { setupLayouts } from 'vite-plugin-vue-layouts'

This function is provided via a virtual module generated by the plugin at build time, not directly from the package itself.

Client-side Types

✓ /// <reference types="vite-plugin-vue-layouts/client" />

To get TypeScript declarations for 'virtual:generated-layouts', add 'vite-plugin-vue-layouts/client' to `compilerOptions.types` in your `tsconfig.json`.

Demonstrates basic setup, integrating the plugin with Vite, Vue, and Vue Router to enable router-based layouts using `vite-plugin-pages`.

import { defineConfig } from 'vite'; import Vue from '@vitejs/plugin-vue'; import Pages from 'vite-plugin-pages'; // Recommended companion plugin import Layouts from 'vite-plugin-vue-layouts'; export default defineConfig({ plugins: [ Vue(), Pages(), // Optional, but commonly used with this plugin Layouts({ layoutsDirs: 'src/layouts', defaultLayout: 'default' }) ] }); // src/main.ts import { createApp } from 'vue'; import { createRouter, createWebHistory } from 'vue-router'; import { setupLayouts } from 'virtual:generated-layouts'; import generatedRoutes from '~pages'; // From vite-plugin-pages import App from './App.vue'; // Transform generated routes with layouts const routes = setupLayouts(generatedRoutes); const router = createRouter({ history: createWebHistory(), routes, }); createApp(App).use(router).mount('#app');

Debug

Known issues

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

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.

affects: >=0.9.0

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

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

affects: >=0.9.0

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

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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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

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

[vite] Internal server error: Failed to resolve import "virtual:generated-layouts" from "src/main.ts". Does the file exist?

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

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.

Hot Module Replacement (HMR) for new pages or layout components is not working as expected.

This can happen if the `pagesDir` or `layoutsDirs` options are not correctly configured, preventing the plugin from watching the relevant directories for changes.

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.

Upgrade

Version history

0.11.0latest on npm

Audit

Dependencies

viterequiredPeer dependency for the build toolchain.

vuerequiredPeer dependency for the Vue.js framework.

vue-routerrequiredPeer dependency for Vue Router integration.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

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

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