Nuxt Auth Auto Refresh

1.0.2 · active · verified Wed Apr 22

The `nuxt-auth-auto-refresh` package provides automatic, periodic token refreshing for applications using the Nuxt Auth Module v5 (`@nuxtjs/auth-next`). Unlike the default Nuxt Auth v5 behavior, which only refreshes tokens immediately before API requests, this module actively monitors token expiration in the background. It polls every 500ms and triggers a refresh if a token is nearing its expiration (specifically, past 75% of its lifetime but not fully expired). This prevents users from being logged out unexpectedly during long sessions without API interaction or when tokens have very short lifespans. The current stable version is 1.0.2. Its release cadence is tied to the Nuxt Auth Module v5, which the README notes is not yet considered stable itself. This module differentiates by proactively managing token validity, enhancing user experience in specific scenarios.

Common errors

```
Auth plugin 'node_modules/nuxt-auth-auto-refresh/dist/index.js' could not be loaded.
```
cause Incorrect path specified for the plugin in `nuxt.config.js` or the `nuxt-auth-auto-refresh` package was not properly installed.

fix Verify that `nuxt-auth-auto-refresh` is installed in `node_modules` and the `src` path in `auth.plugins` is exactly `node_modules/nuxt-auth-auto-refresh/dist/index.js`.
```
Token is not refreshing periodically; the user gets logged out after some time even with the plugin active.
```
cause The Nuxt Auth Module v5 might not be correctly configured with a `refreshToken` endpoint, or the `exp` claim in the access token is missing/incorrect, preventing the plugin from accurately calculating expiry.

fix Ensure your Nuxt Auth strategy includes a `refreshToken` endpoint and that your access tokens correctly contain `exp` (expiration) and `iat` (issued at) claims for the plugin to function as expected.

Warnings

breaking This module is explicitly built for Nuxt Auth Module v5. Breaking changes in Nuxt Auth v5 itself, or its eventual deprecation, will directly impact the functionality and viability of this auto-refresh plugin.
Fix: Regularly check the compatibility of `nuxt-auth-auto-refresh` with new versions of `@nuxtjs/auth-next`. Be prepared for potential refactoring if underlying Nuxt Auth APIs change significantly.
gotcha The README explicitly states 'v5 is not considered stable yet, use with caution.' This warning applies indirectly to `nuxt-auth-auto-refresh` as its stability is contingent upon the stability of its dependency.
Fix: Thoroughly test token refresh functionality in production-like environments before relying on it, especially in critical applications with high uptime requirements.
gotcha The plugin works by periodically checking token expiration and calling the internal `refreshTokens()` function of the Auth Module. If this internal API changes or is removed in future Nuxt Auth v5 updates, this plugin will break.
Fix: Monitor `@nuxtjs/auth-next` updates for changes to internal token refresh mechanisms. If significant internal changes occur without official support, consider contributing to `@nuxtjs/auth-next` or forking this module for adaptation.

Install

npm install nuxt-auth-auto-refresh npm
yarn add nuxt-auth-auto-refresh yarn
pnpm add nuxt-auth-auto-refresh pnpm

Imports

Plugin configuration path
wrong:
```
import nuxtAuthAutoRefresh from 'nuxt-auth-auto-refresh'
```
correct:
```
plugins: [{ src: "node_modules/nuxt-auth-auto-refresh/dist/index.js", ssr: false }]
```
This module is consumed as a Nuxt Auth plugin by specifying its distribution path within the `auth.plugins` array in `nuxt.config.js`. It does not expose traditional ES module symbols for direct import.

Quickstart

This configuration snippet demonstrates how to integrate `nuxt-auth-auto-refresh` into your `nuxt.config.js` by adding its distribution path to the `auth.plugins` array. This setup enables periodic token refreshes for your Nuxt Auth v5 application, preventing premature user logouts.

// nuxt.config.js
export default {
  buildModules: [
    // Ensure @nuxtjs/auth-next is installed and configured
    '@nuxtjs/auth-next',
  ],
  auth: {
    strategies: {
      // Example strategy - replace with your actual strategy
      local: {
        token: {
          property: 'token',
          global: true,
          required: true,
          type: 'Bearer'
        },
        user: {
          property: 'user',
          autoFetch: true
        },
        endpoints: {
          login: { url: '/api/auth/login', method: 'post' },
          logout: { url: '/api/auth/logout', method: 'post' },
          user: { url: '/api/auth/user', method: 'get' }
        }
      }
    },
    redirect: {
      login: '/login',
      logout: '/login',
      home: '/',
      callback: '/login'
    },
    plugins: [
      // Add the auto-refresh plugin here
      { src: 'node_modules/nuxt-auth-auto-refresh/dist/index.js', ssr: false }
    ]
  },
  // ... other nuxt config
}

view raw JSON →