# Neon Auth/JS - Common Mistakes

Reference guide for common mistakes when using `@neondatabase/auth` or `@neondatabase/neon-js`.

## Table of Contents

- [Import Mistakes](#import-mistakes)
  - [BetterAuthReactAdapter Subpath Requirement](#betterauthreactadapter-subpath-requirement)
  - [Adapter Factory Functions](#adapter-factory-functions)
- [CSS Import Mistakes](#css-import-mistakes)
- [Configuration Mistakes](#configuration-mistakes)
  - [Wrong createAuthClient Signature](#wrong-createauthclient-signature)
  - [Missing Environment Variables](#missing-environment-variables)
- [Usage Mistakes](#usage-mistakes)
  - [Missing "use client" Directive](#missing-use-client-directive)
  - [Wrong API for Adapter](#wrong-api-for-adapter)

---

## Import Mistakes

### BetterAuthReactAdapter Subpath Requirement

`BetterAuthReactAdapter` is **NOT** exported from the main package entry. You must import it from the subpath.

**Wrong:**
```typescript
// These will NOT work
import { BetterAuthReactAdapter } from "@neondatabase/neon-js";
import { BetterAuthReactAdapter } from "@neondatabase/auth";
```

**Correct:**
```typescript
// For @neondatabase/neon-js
import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react/adapters";

// For @neondatabase/auth
import { BetterAuthReactAdapter } from "@neondatabase/auth/react/adapters";
```

**Why:** The React adapter has React-specific dependencies and is tree-shaken out of the main bundle. Using subpath exports keeps the main bundle smaller for non-React environments.

### Adapter Factory Functions

All adapters are **factory functions** that must be called with `()`.

**Wrong:**
```typescript
const client = createClient({
  auth: {
    adapter: BetterAuthReactAdapter,  // Missing ()
    url: process.env.NEON_AUTH_URL!,
  },
  dataApi: { url: process.env.NEON_DATA_API_URL! },
});
```

**Correct:**
```typescript
const client = createClient({
  auth: {
    adapter: BetterAuthReactAdapter(),  // Called as function
    url: process.env.NEON_AUTH_URL!,
  },
  dataApi: { url: process.env.NEON_DATA_API_URL! },
});
```

This applies to all adapters:
- `BetterAuthReactAdapter()`
- `BetterAuthVanillaAdapter()`
- `SupabaseAuthAdapter()`

---

## CSS Import Mistakes

Auth UI components require CSS. Choose **ONE** method based on your project.

### With Tailwind v4

```css
/* In app/globals.css */
@import 'tailwindcss';
@import '@neondatabase/neon-js/ui/tailwind';
/* Or: @import '@neondatabase/auth/ui/tailwind'; */
```

### Without Tailwind

```typescript
// In app/layout.tsx
import "@neondatabase/neon-js/ui/css";
// Or: import "@neondatabase/auth/ui/css";
```

### Never Import Both

**Wrong:**
```css
/* Causes ~94KB of duplicate styles */
@import '@neondatabase/neon-js/ui/css';
@import '@neondatabase/neon-js/ui/tailwind';
```

**Why:** The `ui/css` import includes pre-built CSS (~47KB). The `ui/tailwind` import provides Tailwind tokens (~2KB) that generate similar styles. Using both doubles your CSS bundle.

---

## Configuration Mistakes

### Wrong createAuthClient Signature

The `createAuthClient` function takes the URL as the first argument, not as a property in an options object.

**Wrong:**
```typescript
// This will NOT work
createAuthClient({ baseURL: url });
createAuthClient({ url: myUrl });
```

**Correct:**
```typescript
// Vanilla client - URL as first arg
createAuthClient(url);

// With adapter - URL as first arg, options as second
createAuthClient(url, { adapter: BetterAuthReactAdapter() });

// Next.js client - no arguments (uses env vars automatically)
import { createAuthClient } from "@neondatabase/auth/next";
const authClient = createAuthClient();
```

### Missing Environment Variables

**Required for Next.js:**
```bash
# .env.local
NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
NEXT_PUBLIC_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth

# For neon-js (auth + data)
NEON_DATA_API_URL=https://ep-xxx.apirest.c-2.us-east-2.aws.neon.build/dbname/rest/v1
```

**Required for Vite/React SPA:**
```bash
# .env
VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.c-2.us-east-2.aws.neon.build/dbname/auth
VITE_NEON_DATA_API_URL=https://ep-xxx.apirest.c-2.us-east-2.aws.neon.build/dbname/rest/v1
```

**Important:**
- `NEON_AUTH_BASE_URL` - Server-side auth
- `NEXT_PUBLIC_*` prefix - Required for client-side access in Next.js
- `VITE_*` prefix - Required for client-side access in Vite
- Restart dev server after adding env vars

---

## Usage Mistakes

### Missing "use client" Directive

Client components using `useSession()` need the `"use client"` directive.

**Wrong:**
```typescript
// Missing directive - will cause hydration errors
import { authClient } from "@/lib/auth/client";

function AuthStatus() {
  const session = authClient.useSession();
  // ...
}
```

**Correct:**
```typescript
"use client";

import { authClient } from "@/lib/auth/client";

function AuthStatus() {
  const session = authClient.useSession();
  // ...
}
```

### Wrong API for Adapter

Each adapter has its own API style. Don't mix them.

**Wrong - BetterAuth API with SupabaseAuthAdapter:**
```typescript
const client = createClient({
  auth: { adapter: SupabaseAuthAdapter(), url },
  dataApi: { url },
});

// This won't work with SupabaseAuthAdapter
await client.auth.signIn.email({ email, password });
```

**Correct - Supabase API with SupabaseAuthAdapter:**
```typescript
const client = createClient({
  auth: { adapter: SupabaseAuthAdapter(), url },
  dataApi: { url },
});

// Use Supabase-style methods
await client.auth.signInWithPassword({ email, password });
```

**API Reference by Adapter:**

| Adapter | Sign In | Sign Up | Get Session |
|---------|---------|---------|-------------|
| BetterAuthVanillaAdapter | `signIn.email({ email, password })` | `signUp.email({ email, password })` | `getSession()` |
| BetterAuthReactAdapter | `signIn.email({ email, password })` | `signUp.email({ email, password })` | `useSession()` / `getSession()` |
| SupabaseAuthAdapter | `signInWithPassword({ email, password })` | `signUp({ email, password })` | `getSession()` |

---

## Related Resources

- [Auth Adapters Guide](https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/references/neon-js-adapters.md) - Detailed adapter comparison
- [Import Reference](https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/references/neon-js-imports.md) - Complete import paths
- [Troubleshooting Guide](https://raw.githubusercontent.com/neondatabase-labs/ai-rules/main/references/neon-auth-troubleshooting.md) - Error solutions