@netlify/identity 0.1.1-alpha.21 → 0.1.1-alpha.22

package/README.md

@@ -620,32 +620,58 @@ export function load() {
 
 ### Handling OAuth callbacks in SPAs
 
-All SPA frameworks need a callback handler that runs on page load to process OAuth redirects, email confirmations, and password recovery tokens.
+All SPA frameworks need a callback handler that runs on page load to process OAuth redirects, email confirmations, and password recovery tokens. Use a **wrapper component** that blocks page content while processing tokens. This prevents a flash of unauthenticated content that occurs when the page renders before the callback completes.
 
 ```tsx
 // React component (works with Next.js, Remix, TanStack Start)
-import { useEffect } from 'react'
+import { useEffect, useState } from 'react'
 import { handleAuthCallback } from '@netlify/identity'
 
-export function CallbackHandler() {
+const AUTH_HASH_PATTERN = /^#(confirmation_token|recovery_token|invite_token|email_change_token|access_token)=/
+
+export function CallbackHandler({ children }: { children: React.ReactNode }) {
+  const [processing, setProcessing] = useState(
+    () => typeof window !== 'undefined' && AUTH_HASH_PATTERN.test(window.location.hash),
+  )
+  const [error, setError] = useState<string | null>(null)
+
   useEffect(() => {
-    if (!window.location.hash) return
-
-    handleAuthCallback().then((result) => {
-      if (!result) return
-      if (result.type === 'invite') {
-        window.location.href = `/accept-invite?token=${result.token}`
-      } else {
-        window.location.href = '/dashboard'
-      }
-    })
+    if (!window.location.hash || !AUTH_HASH_PATTERN.test(window.location.hash)) return
+
+    handleAuthCallback()
+      .then((result) => {
+        if (!result) {
+          setProcessing(false)
+          return
+        }
+        if (result.type === 'invite') {
+          window.location.href = `/accept-invite?token=${result.token}`
+        } else {
+          window.location.href = '/dashboard'
+        }
+      })
+      .catch((err) => {
+        setError(err instanceof Error ? err.message : 'Callback failed')
+        setProcessing(false)
+      })
   }, [])
 
-  return null
+  if (error) return <div>Auth error: {error}</div>
+  if (processing) return <div>Confirming your account...</div>
+  return <>{children}</>
 }
 ```
 
-Mount this component in your **root layout** so it runs on every page. If you only mount it on a `/callback` route, OAuth redirects and email confirmation links that land on other pages will not be processed.
+Wrap your page content with this component in your **root layout** so it runs on every page:
+
+```tsx
+// Root layout
+<CallbackHandler>
+  <Outlet /> {/* or {children} in Next.js */}
+</CallbackHandler>
+```
+
+If you only mount it on a `/callback` route, OAuth redirects and email confirmation links that land on other pages will not be processed.
 
 ## Guides
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netlify/identity",
-  "version": "0.1.1-alpha.21",
+  "version": "0.1.1-alpha.22",
   "type": "module",
   "description": "Add authentication to your Netlify site with a few lines of code",
   "main": "./dist/index.cjs",
@@ -63,6 +63,7 @@
   },
   "author": "Netlify Inc.",
   "devDependencies": {
+    "@types/node": "^25.3.3",
     "eslint": "^9.0.0",
     "husky": "^9.1.7",
     "jsdom": "^28.1.0",