@polymorphism-tech/morph-spec 7.0.0 → 7.1.0

package/framework/standards/backend/integrations/neon-auth/neon-auth.md

@@ -5,6 +5,10 @@
 > **Keywords:** neon auth, better auth, authentication, nextjs, user management, session, JWT
 > **Load When:** neon auth or authentication keywords detected
 
+**Verified against:** Neon Auth — @neondatabase/auth + @neondatabase/auth-ui (Better Auth). Last-verified: 2026-05-20.
+
+---
+
 Managed authentication powered by Better Auth, with all auth data stored directly in your Neon database (`neon_auth` schema). No external auth providers, no webhooks, no sync delays.
 
 ---
@@ -37,15 +41,23 @@ Neon Auth provides:
 ### Install Packages
 
 ```bash
-npm install @neondatabase/auth@latest
+# Core auth + UI components are separate packages
+npm install @neondatabase/auth@latest @neondatabase/auth-ui @neondatabase/serverless
 ```
 
+> The UI components (`AuthView`, `UserButton`, `SignedIn`, `SignedOut`,
+> `RedirectToSignIn`) live in `@neondatabase/auth-ui`, not in the core
+> `@neondatabase/auth` package. The legacy `@stackframe/stack` packages and
+> `@neondatabase/neon-auth-next` are deprecated — do not install them.
+
 ### Environment Variables
 
 ```bash
 # .env.local
 NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth
 NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
+# Public auth URL consumed by the browser auth client
+NEXT_PUBLIC_AUTH_URL=https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth
 ```
 
 Generate cookie secret:
@@ -59,7 +71,10 @@ openssl rand -base64 32
 // lib/auth/client.ts
 'use client';
 import { createAuthClient } from '@neondatabase/auth/next';
-export const authClient = createAuthClient();
+// createAuthClient takes the public auth URL as a positional argument
+export const authClient = createAuthClient(process.env.NEXT_PUBLIC_AUTH_URL!);
+// Re-export the React hooks from the client instance for ergonomic imports
+export const { useSession } = authClient;
 
 // lib/auth/server.ts
 import { createNeonAuth } from '@neondatabase/auth/next/server';
@@ -73,25 +88,21 @@ export const auth = createNeonAuth({
 
 ### Root Layout Provider
 
+Import the Tailwind styles for the UI components in `globals.css`:
+
+```css
+@import '@neondatabase/auth-ui/tailwind';
+```
+
 ```tsx
 // app/providers.tsx
 'use client';
-import { NeonAuthUIProvider } from '@neondatabase/auth/react';
-import '@neondatabase/auth/ui/css';
-import Link from 'next/link';
-import { useRouter } from 'next/navigation';
+import { NeonAuthUIProvider } from '@neondatabase/auth-ui';
 import { authClient } from '@/lib/auth/client';
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  const router = useRouter();
   return (
-    <NeonAuthUIProvider
-      authClient={authClient}
-      navigate={router.push}
-      replace={router.replace}
-      onSessionChange={router.refresh}
-      Link={Link}
-    >
+    <NeonAuthUIProvider authClient={authClient}>
       {children}
     </NeonAuthUIProvider>
   );
@@ -115,23 +126,23 @@ export const { GET, POST } = auth.handler();
 
 ```tsx
 // app/auth/sign-in/page.tsx
-import { AuthView } from '@neondatabase/auth/react';
+import { AuthView } from '@neondatabase/auth-ui';
 
 export default function SignInPage() {
   return (
     <div className="flex items-center justify-center min-h-screen">
-      <AuthView pathname="sign-in" />
+      <AuthView path="sign-in" />
     </div>
   );
 }
 
 // app/auth/sign-up/page.tsx
-import { AuthView } from '@neondatabase/auth/react';
+import { AuthView } from '@neondatabase/auth-ui';
 
 export default function SignUpPage() {
   return (
     <div className="flex items-center justify-center min-h-screen">
-      <AuthView pathname="sign-up" />
+      <AuthView path="sign-up" />
     </div>
   );
 }
@@ -200,7 +211,7 @@ export const config = {
 ### Component-Level Protection
 
 ```tsx
-import { SignedIn, RedirectToSignIn } from '@neondatabase/auth/react';
+import { SignedIn, RedirectToSignIn } from '@neondatabase/auth-ui';
 
 export default function ProtectedPage() {
   return (