Vite Plugin for Vue Router Layouts

Common errors

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

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

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

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

Warnings

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

Install

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

Imports

• Layouts
  wrong:

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

  correct:

  import Layouts from '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
  wrong:

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

  correct:

  import { setupLayouts } from 'virtual:generated-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`.

Quickstart

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