feat(backend, clerk-js): Deprecate metadata updates in user update methods by brunol95 · Pull Request #8587 · clerk/javascript

brunol95 · 2026-05-18T19:13:02Z

Description

deprecates metadata fields in update user methods and refactors implementation to route to dedicated metadata endpoints
adds a new replaceUserMetadata method

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

changeset-bot · 2026-05-18T19:13:07Z

🦋 Changeset detected

Latest commit: 4cf3a28

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

This PR includes changesets to release 20 packages

Name	Type
@clerk/backend	Minor
@clerk/clerk-js	Patch
@clerk/shared	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/chrome-extension	Patch
@clerk/expo	Patch
@clerk/expo-passkeys	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/react	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 · 2026-05-18T19:13:08Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 20, 2026 6:54pm

coderabbitai · 2026-05-18T19:18:26Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR refactors user metadata update paths across the Clerk JavaScript SDK: it deprecates metadata parameters on updateUser/user.update, adds an RFC 7396 computeMergePatch utility, makes frontend User.update async to conditionally route unsafeMetadata via merge-patch-aware updateMetadata (short-circuiting when unchanged), splits backend updateUser into conditional PATCH (non-metadata) and PUT (metadata), and adds replaceUserMetadata for full metadata replacement. Tests and API/version constant bumps accompany the changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

clerk/javascript#8537: Introduces User.updateMetadata() on the frontend, which this PR uses as the target method for routing deprecated user.update({ unsafeMetadata }) calls.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly describes the main change: deprecating metadata updates in user update methods and routing to dedicated endpoints, which aligns with the primary objectives of the changeset.
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.
Description check	✅ Passed	The PR description accurately relates to the changeset: it deprecates metadata fields in update user methods, refactors routing to dedicated metadata endpoints, and adds replaceUserMetadata method.

_{✏️ 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.}

…update Co-authored-by: Cursor <cursoragent@cursor.com>

pkg-pr-new · 2026-05-18T20:00:58Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 4cf3a28

wobsoriano

Left a small suggestion and a question.

Also if possible, I think we should add an e2e test. We can place the test here https://github.com/clerk/javascript/blob/main/integration/tests/unsafeMetadata.test.ts

wobsoriano · 2026-05-19T17:19:24Z

Let's split this into separate changesets so each package changelog stays focused 👍🏼

for backend

for clerk-js and shared

wobsoriano · 2026-05-19T21:41:31Z

+      });
+    }
+
+    const patch = computeMergePatch(this.unsafeMetadata, unsafeMetadata);


Does this preserve replacement semantics if this.unsafeMetadata is not fresh at the moment of the call? Touch-on-focus can refresh the user in common tab-switching flows, but user.update({ unsafeMetadata }) previously sent the caller-provided value as the full replacement regardless of local cache state. With this client-side diff, a stale local value can produce an incomplete patch, or {} and skip the request entirely.

Correct me if Im wrong 😄

Ah yes you are right . There are two scenarios:

if we execute the call to PATCH v1 /me endpoint first that returns a fresh user object. No issue here since the diff will be using the latest data.

If the request is a metadata only update, then theres a chance the user object could be stale. In this case, I think we'll need to perform a reload first.

@wobsoriano I pushed a fix. Let me know what you think!

wobsoriano

a couple more comments, but this is looking good! Thank you for resolving the other requests

