feat(clerk-js): add update user metadata method

[brunol95]

Description

This PR introduces the updateMetadata method on the user object
https://clerk.com/docs/reference/frontend-api/2025-11-10/tag/user/PATCH/v1/me/metadata

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 59982f4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages

Name	Type
@clerk/clerk-js	Minor
@clerk/shared	Minor
@clerk/chrome-extension	Patch
@clerk/expo	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 13, 2026 5:40pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: e5fdc5d8-a987-4140-8166-7d1b83cd882c

📥 Commits

Reviewing files that changed from the base of the PR and between bdec0ff and 59982f4.

📒 Files selected for processing (1)

• .changeset/user-update-metadata.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/user-update-metadata.md

---

📝 Walkthrough

Walkthrough

This PR adds a new updateMetadata method to the UserResource interface and its User class implementation. The method accepts UpdateUserMetadataParams containing unsafeMetadata and issues a PATCH request to /me/metadata, using merge semantics where nested keys are merged and keys set to null are removed. Two tests verify the PATCH includes JSON-stringified unsafeMetadata and correctly handles null-valued keys. A changeset documents minor bumps for @clerk/clerk-js and @clerk/shared and notes unsafeMetadata is writable.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title clearly and concisely summarizes the main change: adding an updateMetadata method to the user object in clerk-js.
Description check	✅ Passed	The pull request description is directly related to the changeset, explaining the purpose of introducing the updateMetadata method and referencing the relevant API endpoint.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8537

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8537

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8537

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8537

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8537

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8537

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8537

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8537

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8537

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8537

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8537

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8537

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8537

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8537

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8537

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8537

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8537

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8537

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8537

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8537

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8537

commit: 59982f4

[brunol95]

!snapshot

[github-actions]

Hey @brunol95 - the snapshot version command generated the following package versions:

Package	Version
@clerk/astro	3.2.3-snapshot.v20260513155808
@clerk/backend	3.4.8-snapshot.v20260513155808
@clerk/chrome-extension	3.1.25-snapshot.v20260513155808
@clerk/clerk-js	6.11.0-snapshot.v20260513155808
@clerk/dev-cli	0.1.1-snapshot.v20260513155808
@clerk/expo	3.2.11-snapshot.v20260513155808
@clerk/expo-passkeys	1.0.24-snapshot.v20260513155808
@clerk/express	2.1.16-snapshot.v20260513155808
@clerk/fastify	3.1.26-snapshot.v20260513155808
@clerk/hono	0.1.26-snapshot.v20260513155808
@clerk/localizations	4.6.3-snapshot.v20260513155808
@clerk/msw	0.0.24-snapshot.v20260513155808
@clerk/nextjs	7.3.4-snapshot.v20260513155808
@clerk/nuxt	2.4.3-snapshot.v20260513155808
@clerk/react	6.6.3-snapshot.v20260513155808
@clerk/react-router	3.2.4-snapshot.v20260513155808
@clerk/shared	4.11.0-snapshot.v20260513155808
@clerk/tanstack-react-start	1.2.4-snapshot.v20260513155808
@clerk/testing	2.0.28-snapshot.v20260513155808
@clerk/ui	1.9.2-snapshot.v20260513155808
@clerk/upgrade	2.0.3-snapshot.v20260513155808
@clerk/vue	2.2.3-snapshot.v20260513155808

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/astro

npm i @clerk/astro@3.2.3-snapshot.v20260513155808 --save-exact

@clerk/backend

npm i @clerk/backend@3.4.8-snapshot.v20260513155808 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.1.25-snapshot.v20260513155808 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.11.0-snapshot.v20260513155808 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@0.1.1-snapshot.v20260513155808 --save-exact

@clerk/expo

npm i @clerk/expo@3.2.11-snapshot.v20260513155808 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.24-snapshot.v20260513155808 --save-exact

@clerk/express

npm i @clerk/express@2.1.16-snapshot.v20260513155808 --save-exact

@clerk/fastify

npm i @clerk/fastify@3.1.26-snapshot.v20260513155808 --save-exact

@clerk/hono

npm i @clerk/hono@0.1.26-snapshot.v20260513155808 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.6.3-snapshot.v20260513155808 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.24-snapshot.v20260513155808 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.3.4-snapshot.v20260513155808 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.4.3-snapshot.v20260513155808 --save-exact

@clerk/react

npm i @clerk/react@6.6.3-snapshot.v20260513155808 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.2.4-snapshot.v20260513155808 --save-exact

@clerk/shared

npm i @clerk/shared@4.11.0-snapshot.v20260513155808 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.2.4-snapshot.v20260513155808 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.28-snapshot.v20260513155808 --save-exact

@clerk/ui

npm i @clerk/ui@1.9.2-snapshot.v20260513155808 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.3-snapshot.v20260513155808 --save-exact

@clerk/vue

npm i @clerk/vue@2.2.3-snapshot.v20260513155808 --save-exact

[wobsoriano]

Looks good!