{"id":24954869,"url":"https://github.com/drunomics/nuxt-auth-utils","last_synced_at":"2026-07-06T00:32:15.305Z","repository":{"id":273290950,"uuid":"917636416","full_name":"drunomics/nuxt-auth-utils","owner":"drunomics","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-16T11:23:11.000Z","size":1625,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"feature/server-handler-config-build","last_synced_at":"2026-02-04T08:19:59.557Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drunomics.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-16T11:14:03.000Z","updated_at":"2025-01-16T11:21:44.000Z","dependencies_parsed_at":"2025-01-20T03:04:03.469Z","dependency_job_id":"dc45941a-20cd-4d47-b849-762518703428","html_url":"https://github.com/drunomics/nuxt-auth-utils","commit_stats":null,"previous_names":["drunomics/nuxt-auth-utils"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/drunomics/nuxt-auth-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drunomics%2Fnuxt-auth-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drunomics%2Fnuxt-auth-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drunomics%2Fnuxt-auth-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drunomics%2Fnuxt-auth-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drunomics","download_url":"https://codeload.github.com/drunomics/nuxt-auth-utils/tar.gz/refs/heads/feature/server-handler-config-build","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drunomics%2Fnuxt-auth-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35174071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-03T05:13:29.704Z","updated_at":"2026-07-06T00:32:15.239Z","avatar_url":"https://github.com/drunomics.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nuxt Auth Utils\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![License][license-src]][license-href]\n[![Nuxt][nuxt-src]][nuxt-href]\n\nMinimalist Authentication module for Nuxt exposing Vue composables and server utils.\n\n- [Release Notes](/CHANGELOG.md)\n- [Demo](https://github.com/atinux/nuxt-todos-edge)\n\u003c!-- - [🏀 Online playground](https://stackblitz.com/github/your-org/nuxt-auth-utils?file=playground%2Fapp.vue) --\u003e\n\u003c!-- - [📖 \u0026nbsp;Documentation](https://example.com) --\u003e\n\n## Features\n\n- Secured \u0026 sealed cookies sessions\n- [OAuth Providers](#supported-oauth-providers)\n\n## Requirements\n\nThis module only works with SSR (server-side rendering) enabled as it uses server API routes. You cannot use this module with `nuxt generate`.\n\n## Quick Setup\n\n1. Add `nuxt-auth-utils` dependency to your project\n\n```bash\n# Using pnpm\npnpm add -D nuxt-auth-utils\n\n# Using yarn\nyarn add --dev nuxt-auth-utils\n\n# Using npm\nnpm install --save-dev nuxt-auth-utils\n```\n\n2. Add `nuxt-auth-utils` to the `modules` section of `nuxt.config.ts`\n\n```js\nexport default defineNuxtConfig({\n  modules: [\n    'nuxt-auth-utils'\n  ]\n})\n```\n\n3. Add a `NUXT_SESSION_PASSWORD` env variable with at least 32 characters in the `.env`.\n\n```bash\n# .env\nNUXT_SESSION_PASSWORD=password-with-at-least-32-characters\n```\n\nNuxt Auth Utils can generate one for you when running Nuxt in development the first time when no `NUXT_SESSION_PASSWORD` is set.\n\n4. That's it! You can now add authentication to your Nuxt app ✨\n\n## Module Options\n\n### serverHandler (optional)\nDefine custom server handler endpoints. Makes it possible to use your own custom server handler endpoints for fetching and deleting a session.\n\n```js\nexport default defineNuxtConfig({\n  runtimeConfig: {\n    public: {\n      auth: {\n        serverHandler: {\n          getSession: {\n            route: '/api/custom/auth/session',\n            method: 'get'\n          },\n          deleteSession: {\n            route: '/api/custom/auth/session',\n            method: 'delete'\n          },\n        }\n      }\n    }\n  }\n})\n```\n\n## Vue Composables\n\nNuxt Auth Utils automatically adds some plugins to fetch the current user session to let you access it from your Vue components.\n\n### User Session\n\n```vue\n\u003cscript setup\u003e\nconst { loggedIn, user, session, clear } = useUserSession()\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cdiv v-if=\"loggedIn\"\u003e\n    \u003ch1\u003eWelcome {{ user.login }}!\u003c/h1\u003e\n    \u003cp\u003eLogged in since {{ session.loggedInAt }}\u003c/p\u003e\n    \u003cbutton @click=\"clear\"\u003eLogout\u003c/button\u003e\n  \u003c/div\u003e\n  \u003cdiv v-else\u003e\n    \u003ch1\u003eNot logged in\u003c/h1\u003e\n    \u003ca href=\"/api/auth/github\"\u003eLogin with GitHub\u003c/a\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n```\n\n## Server Utils\n\nThe following helpers are auto-imported in your `server/` directory.\n\n### Session Management\n\n```ts\n// Set a user session, note that this data is encrypted in the cookie but can be decrypted with an API call\n// Only store the data that allow you to recognize an user, but do not store sensitive data\nawait setUserSession(event, {\n  user: {\n    // ... user data\n  },\n  loggedInAt: new Date()\n  // Any extra fields\n})\n\n// Get the current user session\nconst session = await getUserSession(event)\n\n// Clear the current user session\nawait clearUserSession(event)\n\n// Require a user session (send back 401 if no `user` key in session)\nconst session = await requireUserSession(event)\n```\n\nYou can define the type for your user session by creating a type declaration file (for example, `auth.d.ts`) in your project to augment the `UserSession` type:\n\n```ts\ndeclare module '#auth-utils' {\n  interface UserSession {\n    // define the type here\n  }\n}\nexport {}\n```\n\n### OAuth Event Handlers\n\nAll helpers are exposed from the `oauth` global variable and can be used in your server routes or API routes.\n\nThe pattern is `oauth.\u003cprovider\u003eEventHandler({ onSuccess, config?, onError? })`, example: `oauth.githubEventHandler`.\n\nThe helper returns an event handler that automatically redirects to the provider authorization page and then call `onSuccess` or `onError` depending on the result.\n\nThe `config` can be defined directly from the `runtimeConfig` in your `nuxt.config.ts`:\n\n```ts\nexport default defineNuxtConfig({\n  runtimeConfig: {\n    oauth: {\n      \u003cprovider\u003e: {\n        clientId: '...',\n        clientSecret: '...'\n      }\n    }\n  }\n})\n```\n\nIt can also be set using environment variables:\n\n- `NUXT_OAUTH_\u003cPROVIDER\u003e_CLIENT_ID`\n- `NUXT_OAUTH_\u003cPROVIDER\u003e_CLIENT_SECRET`\n\n#### Supported OAuth Providers\n\n- Auth0\n- AWS Cognito\n- Battle.net\n- Discord\n- GitHub\n- Google\n- Keycloak\n- LinkedIn\n- Microsoft\n- Spotify\n- Twitch\n\nYou can add your favorite provider by creating a new file in [src/runtime/server/lib/oauth/](./src/runtime/server/lib/oauth/).\n\n### Example\n\nExample: `~/server/routes/auth/github.get.ts`\n\n```ts\nexport default oauth.githubEventHandler({\n  config: {\n    emailRequired: true\n  },\n  async onSuccess(event, { user, tokens }) {\n    await setUserSession(event, {\n      user: {\n        githubId: user.id\n      }\n    })\n    return sendRedirect(event, '/')\n  },\n  // Optional, will return a json error and 401 status code by default\n  onError(event, error) {\n    console.error('GitHub OAuth error:', error)\n    return sendRedirect(event, '/')\n  },\n})\n```\n\nMake sure to set the callback URL in your OAuth app settings as `\u003cyour-domain\u003e/auth/github`.\n\n### Extend Session\n\nWe leverage hooks to let you extend the session data with your own data or to log when the user clear its session.\n\n```ts\n// server/plugins/session.ts\nexport default defineNitroPlugin(() =\u003e {\n  // Called when the session is fetched during SSR for the Vue composable (/api/_auth/session)\n  // Or when we call useUserSession().fetch()\n  sessionHooks.hook('fetch', async (session, event) =\u003e {\n    // extend User Session by calling your database\n    // or\n    // throw createError({ ... }) if session is invalid for example\n  })\n\n  // Called when we call useServerSession().clear() or clearUserSession(event)\n  sessionHooks.hook('clear', async (session, event) =\u003e {\n    // Log that user logged out\n  })\n})\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Generate type stubs\nnpm run dev:prepare\n\n# Develop with the playground\nnpm run dev\n\n# Build the playground\nnpm run dev:build\n\n# Run ESLint\nnpm run lint\n\n# Run Vitest\nnpm run test\nnpm run test:watch\n\n# Release new version\nnpm run release\n```\n\n\u003c!-- Badges --\u003e\n[npm-version-src]: https://img.shields.io/npm/v/nuxt-auth-utils/latest.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\n[npm-version-href]: https://npmjs.com/package/nuxt-auth-utils\n\n[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-auth-utils.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\n[npm-downloads-href]: https://npmjs.com/package/nuxt-auth-utils\n\n[license-src]: https://img.shields.io/npm/l/nuxt-auth-utils.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\n[license-href]: https://npmjs.com/package/nuxt-auth-utils\n\n[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js\n[nuxt-href]: https://nuxt.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrunomics%2Fnuxt-auth-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrunomics%2Fnuxt-auth-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrunomics%2Fnuxt-auth-utils/lists"}