vite-plugin-layouts

Router based layouts for Vue 3 applications using Vite.

Features

• 📁 File Based Layouts are stored in /src/layouts as standard Vue components
• 🔄 Sensible Defaults Pages without a layout use default.vue automatically
• 🌐 Multiple Layouts Support for multiple layout directories
• 🎨 Meta Configuration Specify layouts via route blocks in your pages
• 🔌 Router Integration Pairs with unplugin-vue-router
• 📱 HMR Optimized Client-side layout mode for faster HMR
• 🛠️ Flexible Configuration Customize layout directories, exclusions, and more

Install

1npm install -D vite-plugin-layouts
2# or
3yarn add -D vite-plugin-layouts
4# or
5pnpm add -D vite-plugin-layouts
6# or
7bun add -D vite-plugin-layouts

Get Started

1// vite.config.ts
2import Vue from '@vitejs/plugin-vue'
3import { defineConfig } from 'vite'
4import Layouts from 'vite-plugin-layouts'
5import Pages from 'vite-plugin-pages'
6
7export default defineConfig({
8  plugins: [
9    Vue(),
10    Pages(),
11    Layouts()
12  ]
13})

Then in your main.ts file:

1// main.ts
2import { setupLayouts } from 'virtual:generated-layouts'
3import { createRouter } from 'vue-router'
4import generatedRoutes from '~pages'
5
6const routes = setupLayouts(generatedRoutes)
7
8const router = createRouter({
9  // ...
10  routes,
11})

If you're using unplugin-vue-router:

1// main.ts
2import { setupLayouts } from 'virtual:generated-layouts'
3import { createRouter } from 'vue-router/auto'
4
5const router = createRouter({
6  // ...
7  extendRoutes: routes => setupLayouts(routes),
8})

TypeScript Support

If you want type definition for the virtual modules, add the following to your tsconfig.json:

1{
2  "compilerOptions": {
3    "types": ["vite-plugin-layouts/client"]
4  }
5}

Usage

Layouts are stored in the /src/layouts folder by default and are standard Vue components with a <router-view></router-view> in the template.

You can specify which layout to use for a page by using a route block:

1<route lang="yaml">
2meta:
3  layout: users
4</route>

This will look for /src/layouts/users.vue for the page's layout. If no layout is specified, it will use default.vue.

Configuration

1// vite.config.ts
2import Vue from '@vitejs/plugin-vue'
3import { defineConfig } from 'vite'
4import Layouts from 'vite-plugin-layouts'
5import Pages from 'vite-plugin-pages'
6
7export default defineConfig({
8  plugins: [
9    Vue(),
10    Pages(),
11    Layouts({
12      layoutsDirs: 'src/layouts', // default: 'src/layouts'
13      pagesDirs: 'src/pages', // default: 'src/pages'
14      defaultLayout: 'default', // default: 'default'
15      exclude: [], // Patterns to exclude from layout loading
16    })
17  ]
18})

Available Options

Option	Type	Default	Description
layoutsDirs	string | string[]	'src/layouts'	Path(s) to the layouts directory. Supports globs.
pagesDirs	string | string[] | null	'src/pages'	Path(s) to the pages directory. Set to null to watch all files.
defaultLayout	string	'default'	Name of the default layout to use when none is specified.
exclude	string[]	[]	Patterns to exclude from layout loading. Files named __*__.vue are automatically excluded.

Advanced Configuration: ClientSideLayout

For faster HMR and more efficient loading, you can use the ClientSideLayout mode:

1// vite.config.ts
2import Vue from '@vitejs/plugin-vue'
3import { defineConfig } from 'vite'
4import { ClientSideLayout } from 'vite-plugin-layouts'
5import Pages from 'vite-plugin-pages'
6
7export default defineConfig({
8  plugins: [
9    Vue(),
10    Pages(),
11    ClientSideLayout({
12      layoutsDir: 'src/layouts', // default: 'src/layouts'
13      defaultLayout: 'default', // default: 'default'
14      importMode: 'sync' // Auto-detect: 'sync' for SSG, 'async' for others
15    })
16  ]
17})

How It Works

The setupLayouts function transforms your routes by:

1. Replacing pages with their specified layouts
2. Making the original pages children of their layouts

This creates nested routes with the same paths, giving you full access to the vue-router API.

Common Patterns

Transitions Between Routes

To add transitions between routes, including when using the same layout:

1<!-- App.vue -->
2<template>
3  <router-view v-slot="{ Component, route }">
4    <transition name="slide">
5      <component :is="Component" :key="route" />
6    </transition>
7  </router-view>
8</template>

Passing Data from Layout to Page

Use props to pass data down from layout to page:

1<router-view foo="bar" />

Setting Static Data for a Layout

Use the route's meta property in your page:

1<!-- page.vue -->
2<template>
3  <div>Content</div>
4</template>
5
6<route lang="yaml">
7meta:
8  layout: default
9  bgColor: yellow
10</route>

Then in your layout:

1<!-- layout.vue -->
2<script setup>
3import { useRouter } from 'vue-router'
4</script>
5
6<template>
7  <div :style="`background: ${useRouter().currentRoute.value.meta.bgColor};`">
8    <router-view />
9  </div>
10</template>

Dynamic Data from Page to Layout

Use custom events to pass data from page to layout:

1<!-- page.vue -->
2<script setup>
3import { defineEmits } from 'vue'
4const emit = defineEmits(['setColor'])
5
6if (2 + 2 === 4)
7  emit('setColor', 'green')
8else
9  emit('setColor', 'red')
10</script>

Listen for the events in your layout:

1<!-- layout.vue -->
2<script setup>
3import { ref } from 'vue'
4
5const bgColor = ref('yellow')
6function setBg(color) {
7  bgColor.value = color
8}
9</script>
10
11<template>
12  <main :style="`background: ${bgColor};`">
13    <router-view @set-color="setBg" />
14  </main>
15</template>

Testing

1bun test

Changelog

Please see our releases page for more information on what has changed recently.

Contributing

Please review the Contributing Guide for details.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where vite-plugin-layouts is being used! We showcase them on our website too.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

Credits

• JohnCampionJr - Creator of original vite-plugin-vue-layouts
• Chris Breuer
• All Contributors

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