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

package/README.md

@@ -19,18 +19,20 @@ npm install @netlify/identity
 
 ## Quick start
 
-### Browser
+### Log in (browser)
 
 ```ts
-import { getUser } from '@netlify/identity'
+import { login, getUser } from '@netlify/identity'
 
-const user = getUser()
-if (user) {
-  console.log(`Hello, ${user.name}`)
-}
+// Log in
+const user = await login('jane@example.com', 'password123')
+console.log(`Hello, ${user.name}`)
+
+// Later, check auth state synchronously
+const currentUser = getUser()
 ```
 
-### Netlify Function
+### Protect a Netlify Function
 
 ```ts
 import { getUser } from '@netlify/identity'
@@ -43,7 +45,7 @@ export default async (req: Request, context: Context) => {
 }
 ```
 
-### Edge Function
+### Protect an Edge Function
 
 ```ts
 import { getUser } from '@netlify/identity'
@@ -66,7 +68,9 @@ export default async (req: Request, context: Context) => {
 getUser(): User | null
 ```
 
-Returns the current authenticated user, or `null` if not logged in. Synchronous, never throws.
+Returns the current authenticated user, or `null` if not logged in. Synchronous. Never throws.
+
+> **Next.js note:** Calling `getUser()` in a Server Component opts the page into [dynamic rendering](https://nextjs.org/docs/app/building-your-application/rendering/server-components#dynamic-rendering) because it reads cookies. This is expected and correct for authenticated pages. Next.js handles the internal dynamic rendering signal automatically.
 
 #### `isAuthenticated`
 
@@ -109,12 +113,14 @@ In the browser, uses gotrue-js and emits a `'login'` event. On the server (Netli
 #### `signup`
 
 ```ts
-signup(email: string, password: string, data?: Record<string, unknown>): Promise<User>
+signup(email: string, password: string, data?: SignupData): Promise<User>
 ```
 
 Creates a new account. Works in both browser and server contexts.
 
-In the browser, uses gotrue-js and emits `'login'` if autoconfirm is enabled. On the server, calls the GoTrue HTTP API directly and sets the `nf_jwt` cookie if the user is auto-confirmed.
+If autoconfirm is enabled in your Identity settings, the user is logged in immediately: cookies are set and a `'login'` event is emitted. If autoconfirm is **disabled** (the default), the user receives a confirmation email and must click the link before they can log in. In that case, no cookies are set and no auth event is emitted.
+
+The optional `data` parameter sets user metadata (e.g., `{ full_name: 'Jane Doe' }`), stored in the user's `user_metadata` field.
 
 **Throws:** `AuthError` on failure (e.g., email already registered, signup disabled). In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
 
@@ -126,9 +132,9 @@ logout(): Promise<void>
 
 Logs out the current user and clears the session. Works in both browser and server contexts.
 
-In the browser, uses gotrue-js and emits a `'logout'` event. On the server, calls GoTrue's `/logout` endpoint with the JWT from the `nf_jwt` cookie, then deletes the cookie.
+In the browser, uses gotrue-js and emits a `'logout'` event. On the server, calls GoTrue's `/logout` endpoint with the JWT from the `nf_jwt` cookie, then deletes the cookie. Auth cookies are always cleared, even if the GoTrue call fails.
 
-**Throws:** `AuthError` on network failure. In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
+**Throws:** In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
 
 #### `oauthLogin`
 
@@ -140,7 +146,7 @@ Redirects to an OAuth provider. The page navigates away, so this function never
 
 The `provider` argument should be one of the `AuthProvider` values: `'google'`, `'github'`, `'gitlab'`, `'bitbucket'`, `'facebook'`, or `'saml'`.
 
-**Throws:** `MissingIdentityError` if Identity is not configured. `Error` if called on the server.
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if called on the server.
 
 #### `handleAuthCallback`
 
@@ -160,6 +166,28 @@ onAuthChange(callback: AuthCallback): () => void
 
 Subscribes to auth state changes (login, logout, token refresh, user updates). Returns an unsubscribe function. Also fires on cross-tab session changes. No-op on the server.
 
+#### `hydrateSession`
+
+```ts
+hydrateSession(): Promise<User | null>
+```
+
+Bootstraps the browser-side gotrue-js session from server-set auth cookies (`nf_jwt`, `nf_refresh`). Returns the hydrated `User`, or `null` if no auth cookies are present. No-op on the server.
+
+**When to use:** After a server-side login (e.g., via a Netlify Function or Server Action), the `nf_jwt` cookie is set but gotrue-js has no browser session yet. `getUser()` works immediately (it decodes the cookie), but account operations like `updateUser()` or `verifyEmailChange()` require a live gotrue-js session. Call `hydrateSession()` once on page load to bridge this gap.
+
+If a gotrue-js session already exists (e.g., from a browser-side login), this is a no-op and returns the existing user.
+
+```ts
+import { hydrateSession, updateUser } from '@netlify/identity'
+
+// On page load, hydrate the session from server-set cookies
+await hydrateSession()
+
+// Now browser account operations work
+await updateUser({ data: { full_name: 'Jane Doe' } })
+```
+
 #### `requestPasswordRecovery`
 
 ```ts
@@ -213,10 +241,10 @@ Redeems a recovery token and sets a new password. Logs the user in on success.
 #### `updateUser`
 
 ```ts
-updateUser(updates: Record<string, unknown>): Promise<User>
+updateUser(updates: UserUpdates): Promise<User>
 ```
 
-Updates the current user's metadata or credentials. Requires an active session.
+Updates the current user's metadata or credentials. Requires an active session. Pass `email` or `password` to change credentials, or `data` to update user metadata (e.g., `{ data: { full_name: 'New Name' } }`).
 
 **Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if no user is logged in, or the update fails.
 
@@ -264,6 +292,27 @@ interface IdentityConfig {
 type AuthProvider = 'google' | 'github' | 'gitlab' | 'bitbucket' | 'facebook' | 'saml' | 'email'
 ```
 
+#### `UserUpdates`
+
+```ts
+interface UserUpdates {
+  email?: string
+  password?: string
+  data?: Record<string, unknown>
+  [key: string]: unknown
+}
+```
+
+Fields accepted by `updateUser()`. All fields are optional.
+
+#### `SignupData`
+
+```ts
+type SignupData = Record<string, unknown>
+```
+
+User metadata passed as the third argument to `signup()`. Stored in the user's `user_metadata` field.
+
 #### `AppMetadata`
 
 ```ts
@@ -422,7 +471,7 @@ export async function loader() {
 }
 ```
 
-Remix actions return HTTP responses, so `redirect()` after server-side `login()` works correctly with cookies.
+Remix `redirect()` works after server-side `login()` because Remix actions return real HTTP responses. The browser receives a 302 with the `Set-Cookie` header already applied, so the next request includes the auth cookie. This is different from Next.js, where `redirect()` in a Server Action triggers a client-side (soft) navigation that may not include newly-set cookies.
 
 ### TanStack Start
 
@@ -526,37 +575,133 @@ if (!user) return Astro.redirect('/login')
 <h1>Hello, {user.email}</h1>
 ```
 
+### SvelteKit
+
+**Login from the browser (recommended):**
+
+```svelte
+<!-- src/routes/login/+page.svelte -->
+<script lang="ts">
+  import { login } from '@netlify/identity'
+
+  let email = ''
+  let password = ''
+  let error = ''
+
+  async function handleLogin() {
+    try {
+      await login(email, password)
+      window.location.href = '/dashboard'
+    } catch (e) {
+      error = (e as Error).message
+    }
+  }
+</script>
+
+<form on:submit|preventDefault={handleLogin}>
+  <input bind:value={email} type="email" />
+  <input bind:value={password} type="password" />
+  <button type="submit">Log in</button>
+  {#if error}<p>{error}</p>{/if}
+</form>
+```
+
+```ts
+// src/routes/dashboard/+page.server.ts
+import { getUser } from '@netlify/identity'
+import { redirect } from '@sveltejs/kit'
+
+export function load() {
+  const user = getUser()
+  if (!user) redirect(302, '/login')
+  return { user }
+}
+```
+
 ### 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 processes callbacks on any page.
+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
 
+### React `useAuth` hook
+
+The library is framework-agnostic, but here's a simple React hook for keeping components in sync with auth state:
+
+```tsx
+import { useState, useEffect } from 'react'
+import { getUser, onAuthChange } from '@netlify/identity'
+import type { User } from '@netlify/identity'
+
+export function useAuth() {
+  const [user, setUser] = useState<User | null>(getUser())
+
+  useEffect(() => {
+    return onAuthChange((_event, user) => setUser(user))
+  }, [])
+
+  return user
+}
+```
+
+```tsx
+function NavBar() {
+  const user = useAuth()
+  return user ? <p>Hello, {user.name}</p> : <a href="/login">Log in</a>
+}
+```
+
 ### Listening for auth changes
 
 Use `onAuthChange` to keep your UI in sync with auth state. It fires on login, logout, token refresh, and user updates. It also detects session changes in other browser tabs (via `localStorage`).
@@ -656,6 +801,17 @@ if (result?.type === 'invite' && result.token) {
 }
 ```
 
+### Session lifetime
+
+Sessions are managed by Netlify Identity (GoTrue) on the server side. The library stores two cookies:
+
+- **`nf_jwt`**: A short-lived JWT access token (default: 1 hour). Automatically refreshed by gotrue-js in the browser using the refresh token.
+- **`nf_refresh`**: A long-lived refresh token used to obtain new access tokens without re-authenticating.
+
+In the browser, gotrue-js handles token refresh automatically in the background. On the server, the access token in the `nf_jwt` cookie is validated as-is; if it has expired, `getUser()` returns `null`. The user will need to refresh the page (which triggers a browser-side token refresh) or log in again.
+
+Session lifetime is configured in your GoTrue/Identity server settings, not in this library.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   getSettings: () => getSettings,
   getUser: () => getUser,
   handleAuthCallback: () => handleAuthCallback,
+  hydrateSession: () => hydrateSession,
   isAuthenticated: () => isAuthenticated,
   login: () => login,
   logout: () => logout,
@@ -69,7 +70,7 @@ var AuthError = class extends Error {
   }
 };
 var MissingIdentityError = class extends Error {
-  constructor(message = "Identity is not available in this environment") {
+  constructor(message = "Netlify Identity is not available. Enable Identity in your site dashboard and use `netlify dev` for local development.") {
     super(message);
     this.name = "MissingIdentityError";
   }
@@ -247,6 +248,9 @@ var backgroundHydrate = (accessToken) => {
   if (hydrating) return;
   hydrating = true;
   const refreshToken = getCookie(NF_REFRESH_COOKIE) ?? "";
+  const decoded = decodeJwtPayload(accessToken);
+  const expiresAt = decoded?.exp ?? Math.floor(Date.now() / 1e3) + 3600;
+  const expiresIn = Math.max(0, expiresAt - Math.floor(Date.now() / 1e3));
   setTimeout(() => {
     try {
       const client = getClient();
@@ -254,8 +258,8 @@ var backgroundHydrate = (accessToken) => {
         {
           access_token: accessToken,
           token_type: "bearer",
-          expires_in: 3600,
-          expires_at: Math.floor(Date.now() / 1e3) + 3600,
+          expires_in: expiresIn,
+          expires_at: expiresAt,
           refresh_token: refreshToken
         },
         true
@@ -363,15 +367,19 @@ var persistSession = true;
 var listeners = /* @__PURE__ */ new Set();
 var emitAuthEvent = (event, user) => {
   for (const listener of listeners) {
-    listener(event, user);
+    try {
+      listener(event, user);
+    } catch {
+    }
   }
 };
+var GOTRUE_STORAGE_KEY = "gotrue.user";
 var storageListenerAttached = false;
 var attachStorageListener = () => {
   if (storageListenerAttached) return;
   storageListenerAttached = true;
   window.addEventListener("storage", (event) => {
-    if (event.key !== "gotrue.user") return;
+    if (event.key !== GOTRUE_STORAGE_KEY) return;
     if (event.newValue) {
       const client = getGoTrueClient();
       const currentUser = client?.currentUser();
@@ -486,6 +494,10 @@ var signup = async (email, password, data) => {
     const response = await client.signup(email, password, data);
     const user = toUser(response);
     if (response.confirmed_at) {
+      const jwt = await response.jwt?.();
+      if (jwt) {
+        setBrowserAuthCookies(jwt);
+      }
       emitAuthEvent("login", user);
     }
     return user;
@@ -504,8 +516,7 @@ var logout = async () => {
           method: "POST",
           headers: { Authorization: `Bearer ${jwt}` }
         });
-      } catch (error) {
-        throw new AuthError(error.message, void 0, { cause: error });
+      } catch {
       }
     }
     deleteAuthCookies(cookies);
@@ -525,11 +536,11 @@ var logout = async () => {
 };
 var oauthLogin = (provider) => {
   if (!isBrowser()) {
-    throw new Error("oauthLogin() is only available in the browser");
+    throw new AuthError("oauthLogin() is only available in the browser");
   }
   const client = getClient();
   window.location.href = client.loginExternalUrl(provider);
-  throw new Error("Redirecting to OAuth provider");
+  throw new AuthError("Redirecting to OAuth provider");
 };
 var handleAuthCallback = async () => {
   if (!isBrowser()) return null;
@@ -613,6 +624,7 @@ var handleAuthCallback = async () => {
     }
     return null;
   } catch (error) {
+    if (error instanceof AuthError) throw error;
     throw new AuthError(error.message, void 0, { cause: error });
   }
 };
@@ -627,12 +639,15 @@ var hydrateSession = async () => {
   const accessToken = getCookie(NF_JWT_COOKIE);
   if (!accessToken) return null;
   const refreshToken = getCookie(NF_REFRESH_COOKIE) ?? "";
+  const decoded = decodeJwtPayload(accessToken);
+  const expiresAt = decoded?.exp ?? Math.floor(Date.now() / 1e3) + 3600;
+  const expiresIn = Math.max(0, expiresAt - Math.floor(Date.now() / 1e3));
   const gotrueUser = await client.createUser(
     {
       access_token: accessToken,
       token_type: "bearer",
-      expires_in: 3600,
-      expires_at: Math.floor(Date.now() / 1e3) + 3600,
+      expires_in: expiresIn,
+      expires_at: expiresAt,
       refresh_token: refreshToken
     },
     persistSession
@@ -749,6 +764,7 @@ var updateUser = async (updates) => {
   getSettings,
   getUser,
   handleAuthCallback,
+  hydrateSession,
   isAuthenticated,
   login,
   logout,