feat(clerk-js): Improve getToken offline handling
#7598
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Trigger background refresh when needsRefresh is true, without requiring refreshIfStale option. Guarantees cache revalidation without relying solely on the poller. - Add #refreshTokenInBackground() that doesn't cache pending promise, allowing concurrent getToken() calls to return stale token while refresh is in progress. - Track in-flight background refreshes to prevent duplicate requests. - Rename DEFAULT_LEEWAY to BACKGROUND_REFRESH_THRESHOLD_IN_SECONDS with clear documentation about 15s minimum and rate limiting warning. - Add comprehensive JSDoc for leewayInSeconds option explaining minimum value, default, and rate limiting considerations.
Add upgrade guide entries for: - getToken `leewayInSeconds` minimum of 15 seconds - stale-while-revalidate pattern for session tokens
- Test refreshIfStale: true forces synchronous refresh when token is stale - Test refreshIfStale: true with fresh token returns cached value - Test leewayInSeconds triggers earlier background refresh - Test minimum 15s leeway enforcement - Test no background refresh when token has sufficient TTL
- Rename option from leewayInSeconds to backgroundRefreshThreshold for clarity - Lower minimum threshold from 15s to 5s (poller interval) - Remove explicit refreshIfStale: false in AuthCookieService (default behavior) - Update tests and upgrade documentation
🦋 Changeset detectedLatest commit: 9de4869 The changes in this PR will be included in the next version bump. This PR includes changesets to release 21 packages
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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
bratsos
changed the base branch from
main
to
alexbratsos/user-4045-make-gettoken-callable-outside-of-react
jacekradko
reviewed
Jan 14, 2026
Comment on lines
94
to
102
| if (ClerkOfflineError.is(e)) { | ||
| throw e; | ||
| } | ||
|
|
||
| if (isNetworkError(e) || !isValidBrowserOnline()) { | ||
| throw new ClerkOfflineError('Network request failed', { | ||
| cause: e instanceof Error ? e : undefined, | ||
| }); | ||
| } |
Member
There was a problem hiding this comment.
Is this something we want to happen for all resources, or just the session resource?
Member
Author
There was a problem hiding this comment.
I've change this since the last refactor, I've only kept the ClerkOfflineError exception only on session resource
Member
|
@bratsos I am concerned that this PR is going to conflict heavily with the stale-while-revalidate change: #7317 I think we will want to base this PR off feat/stale-while-revalidate-token and build on top of it. Some of the offline heuristics work well with SWR since we can return a cached token whenever possible and error only when we truly cannot fetch a new token |
# Conflicts: # packages/clerk-js/bundlewatch.config.json
Base automatically changed from
alexbratsos/user-4045-make-gettoken-callable-outside-of-react
to
main
January 16, 2026 16:45
Replace the stale-while-revalidate approach with a timer-based proactive refresh mechanism. Instead of relying on getToken() calls to trigger background refresh, we now schedule a timer when tokens are cached that fires before the leeway period begins. Key changes: - Add onRefresh callback to TokenCacheEntry for proactive refresh - Schedule refresh timer at (TTL - leeway - 2s) = 43s for 60s tokens - Remove needsRefresh flag and refreshThreshold parameter from cache - Remove backgroundRefreshThreshold and refreshIfStale from GetTokenOptions - Update Session to pass onRefresh callback when caching tokens Benefits: - More consistent refresh regardless of getToken() call frequency - Zero risk: if timer doesn't fire, poller catches it as fallback - Fits naturally with existing cleanup timer pattern
BREAKING CHANGE: `getToken()` now throws `ClerkOfflineError` instead of returning `null` when the client is offline. This makes it explicit that the failure was due to network conditions, not authentication state.
bratsos
force-pushed
the
alexbratsos/user-4063-improve-gettoken-offline-handling
branch
from
b6350c6 to
640e362
Compare
bratsos
changed the title
getToken offline handlinggetToken offline handling
bratsos
changed the base branch from
main
to
feat/stale-while-revalidate-token
bratsos
commented
Jan 28, 2026
Comment on lines
+2
to
+10
| '@clerk/tanstack-react-start': major | ||
| '@clerk/react-router': major | ||
| '@clerk/clerk-js': major | ||
| '@clerk/upgrade': major | ||
| '@clerk/nextjs': major | ||
| '@clerk/shared': major | ||
| '@clerk/react': major | ||
| '@clerk/nuxt': major | ||
| '@clerk/vue': major |
Member
Author
There was a problem hiding this comment.
I'm not sure if this should be a major change in all sdks 🤔
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
offline-demo.mp4
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change