{"id":28465,"library":"winx-auth","title":"Winx Auth","description":"Nuxt 3 authentication module that provides login, logout, CSRF protection, token management, and global authentication middleware. Version 3.2.1 is the current stable release. It integrates with Nuxt 3's composition API via the `useAuth` composable and supports secure cookie-based tokens with configurable CSRF protection. Key differentiators include built-in CSRF encryption, global middleware options, and automatic token/cookie management with production-like security defaults. Released under the MIT license.","status":"active","version":"3.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/Winx-Universe/winx-auth","tags":["javascript"],"install":[{"cmd":"npm install winx-auth","lang":"bash","label":"npm"},{"cmd":"yarn add winx-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add winx-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency required as the module is built for Nuxt 3","package":"nuxt","optional":false}],"imports":[{"note":"useAuth is auto-imported by Nuxt via '#imports'; no manual import needed from the package.","wrong":"import { useAuth } from 'winx-auth'","symbol":"useAuth","correct":"const { login, logout } = useAuth()"},{"note":"Module name is 'winx-auth' as a string in the modules array, not 'auth' or 'winx-auth-module'.","wrong":"modules: ['winx-auth-module']","symbol":"auth module","correct":"modules: ['winx-auth']"},{"note":"Configuration is placed under the 'auth' key in nuxt.config.ts, not under a custom key.","wrong":"winxAuth: { ... }","symbol":"auth config","correct":"auth: { enabled: true }"},{"note":"The global $auth helper provides login/logout methods; method names are 'login' and 'logout'.","wrong":"$auth.signIn({ code })","symbol":"$auth","correct":"$auth.login({ code })"}],"quickstart":{"code":"// nuxt.config.ts\nexport default defineNuxtConfig({\n  modules: ['winx-auth'],\n  auth: {\n    apiUrl: process.env.API_URL || 'http://localhost:8080',\n    enableGlobalAppMiddleware: true,\n  },\n});\n\n// pages/login.vue\n<script setup lang=\"ts\">\nconst code = ref('');\nconst { login } = useAuth();\n\nconst handleLogin = async () => {\n  await login({ code: code.value });\n};\n</script>\n\n<template>\n  <input v-model=\"code\" type=\"text\" />\n  <button @click=\"handleLogin\">Login</button>\n</template>","lang":"typescript","description":"Demonstrates basic setup with Nuxt config and a login page using the useAuth composable."},"warnings":[{"fix":"Ensure useAuth() is called within <script setup> or directly in a Vue component's setup() function.","message":"useAuth() must be called inside a component's setup function or within Nuxt's auto-import context. Using it outside setup (e.g., in a plain function) may result in errors.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Set enableGlobalAppMiddleware: false in auth config, or use allow404WithoutAuth: true to allow 404 pages.","message":"The global middleware enforces authentication on all routes by default. Public pages will be blocked unless configured correctly.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Use pnpm add winx-auth (version 3.x) instead of the old package.","message":"The 'auth-module' package name was used in older versions. Do not confuse 'winx-auth' with 'auth-module'.","severity":"deprecated","affected_versions":"<3.0.0"},{"fix":"Set secure: false in development or use HTTPS locally (e.g., via mkcert).","message":"Cookie options httpOnly and secure default to true in production, which may cause issues if testing over HTTP locally.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Use randomBytes(22).toString('base64') (as shown in default config) or a secure environment variable.","message":"The CSRF encryptSecret should be a secure, randomly generated string. Using a static or weak secret compromises security.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Move the call into a Vue component's <script setup> block or use #imports auto-import.","cause":"useAuth() returned undefined because it was called outside Nuxt's component context (e.g., in a plain .ts file).","error":"Cannot read properties of undefined (reading 'login')"},{"fix":"Run 'npm install winx-auth' (or pnpm/yarn) and ensure nuxt.config.ts has modules: ['winx-auth'].","cause":"Package not installed or not added to modules array correctly.","error":"Module 'winx-auth' not found"},{"fix":"Set enableGlobalAppMiddleware: false or exclude the login route in middleware options using globalMiddlewareOptions.allow404WithoutAuth or custom middleware.","cause":"Global app middleware redirects to login page which itself requires auth, causing infinite loop.","error":"Auth middleware redirect loop"},{"fix":"Check that token.name matches what the API expects, and that cookie options are consistent (httpOnly/secure).","cause":"Login API endpoint returned a token but cookie options (httpOnly, secure) may be misconfigured or the token name changed.","error":"Cookie with name 'token.winx' not set"},{"fix":"Ensure encryptSecret in nuxt.config matches the secret used to generate the CSRF token on the server side.","cause":"The CSRF cookie and header values do not match, often due to misconfigured encryptSecret or different encryptAlgorithm.","error":"CSRF token mismatch"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}