FusionAuth Vue SDK

This SDK provides helpful methods and reactive values that integrate with FusionAuth to help automatically manage authentication state in your Vue app.

Your users will be sent to FusionAuth’s themeable hosted login pages and then log in. After that, they are sent back to your Vue application.

Once authentication succeeds, the following secure, HTTP-only cookies will be set:

  • app.at - an OAuth Access Token

  • app.rt - a Refresh Token used to obtain a new app.at. This cookie will only be set if refresh tokens are enabled on your FusionAuth instance.

The access token can be presented to APIs to authorize the request and the refresh token can be used to get a new access token.

There are 2 ways to interact with this SDK:

  1. By hosting your own server that performs the OAuth token exchange and meets the server code requirements for FusionAuth Web SDKs.
  2. By using the server hosted on your FusionAuth instance, i.e., not writing your own server code.

If you are hosting your own server, see server code requirements.

You can use this library against any version of FusionAuth or any OIDC compliant identity server.

Getting Started

Installation

NPM:

npm install @fusionauth/vue-sdk

Yarn:

yarn add @fusionauth/vue-sdk

Usage

Configuring the SDK

Configure and initialize the FusionAuthVuePlugin when you create your Vue app:

import { createApp } from 'vue';
import FusionAuthVuePlugin, { type FusionAuthConfig } from '@fusionauth/vue-sdk';

const config: FusionAuthConfig = {
  clientId: "", // Your app's FusionAuth client id
  serverUrl: "", // The url of the server that performs the token exchange
  redirectUri: "", // The URI that the user is directed to after the login/register/logout action
  shouldAutoFetchUserInfo: true, // Automatically fetch userInfo when logged in. Defaults to false.
  shouldAutoRefresh: true, // Enables automatic token refresh. Defaults to false.
  onRedirect: (state?: string) => { }, // Optional callback invoked upon redirect back from login or register.
}

const app = createApp(App);

app.use(FusionAuthVuePlugin, config);
app.mount('#app')

If you want to use the pre-styled buttons, don't forget to import the css file:

import '@fusionauth/vue-sdk/dist/style.css';

Configuring with Nuxt

If you're using the SDK in a nuxt app, pass the useCookie composable into the config object in your plugin definition.

import { useCookie } from "#app";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(FusionAuthVuePlugin, {
    ...config
    nuxtUseCookie: useCookie,
  });
});
Alternate ways to define your nuxt plugin

Using createFusionAuth, the SDK can be configured more flexibly.

export default defineNuxtPlugin({
  setup(nuxtApp) {
    const fusionauth = createFusionAuth(config);   
    nuxtApp.vueApp.use(FusionAuthVuePlugin, { instance: fusionauth })
    return {
      provide: { fusionauth }
    };
  },
})

useFusionAuth composable

You can interact with the SDK by using the useFusionAuth, which leverages Vue's Composition API. View the full API documentation

<script setup lang="ts">
import { computed } from 'vue';
import { useFusionAuth } from "@fusionauth/vue-sdk";

const {
  isLoggedIn,
  userInfo,
  isFetchingUserInfo,
  login,
  register,
  logout
} = useFusionAuth();

const welcomeMessage = computed(() => {
  const name = userInfo.value?.given_name
  return name 
    ? 'Welcome!'
    : `Welcome ${userInfo.value.given_name}!`;
});
</script>

<template>
  <p>{{ welcomeMessage }}</p>

  <div v-if="isLoggedIn">
    <p v-if="isFetchingUserInfo">
      Loading...
    </p>
    <button @click="logout()">Logout</button>
  </div>

  <div v-if="!isLoggedIn">
    <button @click="login()">Login</button>
    <p>or</p>
    <button @click="register()">Register</button>
  </div>
</template>

State parameter

The login and register functions accept an optional string parameter: state, which will be passed back to the optional onRedirect callback specified on your FusionAuthConfig. Though you may pass any value you would like for the state parameter, it is often used to indicate which page the user was on before redirecting to login or registration, so that the user can be returned to that location after a successful authentication.

UI Components

Protecting Content

The RequireAuth and RequireAnonymous can be used to restrict content based on authentication and authorization.

<template>
  <RequireAuth :with-role="['ADMIN', 'SUPER-ADMIN']">
    <!-- only displays for users with specifed role -->
    <button>Delete user</button>
  </RequireAuth>
</template>

<template>
  <RequireAnonymous>
    <!-- content for unauthenticated users -->
  </RequireAnonymous>
</template>

Pre-built buttons

There are three pre-styled buttons that are configured to perform login/logout/registration. They can be placed anywhere in your app as is.

<template>
  <FusionAuthLoginButton />
  <FusionAuthLogoutButton />
  <FusionAuthRegisterButton />
</template>

<style>
  :root {
    --fusionauth-button-background-color: #096324;
    --fusionauth-button-text-color: #fff;
  }
</style>

With the CSS variables, you can customize the buttons to match your app’s style.

Quickstart

See the FusionAuth Vue Quickstart for a full tutorial on using FusionAuth and Vue.

Documentation

Full library documentation

These docs are generated with typedoc and configured with typedoc-plugin-markdown.

Usage With FusionAuth Cloud

When developing against a FusionAuth Cloud instance with a hostname ending in fusionauth.io, unless your application shares the same domain of fusionauth.io attempts to use these endpoints will fail with a 403 status code.

These endpoints do not work correctly for cross origin requests. Cross origin requests occur when the application making the request to FusionAuth is using a separate domain. For example, if your application URL is app.acme.com and the FusionAuth URL is acme.fusionauth.io requests from your application to FusionAuth will be considered cross origin.

If possible, have FusionAuth and your application served by the same domain, using a proxy if needed. For example, serve your app from app.acme.com and FusionAuth from auth.acme.com.

If this configuration is not possible, use one of these alternative methods:

Modifying FusionAuth CORS configuration options does not fix this issue because the cookies that FusionAuth writes will not be accessible cross domain.

Source Code

The source code is available here: https://github.com/FusionAuth/fusionauth-javascript-sdk/tree/main/packages/sdk-vue/

Upgrade Policy

Besides the releases made to keep track of the FusionAuth API as mentioned above, SDKs and Client Libraries may periodically receive updates with bug fixes, security patches, tests, code samples, or documentation changes.

These releases may also update dependencies, language engines, and operating systems, as we’ll follow the deprecation and sunsetting policies of the underlying technologies that the libraries use.

This means that after a language, framework, or operating system is deprecated by their own maintainer, our SDKs and Client Libraries that depend on it will also be deprecated by us, and will eventually be updated to use a newer version.