[ PROMPT_NODE_23573 ]
Auth Methods
[ SKILL_DOCUMENTATION ]
# Neon Auth - Auth Methods Reference
Complete reference for authentication methods, session management, and error handling.
## Auth Methods
### Sign Up
```typescript
await auth.signUp.email({
email: "[email protected]",
password: "securepassword",
name: "John Doe", // Optional
});
```
### Sign In
```typescript
// Email/password
await auth.signIn.email({
email: "[email protected]",
password: "securepassword",
});
// Social (Google, GitHub)
await auth.signIn.social({
provider: "google", // or "github"
callbackURL: "/dashboard",
});
```
### Sign Out
```typescript
await auth.signOut();
```
### Get Session
```typescript
// Async (Node.js, server components)
const session = await auth.getSession();
// React hook (client components)
const session = auth.useSession();
// Returns: { data: Session | null, isPending: boolean }
```
## Session Data Structure
```typescript
interface Session {
user: {
id: string;
name: string | null;
email: string;
image: string | null;
emailVerified: boolean;
createdAt: Date;
updatedAt: Date;
};
session: {
id: string;
expiresAt: Date;
token: string;
createdAt: Date;
updatedAt: Date;
userId: string;
};
}
```
## Error Handling
```typescript
const { error } = await auth.signIn.email({ email, password });
if (error) {
switch (error.code) {
case "INVALID_EMAIL_OR_PASSWORD":
showError("Invalid email or password");
break;
case "EMAIL_NOT_VERIFIED":
showError("Please verify your email");
break;
case "USER_NOT_FOUND":
showError("User not found");
break;
case "TOO_MANY_REQUESTS":
showError("Too many attempts. Please wait.");
break;
default:
showError("Authentication failed");
}
}
```
## Building Auth Pages
### Use AuthView (Recommended for React Apps)
For authentication pages, use the pre-built `AuthView` component instead of building custom forms.
**What AuthView provides:**
- Sign-in, sign-up, password reset, magic link pages
- Social providers (Google, GitHub) - requires TWO configurations: enable in Neon Console AND add `social` prop to NeonAuthUIProvider
- Form validation, error handling, loading states
- Consistent styling via CSS variables
**Setup (Next.js App Router):**
1. **Import CSS** (in `app/layout.tsx` or `app/globals.css`):
```tsx
import "@neondatabase/auth/ui/css";
```
2. **Wrap app with provider** (create `app/auth-provider.tsx`):
```tsx
"use client";
import { NeonAuthUIProvider } from "@neondatabase/auth/react/ui";
import { authClient } from "@/lib/auth/client";
import { useRouter } from "next/navigation";
import Link from "next/link";
export function AuthProvider({ children }: { children: React.ReactNode }) {
const router = useRouter();
return (
router.refresh()}
Link={Link}
>
{children}
);
}
```
3. **Create auth page** (`app/auth/[path]/page.tsx`):
```tsx
import { AuthView } from "@neondatabase/auth/react/ui";
import { authViewPaths } from "@neondatabase/auth/react/ui/server";
export function generateStaticParams() {
return Object.values(authViewPaths).map((path) => ({ path }));
}
export default async function AuthPage({
params,
}: {
params: Promise;
}) {
const { path } = await params;
return ;
}
```
**Result:** You now have `/auth/sign-in`, `/auth/sign-up`, `/auth/forgot-password`, etc.
**Available paths:** `"sign-in"`, `"sign-up"`, `"forgot-password"`, `"reset-password"`, `"magic-link"`, `"two-factor"`, `"callback"`, `"sign-out"`
### When to Use Low-Level Methods Instead
Use `authClient.signIn.email()`, `authClient.signUp.email()` directly if:
- **Node.js backend** - No React, server-side auth only
- **Custom design system** - Your design team provides form components
- **Mobile/CLI apps** - Non-web frontends
- **Headless auth** - Testing or non-standard flows
For standard React web apps, **use AuthView**.
### Common Anti-Pattern
```tsx
// ❌ Don't build custom forms unless you have specific requirements
function CustomSignInPage() {
const [email, setEmail] = useState("");
const [password, setPassword] = useState("");
const [error, setError] = useState("");
const [loading, setLoading] = useState(false);
const handleSubmit = async (e) => {
e.preventDefault();
setLoading(true);
const { error } = await authClient.signIn.email({ email, password });
if (error) setError(error.message);
setLoading(false);
};
// ... 50+ more lines of form JSX, validation, error display
}
// ✅ Use AuthView instead - one component handles everything
;
```
## Styling
Neon Auth UI **automatically inherits your app's existing theme**. If you have CSS variables like `--primary`, `--background`, etc. defined (from Tailwind, shadcn/ui, or custom CSS), auth components use them with no configuration.
**Key features:**
- **Automatic inheritance**: Uses your existing `--primary`, `--background`, etc.
- **No conflicts**: Auth styles are in `@layer neon-auth`, so your styles always win
- **Import order doesn't matter**: CSS layers handle priority automatically
### Integration with shadcn/ui
If you use shadcn/ui or similar libraries that define `--primary`, `--background`, etc., Neon Auth will automatically inherit those colors. No additional configuration needed.
### Use Existing CSS Variables
When creating custom components, use CSS variables for consistency:
| Variable | Purpose |
| ----------------------------------- | ----------------------- |
| `--background`, `--foreground` | Page background/text |
| `--card`, `--card-foreground` | Card surfaces |
| `--primary`, `--primary-foreground` | Primary buttons/actions |
| `--muted`, `--muted-foreground` | Muted/subtle elements |
| `--border`, `--ring` | Borders and focus rings |
| `--radius` | Border radius |
### Auth-Specific Customization
To customize auth components differently from your main app, use `--neon-*` prefix:
```css
:root {
--primary: oklch(0.55 0.25 250); /* Your app's blue */
--neon-primary: oklch(0.55 0.18 145); /* Auth uses green */
}
```
Source: claude-code-templates (MIT). See About Us for full credits.