add user.updateMetadata method (#3366)

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>

Author: 3 people

docs/guides/users/extending.mdx

@@ -61,9 +61,14 @@ See the following examples to see how to set unsafe metadata on the frontend (cl
 
 <Tabs items={["Client-side", "Server-side"]}>
   <Tab>
+    Use the [`User.updateMetadata()`](/docs/reference/objects/user#update-metadata) method to update unsafe metadata from the frontend. The provided value is **deep-merged** with the existing `unsafeMetadata`, and any key set to `null` is removed.
+
+    > [!TIP]
+    > You can also use [`User.update()`](/docs/reference/objects/user#update) to update unsafe metadata, but it **fully replaces** the value instead of merging. Use `User.updateMetadata()` when you need to change specific keys.
+
     <Tabs items={["React-based SDKs", "JavaScript"]}>
       <Tab>
-        For React-based SDKs, such as Next.js, use the [`useUser()`](/docs/reference/hooks/use-user) hook to update unsafe metadata.
+        For React-based SDKs, such as Next.js, use the [`useUser()`](/docs/reference/hooks/use-user) hook to access the `User` object and call the `updateMetadata()` method.
 
         ```tsx {{ filename: 'page.tsx' }}
         export default function Page() {
@@ -76,7 +81,7 @@ See the following examples to see how to set unsafe metadata on the frontend (cl
 
               <button
                 onClick={() => {
-                  user?.update({
+                  user?.updateMetadata({
                     unsafeMetadata: { birthday },
                   })
                 }}
@@ -90,7 +95,7 @@ See the following examples to see how to set unsafe metadata on the frontend (cl
       </Tab>
 
       <Tab>
-        When using the JavaScript SDK, use the [`User.update()`](/docs/reference/objects/user#update) method to update unsafe metadata.
+        When using the JavaScript SDK, use the [`Clerk`](/docs/reference/objects/clerk) object to access the `User` object and call the `updateMetadata()` method.
 
         ```js {{ filename: 'main.js' }}
         import { Clerk } from '@clerk/clerk-js'
@@ -103,7 +108,7 @@ See the following examples to see how to set unsafe metadata on the frontend (cl
 
         if (clerk.isSignedIn) {
           await clerk.user
-            .update({
+            .updateMetadata({
               unsafeMetadata: {
                 birthday: '01-01-2000',
               },

docs/reference/objects/user.mdx

@@ -775,7 +775,24 @@ function update(params: UpdateUserParams): Promise<User>
   - `unsafeMetadata?`
   - [`UserUnsafeMetadata`](/docs/reference/types/metadata#user-unsafe-metadata)
 
-  Metadata that can be read and set from the Frontend API. One common use case for this attribute is to implement custom fields that will be attached to the `User` object. Updating this value overrides the previous value; it does not merge. To perform a merge, you can pass something like `{ …user.unsafeMetadata, …newData }` to this parameter.
+  Metadata that can be read and set from the Frontend API. One common use case for this attribute is to implement custom fields that will be attached to the `User` object. Using `update()` to update this value fully replaces the existing value. To perform a merge, use [`updateMetadata()`](#update-metadata) instead.
+</Properties>
+
+### `updateMetadata()`
+
+Updates the user's `unsafeMetadata` using deep-merge semantics. Unlike [`update()`](#update), which fully replaces `unsafeMetadata`, this method merges the provided value with the existing `unsafeMetadata`. Top-level and nested keys are merged, and any key set to `null` is removed. Only `unsafeMetadata` is writable from the frontend; `publicMetadata` and `privateMetadata` can only be set from the [Backend API](/docs/reference/backend-api){{ target: '_blank' }}.
+
+```ts
+function updateMetadata(params: UpdateUserMetadataParams): Promise<User>
+```
+
+#### `UpdateUserMetadataParams`
+
+<Properties>
+  - `unsafeMetadata`
+  - [`UserUnsafeMetadata`](/docs/reference/types/metadata#user-unsafe-metadata)
+
+  The metadata to deep-merge with the user's existing `unsafeMetadata`. Keys at any nesting level whose value is `null` are removed.
 </Properties>
 
 ### `updatePassword()`