nuxt-v-auth-stack

A Nuxt layer providing complete authentication functionality powered by Stack Auth.

Features

• Email/password authentication (sign in, sign up, password reset)
• OAuth authentication (Google, GitHub, Microsoft, Facebook)
• Email verification
• Profile management
• Dark/light mode toggle
• Route protection middleware
• Configurable signup (enable/disable)
• Configurable OAuth providers

Installation

Extend this layer in your Nuxt app:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['nuxt-v-auth-stack'],
})

Configuration

Configure Stack Auth credentials via runtime config:

// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['nuxt-v-auth-stack'],

  runtimeConfig: {
    public: {
      stackAuth: {
        projectId: '', // Your Stack Auth project ID
        publishableClientKey: '', // Your publishable client key
        baseUrl: 'https://api.stack-auth.com', // Optional: custom API URL
        signupEnabled: true, // Set to false to disable registration
        oauthProviders: ['google', 'github', 'microsoft'], // Available OAuth providers
      },
    },
  },
})

Or use environment variables:

NUXT_PUBLIC_STACK_AUTH_PROJECT_ID=your-project-id
NUXT_PUBLIC_STACK_AUTH_PUBLISHABLE_CLIENT_KEY=your-client-key

Pages Provided

| Path | Description | |------|-------------| | /auth/login | Sign in with email/password or OAuth | | /auth/register | Create new account | | /auth/forgot-password | Request password reset email | | /auth/reset-password | Set new password (from email link) | | /auth/verify | Email verification | | /auth/callback | OAuth callback handler | | /settings | Profile settings with dark mode toggle |

Route Protection

All routes are protected by default. To make a route public:

<script setup lang="ts">
definePageMeta({
  auth: false
})
</script>

Composables

useAuth()

The primary composable for authentication:

const {
  // State
  user,              // Current user object
  isAuthenticated,   // Boolean - is user logged in
  isLoading,         // Boolean - auth state loading

  // User getters
  userId,            // User ID
  userEmail,         // User's email
  userDisplayName,   // Display name or email prefix
  userAvatar,        // Profile image URL
  isEmailVerified,   // Email verification status

  // Config
  signupEnabled,     // Is registration enabled
  oauthProviders,    // Available OAuth providers

  // Auth methods
  signIn,            // (email, password) => Promise
  signUp,            // (email, password) => Promise
  signOut,           // (redirectTo?) => Promise
  signInWithOAuth,   // (provider) => void
  handleOAuthCallback, // (code) => Promise
  refreshToken,      // () => Promise<boolean>
  fetchCurrentUser,  // () => Promise<User | null>
  initialize,        // () => Promise<void>

  // Profile methods
  updateProfile,     // (data) => Promise
  sendVerificationEmail, // (callbackUrl?) => Promise
  verifyEmail,       // (code) => Promise
} = useAuth()

Example Usage

<script setup lang="ts">
const { user, isAuthenticated, signOut } = useAuth()
</script>

<template>
  <div v-if="isAuthenticated">
    <p>Welcome, {{ user?.displayName }}</p>
    <button @click="signOut()">Sign Out</button>
  </div>
</template>

Middleware

auth (global)

Applied globally - protects all routes except:

• /auth/* pages
• Routes with definePageMeta({ auth: false })

guest

For pages that should only be accessible to non-authenticated users:

<script setup lang="ts">
definePageMeta({
  middleware: 'guest'
})
</script>

Token Storage

Authentication tokens are stored in secure cookies:

• stack_auth_access - Access token (7-day expiry)
• stack_auth_refresh - Refresh token (7-day expiry)

Cookie options:

• secure: true - HTTPS only in production
• sameSite: 'lax' - CSRF protection
• maxAge: 604800 - 7 days

Layouts

auth

Minimal layout for authentication pages. Applied automatically to /auth/* routes.

Customization

Override Pages

Create your own version of any auth page in your consuming app:

app/
  pages/
    auth/
      login.vue  # Your custom login page

Custom Styles

Add auth-specific styles in the layer's CSS file:

/* app/assets/css/auth.css */

Types

interface StackAuthUser {
  id: string
  primaryEmail: string | null
  primaryEmailVerified: boolean
  displayName: string | null
  profileImageUrl: string | null
  // ... see types/stack-auth.ts for full definition
}

interface StackAuthConfig {
  projectId: string
  publishableClientKey: string
  baseUrl?: string
  signupEnabled?: boolean
  oauthProviders?: ('google' | 'github' | 'microsoft' | 'facebook')[]
}

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm run test

License

MIT