@this-dot/vue-route-guard

Vue Route Guard 🛡️

Vue Route Guard is an Vue library that wraps around the vue-router and extends it to provide helpful methods to handle page guards via token authorization and permissions.

It supports:

✅  Adding guards to pages
✅  Ability to choose between different storage options for storing token
✅  Storing and Retrieving authentication data (user details and token)
✅  Exposes method for checking matching page permission within components and pages

---

Installation

Install the package:
npm install @this-dot/vue-route-guard
or
yarn add @this-dot/vue-route-guard

Usage

To get started, we will need to register Vue Route Guard.

Register using Vue.use

It is very simple to add route guard to your Vue app:

Just import the setupGuard module

import { setupGuard } from '@this-dot/vue-route-guard';

Install the plugin

vue.use(setupGuard(guardConfig));

Router Meta

We extended the default router meta to accept the following fields:

Field	Description	Required	Type
requiresAuth	Describes if the page requires authentication	true	boolean
access	Describes the access permissions needed for the route	false	string[]

Guard Config

setupGuard requires to pass an object with the following fields:

Field	Description	Required	Type
router	The router instance used in your vue app	true	Router
token.name	The name used to store and retrieve the token	true	string
token.storage	Storage type (This defaults to session storage)	false	StorageType
redirect.noAuthentication	page to redirect to if no token found or fetchAuthentication fails	false	RouteLocationRaw
redirect.noPermission	page to redirect to if permission is not in route meta access (redirects to noAuthentication if it is not passed)	false	RouteLocationRaw
redirect.clearAuthentication	page to redirect to after clearing authentication (redirects to noAuthentication if it is not passed)	false	RouteLocationRaw
options.fetchAuthentication	This is expects function that returns an object with the authentication information	true	Promise<{}>
options.permissionKey	Describes the field that holds the authentication permission in fetchAuthentication (default permission)	false	string

Example

Create a sample router and guard configuration:

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: '/',
      name: 'home',
      component: () => import('../views/HomeView.vue'),
      meta: { requiresAuth: true },
    },
    {
      path: '/login',
      name: 'login',
      component: () => import('../views/LoginView.vue'),
      meta: { requiresAuth: false },
    },
    {
      path: '/about',
      name: 'about',
      component: () => import('../views/AboutView.vue'),
      meta: {
        requiresAuth: true,
        access: ['admin'],
      },
    },
    {
      path: '/no-permission',
      name: 'no-permission',
      component: () => import('../views/NoPermissionView.vue'),
      meta: {
        requiresAuth: false,
      },
    },
  ],
});
const guardConfig = {
  router: router,
  token: {
    name: 'XSRF-TOKEN',
  },
  redirect: {
    noAuthentication: '/login',
    clearAuthentication: '/login',
    noPermission: '/no-permission',
  },
  options: {
    fetchAuthentication: () => {
      return new Promise(function (resolve, reject) {
        return resolve({
          firstName: 'firstName',
          lastName: 'lastName',
          login: true,
          permission: ['user'],
        });
      });
    },
  },
};
vue.use(setupGuard(guardConfig));

Create a guard config using token. expires: it can be a valid date string or a number to represent the days path: page path for cookie

const guardConfig = {
  router: router,
  token: {
    name: 'XSRF-TOKEN',
    storage: StorageType.cookieStorage,
    attributes: {
      path: '/',
      expires: 2, // cookie to expire in 2 days
    },
  },
  redirect: {
    noAuthentication: '/login',
    clearAuthentication: '/login',
    noPermission: '/no-permission',
  },
  options: {
    fetchAuthentication: () => {
      return new Promise(function (resolve, reject) {
        return resolve({
          firstName: 'firstName',
          lastName: 'lastName',
          login: true,
          permission: ['user'],
        });
      });
    },
  },
};

Access Authentication State

<template>
  <div>{{ auth.$store.state.authentication }}</div>
</template>
<script setup lang="ts">
  import { useGuard } from '@this-dot/vue-route-guard';

  const auth = useGuard();
</script>

Clear Authentication

<script setup lang="ts">
  import { useGuard } from '@this-dot/vue-route-guard';

  const auth = useGuard();

  const logout = () => {
    auth.clearAuthentication().then(() => {
      console.log('cleared authentication');
    });
  };
</script>

Refresh Authentication

This calls fetch authentication and updates the state with the new authentication details

<template>
  <div>
    <span>{{ auth.$store.state.authentication }}</span>
    <button @click="updateAuthentiationInformation">Update</button>
  </div>
</template>
<script setup lang="ts">
  import { useGuard } from '@this-dot/vue-route-guard';

  const auth = useGuard();

  const updateAuthentiationInformation = () => {
    auth.refreshAuthentication();
  };
</script>

Check if user has access

hasAuthenticationAccess can be accessed from useGuard and called to check if user has access to specific permission

<template>
  <header>
    <div class="wrapper">
      <nav>
        <RouterLink to="/">Home</RouterLink>
        <RouterLink v-if="auth.hasAuthenticationAccess(['admin'])" to="/about">About</RouterLink>
      </nav>
    </div>
  </header>

  <RouterView />
</template>

<script setup lang="ts">
  import { useGuard } from '@ds-library/ui';

  const auth = useGuard();
</script>