Vue Router Multiguard

Common errors

• TypeError: multiguard is not a function

  cause This error typically occurs when `multiguard` is imported incorrectly, often by using a named import syntax (`import { multiguard } from '...'`) for a module that provides a default export.
  fix Change your import statement to `import multiguard from 'vue-router-multiguard';`. If using CommonJS `require`, ensure you access the default export correctly: `const multiguard = require('vue-router-multiguard').default;`

• NavigationDuplicated: Avoided redundant navigation to current location

  cause This warning (or similar) from Vue Router can appear if a guard redirects to the current route or attempts to push the same route multiple times consecutively. While not directly caused by `multiguard`, it's a common outcome of guard logic.
  fix Ensure your guards' redirection logic only fires when necessary. Before calling `next(path)`, you might add a check like `if (to.path !== path) { next(path); } else { next(false); }` to prevent unnecessary navigation calls if already on the target path.

Warnings

• gotcha Guards passed to `multiguard` are executed strictly in the order they are supplied. If an early guard calls `next()` with an argument (e.g., a path to redirect to), subsequent guards in the `multiguard` chain will be bypassed, and the route will not be entered. Ensure critical checks are placed earlier in the array.
  Fix: Carefully order your guards in the `multiguard` array. Place fundamental checks like authentication before more specific checks like detailed permissions or logging.
• gotcha Calling `next(false)` inside any guard within `multiguard` will immediately cancel the current navigation without redirecting or resolving any route. This can lead to a 'stuck' state if not handled gracefully in the UI.
  Fix: For most scenarios, redirecting with `next('/some-path')` is preferred to provide explicit user feedback. Use `next(false)` only when completely halting navigation without an alternative path, and ensure your application's UI accounts for this scenario (e.g., by not attempting navigation again until user interaction).
• gotcha TypeScript types for `vue-router-multiguard` were officially added in version 1.0.3. If you are working in a TypeScript project and using an older version (e.g., v1.0.2 or earlier), you will not have native type definitions available.
  Fix: Upgrade to `vue-router-multiguard@^1.0.3` to leverage the included TypeScript definitions, or provide your own `.d.ts` declaration files if upgrading is not an option.

Install

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

Imports

• multiguard
  wrong:

  import { multiguard } from 'vue-router-multiguard';

  correct:

  import multiguard from 'vue-router-multiguard';

  The `multiguard` function is a default export. Using named import syntax will result in an undefined value.
• multiguard (CommonJS)
  wrong:

  const multiguard = require('vue-router-multiguard');

  correct:

  const multiguard = require('vue-router-multiguard').default;

  While primarily designed for ES modules, if using CommonJS `require`, access the default export via `.default` due to ESM interop nuances in some environments.
• Type definitions
  wrong:

  import { Multiguard } from 'vue-router-multiguard/dist/types';

  correct:

  import multiguard, { Multiguard } from 'vue-router-multiguard';

  TypeScript types are included since v1.0.3. The main `multiguard` function is a default export, but you can import the `Multiguard` type directly from the package for explicit type hinting.

Quickstart

This quickstart demonstrates how to apply multiple navigation guards to Vue Router routes using `multiguard`. It defines example guards for authentication, role-based access, and logging, then shows how to chain them effectively on `beforeEnter` hooks. The example includes simulated navigation attempts to illustrate how guards execute serially and can redirect early based on conditions, providing clear console output for each step.

import Vue from 'vue';
import VueRouter, { RouteConfig } from 'vue-router';
import multiguard from 'vue-router-multiguard';

Vue.use(VueRouter);

// Example guard functions
const requireAuth = (to, from, next) => {
    const isAuthenticated = localStorage.getItem('userToken'); // Simulate auth check
    if (to.meta?.requiresAuth && !isAuthenticated) {
        console.log(`Guard 'requireAuth' blocked for ${to.path}: User not authenticated.`);
        next('/login'); // Redirect to login page
    } else {
        next(); // Proceed
    }
};

const requireAdmin = (to, from, next) => {
    const userRole = localStorage.getItem('userRole'); // Simulate role check
    if (to.meta?.requiresAdmin && userRole !== 'admin') {
        console.log(`Guard 'requireAdmin' blocked for ${to.path}: Not an administrator.`);
        next('/access-denied'); // Redirect for insufficient permissions
    } else {
        next(); // Proceed
    }
};

const logRoute = (to, from, next) => {
    console.log(`Guard 'logRoute' entered: ${from.path} -> ${to.path}`);
    next(); // Always proceed
};

const routes: Array<RouteConfig> = [
    {
        path: '/',
        component: { template: '<div><h1>Home</h1><p>Public access.</p></div>' },
        name: 'home'
    },
    {
        path: '/dashboard',
        component: { template: '<div><h1>Dashboard</h1><p>Authenticated access.</p></div>' },
        name: 'dashboard',
        meta: { requiresAuth: true },
        beforeEnter: multiguard([logRoute, requireAuth]) // Combined guards
    },
    {
        path: '/admin',
        component: { template: '<div><h1>Admin Panel</h1><p>Admin-only access.</p></div>' },
        name: 'admin',
        meta: { requiresAuth: true, requiresAdmin: true },
        beforeEnter: multiguard([logRoute, requireAuth, requireAdmin]) // Multiple combined guards
    },
    {
        path: '/login',
        component: { template: '<div><h1>Login</h1><p>Please log in.</p></div>' },
        name: 'login'
    },
    {
        path: '/access-denied',
        component: { template: '<div><h1>Access Denied</h1><p>You do not have permission to view this page.</p></div>' },
        name: 'access-denied'
    }
];

const router = new VueRouter({ routes });

// Simulate user state for demonstration
localStorage.setItem('userToken', 'fake-jwt-token-123'); // User is 'logged in'
localStorage.setItem('userRole', 'user'); // User is not 'admin'

console.log('--- Navigating to /dashboard (authenticated user) ---');
router.push('/dashboard').catch(err => console.error('Navigation error:', err.message));

setTimeout(() => {
    console.log('\n--- Navigating to /admin (authenticated but not admin) ---');
    router.push('/admin').catch(err => console.error('Navigation error:', err.message));
}, 100);

setTimeout(() => {
    console.log('\n--- Navigating to /dashboard (unauthenticated user) ---');
    localStorage.removeItem('userToken'); // Simulate logout
    router.push('/dashboard').catch(err => console.error('Navigation error:', err.message));
}, 200);

// For a real app, you'd mount this to a Vue instance:
// new Vue({ router, el: '#app' });