- update changesets - refactor to use dequal pkg - refactor tests to remove type assertion

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.changeset/route-unsafe-metadata-to-merge-endpoint.md:
- Line 13: Fix the broken inline code span by adding the missing opening
backtick so the fragment around user.update({ unsafeMetadata }) is rendered as
an inline code span; locate the sentence containing "user.update({
unsafeMetadata })` continues to work for now..." and prepend a backtick before
user.update to produce `user.update({ unsafeMetadata })` continues to work for
now and preserves its existing full-replacement behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: 38c3faa6-142f-4cc3-b7e7-b42ea737c237

📥 Commits

Reviewing files that changed from the base of the PR and between aebfef5 and 926d666.

📒 Files selected for processing (5)

.changeset/deprecate-update-user-metadata.md
.changeset/route-unsafe-metadata-to-merge-endpoint.md
integration/tests/unsafeMetadata.test.ts
packages/clerk-js/src/utils/__tests__/mergePatch.test.ts
packages/clerk-js/src/utils/mergePatch.ts

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

.changeset/deprecate-update-user-metadata.md

wobsoriano

Thanks for addressing the comments!

I think the main tradeoff I see is that mixed metadata + non-metadata updates are now split into two requests, so they are no longer atomic if the second request fails.

Approving!

…ta-fields

https://github.com/clerk/javascript into bruno/user-5312-deprecate-update-user-metadata-fields

brunol95 · 2026-05-20T19:10:29Z

!snapshot

brunol95 added clerk-js do not merge labels May 18, 2026

github-actions Bot added the backend label May 18, 2026

brunol95 changed the title ~~deprecate metadata updates in user update methods~~ chore(clerk-js, backend):deprecate metadata updates in user update methods May 18, 2026

deprecate metadata updates via clerkClient.users.updateUser and user.…

16fdd04

…update Co-authored-by: Cursor <cursoragent@cursor.com>

brunol95 force-pushed the bruno/user-5312-deprecate-update-user-metadata-fields branch from 640692b to 16fdd04 Compare May 18, 2026 19:56

vercel Bot deployed to Preview May 18, 2026 19:56 View deployment

brunol95 changed the title ~~chore(clerk-js, backend):deprecate metadata updates in user update methods~~ feat(clerk-js, backend):deprecate metadata updates in user update methods May 19, 2026

update api version in test

bf5b092

vercel Bot deployed to Preview May 19, 2026 14:02 View deployment

brunol95 changed the title ~~feat(clerk-js, backend):deprecate metadata updates in user update methods~~ feat(backend, clerk-js): Deprecate metadata updates in user update methods May 19, 2026

brunol95 requested review from a team and wobsoriano May 19, 2026 14:14

wobsoriano requested changes May 19, 2026

View reviewed changes

user.update refresh user object on metadata only updates

aebfef5

github-actions Bot added the integration label May 20, 2026

vercel Bot deployed to Preview May 20, 2026 14:22 View deployment

brunol95 requested a review from wobsoriano May 20, 2026 16:03

wobsoriano requested changes May 20, 2026

View reviewed changes

fix: isPlainObject rejects Date,Map, class interfaces

926d666

- update changesets - refactor to use dequal pkg - refactor tests to remove type assertion

vercel Bot deployed to Preview May 20, 2026 17:32 View deployment

coderabbitai Bot reviewed May 20, 2026

View reviewed changes

Comment thread .changeset/route-unsafe-metadata-to-merge-endpoint.md Outdated

chore: fix changeset formatting

c4ccc16

vercel Bot deployed to Preview May 20, 2026 17:50 View deployment

wobsoriano approved these changes May 20, 2026

View reviewed changes

Merge branch 'main' into bruno/user-5312-deprecate-update-user-metada…

34c0df9

…ta-fields

vercel Bot deployed to Preview May 20, 2026 18:18 View deployment

brunol95 added 2 commits May 20, 2026 14:40

address lint

34c3fc8

Merge branch 'bruno/user-5312-deprecate-update-user-metadata-fields' of

e0df27e

https://github.com/clerk/javascript into bruno/user-5312-deprecate-update-user-metadata-fields

vercel Bot deployed to Preview May 20, 2026 18:42 View deployment

change supported version to latest for testing

4cf3a28

vercel Bot deployed to Preview May 20, 2026 18:54 View deployment

Conversation

brunol95 commented May 18, 2026 • edited by wobsoriano Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

changeset-bot Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Estimated code review effort

Possibly related PRs

❌ Failed checks (1 warning)

Uh oh!

pkg-pr-new Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

wobsoriano May 19, 2026

Choose a reason for hiding this comment

Uh oh!

brunol95 May 20, 2026

Choose a reason for hiding this comment

Uh oh!

wobsoriano May 19, 2026

Choose a reason for hiding this comment

Uh oh!

brunol95 May 20, 2026

Choose a reason for hiding this comment

Uh oh!

brunol95 May 20, 2026

Choose a reason for hiding this comment

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

brunol95 commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

brunol95 commented May 18, 2026 •

edited by wobsoriano

Loading

changeset-bot Bot commented May 18, 2026 •

edited

Loading

vercel Bot commented May 18, 2026 •

edited

Loading

coderabbitai Bot commented May 18, 2026 •

edited

Loading

pkg-pr-new Bot commented May 18, 2026 •

edited

Loading