Partial session changes
Change selected session fields without rebuilding the entire session object.
Auth.js · Function
unstable_update
unstable_update asynchronously updates session data using a partial session-shaped input. It resolves to the resulting Session or null.
How it works
unstable_update accepts a partial Session value, including partial user data, and returns a promise resolving to the updated Session or null. In a Next.js integration, import the helper from the configured auth module and call it with the fields to change.
Syntax
unstable_update: (data) => Promise<null | Session>;Parameters
| Name | Type | Description |
|---|---|---|
data | Partial<Session | { user: Partial<undefined | User> }> | Partial session data, optionally containing partial user data. |
Returns
Promise<null | Session>
Key points
- The function returns a Promise, so session updates must be handled asynchronously.
- The input is partial, so callers can provide only the session data relevant to the update.
- User information may be supplied as a partial object rather than requiring every user property.
- The resolved value can be a Session object or null.
Common mistakes
- The operation is asynchronous and may resolve to null, so callers should await it and handle the absence of a session.
Example: Update session data
import { auth, unstable_update } from "@/auth";
export async function updateSessionTheme(theme: "light" | "dark") {
return unstable_update({ user: { theme } });
}Pass a partial session-shaped object to update the current session and receive the resulting session or null.
When to use it
User metadata updates
Update user-related session data by passing a partial user object.
Async session workflows
Handle the result of a session mutation in asynchronous server-side code.
Interview questions
QWhat does unstable_update accept and return?
unstable_update is an asynchronous helper whose input is a partial Session value, optionally including partial user data. It resolves to either a Session or null.
Follow-up: What should a caller do with the result? Await the promise and account for the null branch before reading session fields.
QDoes unstable_update require a complete session?
Its argument can contain only the session properties that need changing rather than a complete Session object. The documented user shape is also partial, allowing selected user fields to be supplied.
Follow-up: Why is a partial input useful? It avoids requiring callers to reconstruct unrelated session data when changing one field.
QWhich Auth.js integration documents unstable_update?
The reference documents unstable_update as a Next.js API and gives the signature unstable_update: (data) => Promise<null | Session>. It is therefore used through the Next.js Auth.js integration rather than treated as a synchronous primitive.
Follow-up: What integration should be checked before using it? Confirm that the application is using the current Next.js Auth.js package and its configured auth export.
Related
SessionUserauthNextAuth.js