Skip to content

feat(clerk-js): ask fapi for the client only on reload and touch - #10874

Draft
nikosdouvlis wants to merge 2 commits into
mainfrom
nikos/sdk-172-clerk-js-request-the-piggybacked-client-from
Draft

nikosdouvlis wants to merge 2 commits into
mainfrom
nikos/sdk-172-clerk-js-request-the-piggybacked-client-from

Conversation

@nikosdouvlis

@nikosdouvlis nikosdouvlis commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Description

Draft. Do not merge until fapi accepts include_client on the current API version in production. clerk-js is hot-loaded, and today fapi rejects the unknown param on session touch and on GET /v1/organizations/{id}.

fapi is adding an API version where GET responses carry the client only when the request asks for it with include_client=true. clerk-js already ignores the client on GETs unless forceUpdateClient is set, so it only needs to ask where it applies it.

 reload()            GET  /v1/...
+                         ?include_client=true     (Base.reload and Organization.reload)
 session.touch()     POST /v1/client/sessions/{id}/touch
+                         ?include_client=true     (every intent)
 organization.getRoles() / getDomains() / getInvitations()
-  forceUpdateClient: true
+  client ignored, same as getMemberships()

Behavior change: listing organization roles, domains or invitations no longer refreshes the client. The flag was added in #2073 and dropped from getMemberships two days later in #2082. A role change made elsewhere now shows up on the next mutation, setActive or focus touch.

Focus touch guard: once fapi returns the client on focus touches, a focus touch response that lands after a newer response would overwrite the newer client with its older one. user.update() reverts, an org switch reverts, and after signOut() the sessions show as active again. The client now keeps a revision that moves on every write. A focus touch records it when sent, and its whole response is dropped if the revision moved by the time it arrives.

 Session._touchPost (intent=focus)
+  revision = client revision at send
   POST /v1/client/sessions/{id}/touch
+  revision moved: drop the response (no client, no session update, no token emit)
+  revision same:  apply as before

The check sits in Session._touchPost because getClientResourceFromPayload writes the client singleton at parse time, before Clerk.updateClient runs. Every other request applies as before, including setActive touches, so nothing the user did is ever dropped. A dropped focus touch may have been the newer one. The write that superseded it carried a full client, so only a change made elsewhere in between is missed until the next focus. This also stops a late focus touch from setting the session cookie again after sign-out, which happens today.

Checked in a browser against a dev instance with the new fapi behavior emulated. With the focus touch response held, user.update(), the org switch, email verification and sign-out all reverted before the guard and hold with it. With today's fapi the focus touch still refreshes the session cookie.

SUPPORTED_FAPI_VERSION is not bumped here, so nothing changes in what fapi returns yet. The bump follows once the new version is registered.

Not run on a device. Native OAuth and SSO finish with signIn.reload({ rotatingTokenNonce }), which now carries both the nonce and include_client=true (covered by a unit test).

Refs SDK-172, PLAT-4577

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: request params sent to fapi, plus the behavior change described above

Why:
FAPI is adding an API version where GET responses carry the client only when the request has include_client=true.
clerk-js already ignores the client on GETs unless forceUpdateClient is set, so it only has to ask where it applies it.

What changed:
GETs with forceUpdateClient (reload, including Organization.reload) and every session touch send include_client=true.
getRoles, getDomains and getInvitations no longer force a client update. The flag came from #2073 and was
already dropped from getMemberships in #2082.

Context:
SUPPORTED_FAPI_VERSION is not bumped here. This must not release before FAPI accepts include_client on the
current API version, because today it rejects the unknown param on touch and on GET /v1/organizations/{id}.
@vercel

vercel Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
clerk-js-sandbox Ready Ready Preview Nov 18, 2026 10:16am UTC
mosaic-docs Error Error Nov 18, 2026 10:16am UTC
swingset Ready Ready Preview Nov 18, 2026 10:16am UTC

Request Review

@changeset-bot

changeset-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 9ef0fbe

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

This PR includes changesets to release 4 packages
Name Type
@clerk/clerk-js Patch
@clerk/chrome-extension Patch
@clerk/electron Patch
@clerk/expo 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

@coderabbitai

coderabbitai Bot commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@pkg-pr-new

pkg-pr-new Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10874

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10874

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10874

@clerk/expo

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

@clerk/expo-biometrics

npm i https://pkg.pr.new/@clerk/expo-biometrics@10874

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10874

@clerk/expo-native-components

npm i https://pkg.pr.new/@clerk/expo-native-components@10874

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10874

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 9ef0fbe

Why:
Once fapi returns the client on focus touches, a focus touch response that
lands after a newer response overwrites the newer client with its older
one. user.update() reverts, an org switch reverts, and after signOut() the
sessions show as active again. A late focus touch also re-set the session
cookie after sign-out.

What changed:
The Client singleton keeps a revision that moves on every write. A focus
touch records it when sent and, if it moved by the time the response
arrives, the whole response is discarded before it is parsed: no client,
no in-place session update, no token emit. The check sits in
Session._touchPost because getClientResourceFromPayload writes the
singleton at parse time, before Clerk.updateClient runs. All other
requests, including setActive touches, apply as before.

Context:
A dropped focus touch may have been the newer one. The write that
superseded it carried a full client, so only a change made elsewhere in
between is missed until the next focus.

This branch was successfully deployed

2 active deployments
Preview – swingset — 9ef0fbe8 Deployed Nov 18, 2026 by vercel[bot]
Preview – clerk-js-sandbox — 9ef0fbe8 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant