Nuxt X Neon Auth

A reusable Nuxt layer providing comprehensive authentication functionality with Neon Auth integration.

Features

• 🔐 Multiple Auth Methods: Email/Password, OAuth, Magic Link, OTP
• 🎨 Pre-built Components: Login, Signup, Password Reset forms using Nuxt UI v4
• 🧩 Composables: useXAuth, useXNeonAuth for easy integration
• ⚙️ Configurable: Customizable redirects and feature toggles
• 🎯 TypeScript: Full TypeScript support with type definitions
• 🎨 Styled: Beautiful UI components with Nuxt UI v4 and Tailwind CSS v4

Installation

npm install @xenterprises/nuxt-x-neon-auth

Add to your nuxt.config.ts:

export default defineNuxtConfig({
  extends: ["@xenterprises/nuxt-x-neon-auth"],
});

Configuration

Configure the layer in your app.config.ts:

export default defineAppConfig({
  xAuth: {
    redirects: {
      login: "/auth/login",
      signup: "/auth/signup",
      afterLogin: "/",
      afterSignup: "/",
      afterLogout: "/auth/login",
    },
    features: {
      oauth: false,
      magicLink: false,
      otp: false,
      forgotPassword: true,
    },
    socialLoginProviders: ["google", "github"], // Optional - see supported providers below
  },
});

Supported OAuth Providers

This layer supports 30+ OAuth providers through Better Auth:

Most Popular:

• google, github, apple, microsoft, facebook, twitter, linkedin, discord

Developer Tools:

• gitlab, figma, linear, notion, vercel

Social & Entertainment:

• spotify, twitch, reddit, tiktok, kick

Enterprise:

• atlassian, salesforce, cognito, slack

Regional & Other:

• kakao, line, naver, vk, zoom, dropbox, huggingface, paypal, polar, roblox, paybin

For providers not listed or custom OAuth providers, use the Generic OAuth Plugin.

Environment Variables

Required Neon Auth configuration:

NUXT_PUBLIC_NEON_AUTH_URL=https://your-project.neonauth.xxx.neon.tech/your-db/auth

Usage

Basic Authentication

<script setup lang="ts">
const { login, signup, logout, user, isLoading, isAuthenticated } = useXAuth();

// Login with email/password
const handleLogin = async () => {
  const result = await login("[email protected]", "password123");
  if (result.status === "ok") {
    console.log("Logged in successfully!");
  }
};

// Signup
const handleSignup = async () => {
  const result = await signup("[email protected]", "password123");
  if (result.status === "ok") {
    console.log("Account created!");
  }
};

// Logout
const handleLogout = async () => {
  await logout();
};

// Check authentication status
watchEffect(() => {
  if (isAuthenticated.value) {
    console.log("User is logged in:", user.value);
  }
});
</script>

<template>
  <div>
    <div v-if="isLoading">Loading...</div>
    <div v-else-if="isAuthenticated">
      <p>Welcome, {{ user?.email }}!</p>
      <UButton @click="handleLogout">Logout</UButton>
    </div>
    <div v-else>
      <UButton @click="handleLogin">Login</UButton>
    </div>
  </div>
</template>

OAuth Authentication

<script setup lang="ts">
const { loginWithProvider } = useXAuth();

const handleGoogleLogin = async () => {
  await loginWithProvider("google");
};
</script>

<template>
  <UButton @click="handleGoogleLogin"> Sign in with Google </UButton>
</template>

Magic Link

<script setup lang="ts">
const { sendMagicLink } = useXAuth();

const handleMagicLink = async (email: string) => {
  const result = await sendMagicLink(email);
  if (result.status === "ok") {
    console.log("Magic link sent to", email);
  }
};
</script>

Available Pages

The layer provides these auth pages automatically:

• /auth/login - Login form
• /auth/signup - Signup form
• /auth/forgot-password - Password reset
• /auth/magic-link - Magic link authentication
• /auth/otp - OTP verification
• /auth/logout - Logout handler

Available Components

<template>
  <!-- Use the auth components directly -->
  <XAuthLogin />
  <XAuthSignup />
  <XAuthForgotPassword />
  <XAuthMagicLink />
  <XAuthOtp />
  <XAuthOAuthButton provider="google" />
  <XAuthOAuthButtonGroup />
  <XAuthErrorBoundary :error="errorMessage" @retry="handleRetry" />
</template>

TypeScript Support

import type {
  XAuthConfig,
  OAuthProvider,
  AuthResponse,
} from "@xenterprises/nuxt-x-neon-auth/types";

// Type-safe configuration
const authConfig: XAuthConfig = {
  features: {
    oauth: true,
    magicLink: false,
  },
  socialLoginProviders: ["google", "github"] as OAuthProvider[],
};

// Type-safe auth responses
const handleLogin = async (
  email: string,
  password: string,
): Promise<AuthResponse> => {
  const { login } = useXAuth();
  return await login(email, password);
};

Composables

useXAuth()

Main authentication composable with simplified interface:

const {
  // State
  user,
  isLoading,
  isAuthenticated,

  // Methods
  login,
  signup,
  logout,
  forgotPassword,
  loginWithProvider,
  sendOtp,
  verifyOtp,
  sendMagicLink,
} = useXAuth();

useXNeonAuth()

Lower-level Neon Auth integration:

const {
  authClient,
  currentUser,
  signInWithCredential,
  signUpWithCredential,
  signOut,
  signInWithOAuth,
  sendOtpCode,
  verifyOtpCode,
  sendMagicLinkEmail,
  verifyMagicLink,
  sendForgotPasswordEmail,
} = useXNeonAuth();

Security Best Practices

Environment Variables

• Never commit .env files to version control
• Use different Neon Auth URLs for development, staging, and production
• Rotate credentials regularly

HTTPS

• Always use HTTPS in production
• Ensure your Neon Auth URL uses HTTPS

Password Requirements

The layer uses Zod validation. You can customize password requirements in your consuming app:

import { z } from "zod";

const passwordSchema = z
  .string()
  .min(12, "Password must be at least 12 characters")
  .regex(/[A-Z]/, "Password must contain uppercase letter")
  .regex(/[a-z]/, "Password must contain lowercase letter")
  .regex(/[0-9]/, "Password must contain number")
  .regex(/[^A-Za-z0-9]/, "Password must contain special character");

Session Management

• Sessions are managed by Neon Auth
• Configure session timeout in your Neon Auth dashboard
• Implement proper logout on all devices if needed

Development

The .playground directory contains a test application for developing the layer:

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

Publishing

# Update version in package.json
npm version patch|minor|major

# Publish to npm
npm publish --access public

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © X Enterprises

See LICENSE for more information.