Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nuxt-alt/auth/llms.txt

Use this file to discover all available pages before exploring further.

@nuxt-alt/auth is a drop-in alternative to @nuxtjs/auth built exclusively for Nuxt 3. It ships pluggable authentication schemes, eight pre-configured OAuth providers, SSR-aware token storage, and a first-class useAuth() composable — all with full TypeScript support.

Installation

Add the module to your Nuxt 3 project in a single step

Quickstart

Get up and running with your first authentication strategy

Schemes

Local, cookie, OAuth2, OpenID Connect, and refresh token schemes

Providers

Auth0, GitHub, Google, Discord, Laravel Sanctum, and more

Configuration

Full module options reference with defaults and examples

useAuth() Composable

Access authentication state and methods anywhere in your app

​
Why @nuxt-alt/auth?

@nuxt-alt/auth modernizes the familiar @nuxtjs/auth API for the Nuxt 3 ecosystem. It is built on top of @nuxt-alt/http (which wraps ofetch) and leverages Nuxt 3 primitives like useState, Nitro server handlers, and the auto-import system.

Multiple Schemes

Local, refresh, cookie, OAuth2, and OpenID Connect — choose the scheme that fits your backend

SSR Ready

Tokens and cookies sync correctly on the server so your pages render authenticated content

Flexible Storage

Cookies, localStorage, sessionStorage, Pinia, or Nuxt useState — fully configurable per project

​
Getting started

1

Install the package

Add @nuxt-alt/auth and its peer dependency to your project.
yarn add @nuxt-alt/auth @nuxt-alt/http
2

Register the module

Add @nuxt-alt/auth to the modules array in nuxt.config.ts.
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt-alt/auth'],
  auth: {
    strategies: {
      local: {
        token: {
          property: 'token',
        },
        endpoints: {
          login: { url: '/api/auth/login', method: 'post' },
          logout: { url: '/api/auth/logout', method: 'post' },
          user: { url: '/api/auth/user', method: 'get' },
        },
      },
    },
  },
})
3

Use the composable

Call useAuth() in any component or composable to access login, logout, and user state.
pages/login.vue
<script setup lang="ts">
const auth = useAuth()

async function login() {
  await auth.loginWith('local', {
    body: { email: 'user@example.com', password: 'secret' },
  })
}
</script>

<template>
  <button @click="login">Sign in</button>
</template>
4

Protect pages

Add definePageMeta to restrict access to authenticated users only.
pages/dashboard.vue
<script setup lang="ts">
definePageMeta({ auth: true })
</script>
@nuxt-alt/auth requires Nuxt 3 and has no backwards compatibility with Nuxt 2 or @nuxtjs/auth-next.

Build docs developers (and LLMs) love

Get started for freeTalk to us