Vue Router Layout Selector

Common errors

• TypeError: app.use is not a function

  cause Attempting to use `vue-router-layout` v0.2.0+ (designed for Vue 3) in a Vue 2 project, where `app.use` syntax is not available.
  fix Downgrade `vue-router-layout` to `0.1.x` for Vue 2 projects, or upgrade your entire project to Vue 3.

• Property 'layout' does not exist on type 'ComponentOptionsBase<any, any, any, any, any, any, any, any, any>'.

  cause TypeScript compiler error when using the custom `layout` option within a Vue component's options API, as the type definitions do not automatically include this custom property.
  fix Augment Vue's `ComponentCustomOptions` interface to declare the `layout` property. For example: `declare module '@vue/runtime-core' { interface ComponentCustomOptions { layout?: string | { name: string; props?: Record<string, any> }; } }`

• Layout component does not update or render correctly after route navigation, especially with lazy-loaded components.

  cause Older versions of `vue-router-layout` had known bugs related to the reactivity and lifecycle of dynamically loaded components within the layout system.
  fix Upgrade `vue-router-layout` to version `0.3.0` or higher, which includes significant improvements for handling lazy component loading and ensuring proper layout updates.

Warnings

• breaking Version 0.2.0 and later drops support for Vue 2, requiring Vue 3 or higher. Projects on Vue 2 must use `vue-router-layout@0.1.x`.
  Fix: Upgrade your project's Vue version to v3+, or downgrade `vue-router-layout` to a `0.1.x` release for Vue 2 compatibility.
• gotcha The `created` hook in page components could be wrongly called when the layout changes, leading to unintended side effects or re-initialization.
  Fix: Upgrade to `vue-router-layout@0.4.1` or newer to resolve the issue where the `created` hook is incorrectly triggered on layout changes.
• gotcha Prior to v0.4.0, directly passing props to layout components via the `layout` option in route meta or component options was not supported, limiting layout reusability.
  Fix: Upgrade to `vue-router-layout@0.4.0` or newer to utilize the `layout.props` option for passing data to your layout components.
• gotcha Initial versions (`<0.3.0`) had issues with lifecycle hooks or layout updates when using async components for pages or layouts, potentially leading to incorrect rendering or hook calls and requiring manual workarounds.
  Fix: Ensure you are on `vue-router-layout@0.3.0` or later to benefit from improved handling of lazy component loading in router hooks and corrected lifecycle behavior, especially with async components.

Install

• npm install vue-router-layout npm
• yarn add vue-router-layout yarn
• pnpm add vue-router-layout pnpm

Imports

• createRouterLayout
  wrong:

  const createRouterLayout = require('vue-router-layout')

  correct:

  import { createRouterLayout } from 'vue-router-layout'

  The primary named export, a factory function that returns the RouterLayout component.
• LayoutResolver

  import type { LayoutResolver } from 'vue-router-layout'

  Type import for the callback function that resolves layout components passed to `createRouterLayout`.
• RouterLayoutOptions

  import type { RouterLayoutOptions } from 'vue-router-layout'

  Type import for the options object that can be passed to `createRouterLayout`.

Quickstart

Initializes a `RouterLayout` component, configuring Vue Router to use it for dynamic layout resolution based on route meta or component options, demonstrating basic layout switching and prop passing.

import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { createRouterLayout } from 'vue-router-layout';

// Define your layout components
const DefaultLayout = { template: '<div><h1>Default Layout</h1><router-view /></div>' };
const AdminLayout = { template: '<div><h2>Admin Panel Layout</h2><router-view /></div>' };

// Create <RouterLayout> component.
const RouterLayout = createRouterLayout(layout => {
  if (layout === 'admin') {
    return Promise.resolve(AdminLayout);
  }
  return Promise.resolve(DefaultLayout);
});

const routes = [
  {
    path: '/',
    component: RouterLayout,
    children: [
      {
        path: '',
        component: { template: '<p>Home Page</p>', layout: 'default' },
      },
      {
        path: 'dashboard',
        component: { template: '<p>Admin Dashboard</p>', layout: { name: 'admin', props: { title: 'Admin' } } },
      },
      {
        path: 'profile',
        component: { template: '<p>User Profile</p>', layout: 'default' },
      },
    ],
  },
];

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

const app = createApp({});
app.use(router);
app.mount('#app');

// For a real application, you would render this in an HTML file:
// <div id="app"></div>
// <router-view></router-view>