Nuxt-cookies-auth NPM

Nuxt Cookies Auth

➡️ useFetch with automatic token refresh (stored in httpOnly cookies) ⬅️

Nuxt 3 module for passing cookies with each useFetch request (with the client calls and the SSR calls as well).
httpOnly Cookies are the best option for storing access token (this way it is protected against XSS). Module automatically tries to refresh tokens with a POST call to a specified url on a 401 Unauthorized exception response.

Features

🌲 Handles access and refresh tokens, both can be httpOnly
🚠 Automatically tries to refresh tokens on 401 response
⛰ Works on client and server api

Quick Setup

Add nuxt-cookies-auth dependency to your project

# Using pnpm
pnpm add -D nuxt-cookies-auth

# Using yarn
yarn add --dev nuxt-cookies-auth

# Using npm
npm install --save-dev nuxt-cookies-auth

Add nuxt-cookies-auth to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: ["nuxt-cookies-auth"]
  ...
})

Add configuration to the nuxt.config.ts

export default defineNuxtConfig({
  ...
  cookiesAuth: {
    apiBaseUrl: "",
    refreshTokenUrl: "/api/refresh",
    redirectOnRefreshTokenExpiration: true,
    redirectTo: "/login"
  }
  ...
})

Configuration

refreshTokenUrl: url expecting POST request for refreshing tokens (default: "/api/refresh")
apiBaseUrl: default API url. For calling Nuxt 3 server api routes leave it blank, otherwise put an absolute server url, eg: http://test.com/api (default: blank).
It sets the baseURL to the useFetch as well when the useCookiesAuth is called.
redirectOnRefreshTokenExpiration: redirect or not to the redirectTo path when the api returns 401 response for the refresh token request (default: true)
redirectTo: path where the app will be redirected when the api returns 401 response for refresh token request (default: /login)

# More detailed example of configuration

That's it! You can now use useCookiesAuth in your Nuxt app ✨

Usage

// use spread operator for useCookiesAuth composable and useFetch options:
const { data, error } = await useFetch("/api/data", {
  ...useCookiesAuth()
})

// with body or other parameters:
const { data, error } = await useFetch("/api/data", {
  ...useCookiesAuth(),
  method: "POST",
  query: {
    id: 7
  },
  body: {
    message: "Hello!"
  }
})

Usage with middleware

useCookiesAuth internally needs to know from what route the request has been made for redirecting in case of 401 response for refresh token request. But using useRoute in nuxt frontend middleware is causing:

[nuxt] Calling `useRoute` within middleware may lead to misleading results. Instead, use the (to, from) arguments passed to the middleware to access the new and old routes.

For such case there us an useCookiesAuth overload where you can pass a path from the middleware from parameter to bypass this.

export default defineNuxtRouteMiddleware(async (to, from) => {
  ...
  const { data } = useFetch<User>("/api/data", {
    ...useCookiesAuth(from.path)
  })
  ...
  return
})

Example

Configuration

When you have api url http://test.com/api/v1/auth/refresh for refreshing token and http://test.com/api/v1/users for getting list of users, set:

apiBaseUrl: "http://test.com/api/v1"
refreshTokeUrl: "/auth/refresh"
and call useFetch("/users", { ...useCookiesAuth() }).

Backend

For an authorization with tokens in cookies there are only two routes needed:

login
refresh

Login sets two cookies. First with the access token with shorter expiration and second refresh token with a longer expiration.
You can check the Nuxt 3 server api login route.
Second route for refreshing token just checks the refresh token and when it is correct it sends back a new pair of access and refresh token. This is the route that must be set to the refreshTokenUrl configuration field in nuxt.config.ts.

Development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release