{"id":16740,"library":"nuxt-auth-auto-refresh","title":"Nuxt Auth Auto Refresh","description":"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.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install nuxt-auth-auto-refresh","lang":"bash","label":"npm"},{"cmd":"yarn add nuxt-auth-auto-refresh","lang":"bash","label":"yarn"},{"cmd":"pnpm add nuxt-auth-auto-refresh","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This module is a plugin specifically designed to extend the functionality of the Nuxt Auth Module v5.","package":"@nuxtjs/auth-next","optional":false}],"imports":[{"note":"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.","wrong":"import nuxtAuthAutoRefresh from 'nuxt-auth-auto-refresh'","symbol":"Plugin configuration path","correct":"plugins: [{ src: \"node_modules/nuxt-auth-auto-refresh/dist/index.js\", ssr: false }]"}],"quickstart":{"code":"// nuxt.config.js\nexport default {\n  buildModules: [\n    // Ensure @nuxtjs/auth-next is installed and configured\n    '@nuxtjs/auth-next',\n  ],\n  auth: {\n    strategies: {\n      // Example strategy - replace with your actual strategy\n      local: {\n        token: {\n          property: 'token',\n          global: true,\n          required: true,\n          type: 'Bearer'\n        },\n        user: {\n          property: 'user',\n          autoFetch: true\n        },\n        endpoints: {\n          login: { url: '/api/auth/login', method: 'post' },\n          logout: { url: '/api/auth/logout', method: 'post' },\n          user: { url: '/api/auth/user', method: 'get' }\n        }\n      }\n    },\n    redirect: {\n      login: '/login',\n      logout: '/login',\n      home: '/',\n      callback: '/login'\n    },\n    plugins: [\n      // Add the auto-refresh plugin here\n      { src: 'node_modules/nuxt-auth-auto-refresh/dist/index.js', ssr: false }\n    ]\n  },\n  // ... other nuxt config\n}","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Thoroughly test token refresh functionality in production-like environments before relying on it, especially in critical applications with high uptime requirements.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`.","cause":"Incorrect path specified for the plugin in `nuxt.config.js` or the `nuxt-auth-auto-refresh` package was not properly installed.","error":"Auth plugin 'node_modules/nuxt-auth-auto-refresh/dist/index.js' could not be loaded."},{"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.","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.","error":"Token is not refreshing periodically; the user gets logged out after some time even with the plugin active."}],"ecosystem":"npm"}