feat(clerk-js): Introduce legacy browser variant #5495

dstaley · 2025-03-31T18:15:54Z

Description

This PR introduces a new legacy variant of clerk.browser, intended to be used for instances that require compatibility with browsers released in mid-2019 or newer. This is achieved through the use of core-js, which polyfills modern JavaScript APIs, in addition to the language-level transformations provided by SWC.

We now emit two primary clerk.browser bundles:

clerk.browser.js: This is our "modern"/default bundle that adheres to our browser support policy as specified by browserslist in package.json. This bundle includes language-level transformations for supported browsers, but does not include core-js polyfills. This is because core-js will polyfill divergent behaviors between browsers, inflating our bundle size.
clerk.legacy.browser.js: This is our legacy bundle that adheres to the browser support policy specified by browserslistLegacy in package.json, which supports browsers released in mid-2019 and later. It includes language-level transformations from SWC in addition to core-js polyfills. It is an additional 35KB gzipped compared to the default clerk.browser.js bundle.

In addition to the bundles, we also emit separate chunks for the legacy variant. clerk.legacy.browser.js will load legacy-compatible chunks, whereas clerk.browser.js will load modern-compatible chunks.

As of writing, it's not intended for customers to be able to manually switch to the legacy bundle since it's outside our official browser support matrix. We will be enabling this at the Cloudflare proxy level only for specific customers who have an agreement with us and a demonstrated need for legacy browser compatibility.

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 · 2025-03-31T18:15:58Z

🦋 Changeset detected

Latest commit: a01916b

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

This PR includes changesets to release 3 packages

Name	Type
@clerk/clerk-js	Minor
@clerk/chrome-extension	Patch
@clerk/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

vercel · 2025-03-31T18:15:58Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 18, 2025 1:52pm

dstaley · 2025-03-31T18:17:50Z

!snapshot

clerk-cookie · 2025-03-31T18:20:58Z

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

Package	Version
@clerk/agent-toolkit	0.0.17-snapshot.v20250331181940
@clerk/astro	2.4.6-snapshot.v20250331181940
@clerk/backend	1.26.0-snapshot.v20250331181940
@clerk/chrome-extension	2.2.24-snapshot.v20250331181940
@clerk/clerk-js	5.59.0-snapshot.v20250331181940
@clerk/elements	0.23.9-snapshot.v20250331181940
@clerk/clerk-expo	2.9.7-snapshot.v20250331181940
@clerk/expo-passkeys	0.2.1-snapshot.v20250331181940
@clerk/express	1.3.60-snapshot.v20250331181940
@clerk/fastify	2.1.33-snapshot.v20250331181940
@clerk/localizations	3.13.5-snapshot.v20250331181940
@clerk/nextjs	6.12.13-snapshot.v20250331181940
@clerk/nuxt	1.4.7-snapshot.v20250331181940
@clerk/clerk-react	5.25.6-snapshot.v20250331181940
@clerk/react-router	1.1.12-snapshot.v20250331181940
@clerk/remix	4.5.12-snapshot.v20250331181940
@clerk/shared	3.3.0-snapshot.v20250331181940
@clerk/tanstack-react-start	0.12.3-snapshot.v20250331181940
@clerk/testing	1.4.34-snapshot.v20250331181940
@clerk/themes	2.2.27-snapshot.v20250331181940
@clerk/types	4.50.2-snapshot.v20250331181940
@clerk/vue	1.4.6-snapshot.v20250331181940

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

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/elements

npm i @clerk/[email protected] --save-exact

@clerk/clerk-expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/clerk-react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/remix

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/themes

npm i @clerk/[email protected] --save-exact

@clerk/types

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

packages/clerk-js/package.json

dstaley · 2025-03-31T23:54:11Z

packages/clerk-js/rspack.config.js

@@ -158,7 +160,13 @@ const typescriptLoaderProd = () => {
        loader: 'builtin:swc-loader',
        options: {
          env: {
-            targets: packageJSON.browserslist,
+            targets,
+            ...(useCoreJs


Because core-js will inject polyfills even in our more modern targets, we only enable it when we know we're targeting legacy browsers.

packages/clerk-js/rspack.config.js

LekoArts

I'd argue that with this change we should also change our existing browserslist entry and remove the legacy information (Safari > 12, iOS > 12), write down the exact browsers we support in our docs, and set the browserslist according to that

packages/clerk-js/package.json

packages/clerk-js/rspack.config.js

dstaley · 2025-04-01T16:01:19Z

I'd argue that with this change we should also change our existing browserslist entry and remove the legacy information (Safari > 12, iOS > 12)

I absolutely agree with this, but it might break other customers who were relying on the transformations that SWC was applying to fit those targets. We're going to be discussing this more during the SDK Infra meeting this week to determine if we're okay accepting that. The current plan is to opt instances into the legacy bundle via CF worker, so we might be hesitant to suddenly break previously working browsers during a minor update.

dstaley · 2025-04-14T20:27:50Z

packages/clerk-js/rspack.config.js

@@ -65,7 +68,7 @@ const common = ({ mode, disableRHC = false }) => {
        }),
    ].filter(Boolean),
    output: {
-      chunkFilename: `[name]_[fullhash:6]_${packageJSON.version}.js`,
+      chunkFilename: `[name]_${variant}_[fullhash:6]_${packageJSON.version}.js`,


This is so that we can distinguish which variant a chunk belongs to, mainly so we could (in the future) target specific variant chunks with specific bundlewatch rules.

Copilot

Copilot reviewed 4 out of 7 changed files in this pull request and generated 1 comment.

Files not reviewed (3)

packages/clerk-js/bundlewatch.config.json: Language not supported
packages/clerk-js/package.json: Language not supported
pnpm-lock.yaml: Language not supported

packages/clerk-js/rspack.config.js

LekoArts

Generally speaking LGTM, left one minor comment.

Did you test a current snapshot of the normal browser and legacy bundle to see that old and new behavior is OK?

It would also be good to start a docs PR (if not already done) to update our https://clerk.com/docs/upgrade-guides/long-term-support#library-compatibility page

packages/clerk-js/rspack.config.js

Co-authored-by: Jacek Radko <[email protected]>

jacekradko

Let's give it a whirl!

feat(clerk-js): Introduce legacy browser variant

b9261a2

clerk-cookie added the clerk-js label Mar 31, 2025

vercel bot deployed to Preview March 31, 2025 18:16 View deployment

dstaley commented Mar 31, 2025

View reviewed changes

packages/clerk-js/package.json Outdated Show resolved Hide resolved

dstaley commented Mar 31, 2025

View reviewed changes

packages/clerk-js/rspack.config.js Show resolved Hide resolved

LekoArts reviewed Apr 1, 2025

View reviewed changes

packages/clerk-js/package.json Outdated Show resolved Hide resolved

packages/clerk-js/rspack.config.js Show resolved Hide resolved

fix(clerk-js): rename legacybrowserslist to browserslistLegacy

d98a8a7

vercel bot deployed to Preview April 1, 2025 17:22 View deployment

dstaley added 2 commits April 8, 2025 11:40

fix(clerk-js): Drop Safari 12 from clerk.browser.js

82008dc

Merge branch 'main' into ds.feat/core-js

1b53f83

vercel bot deployed to Preview April 8, 2025 18:43 View deployment

Merge branch 'main' into ds.feat/core-js

44a5bd6

vercel bot deployed to Preview April 14, 2025 16:23 View deployment

fix(clerk-js): Emit chunks with entry name

945c049

vercel bot deployed to Preview April 14, 2025 17:14 View deployment

fix(clerk-js): Hardcode variant instead of using runtime value

59689d0

vercel bot deployed to Preview April 14, 2025 18:51 View deployment

dstaley marked this pull request as ready for review April 14, 2025 20:25

dstaley commented Apr 14, 2025

View reviewed changes

dstaley added 2 commits April 14, 2025 13:29

fix(clerk-js): Emit chunks with the variant at the beginning of filename

29f5359

fix(clerk-js): Actually jkjk

4a3d4c9

vercel bot deployed to Preview April 14, 2025 20:30 View deployment

jacekradko requested a review from Copilot April 15, 2025 03:08

Copilot AI reviewed Apr 15, 2025

View reviewed changes

packages/clerk-js/rspack.config.js Outdated Show resolved Hide resolved

fix(clerk-js): use correct key

7f2ddc1

vercel bot deployed to Preview April 15, 2025 17:47 View deployment

LekoArts reviewed Apr 16, 2025

View reviewed changes

packages/clerk-js/rspack.config.js Outdated Show resolved Hide resolved

dstaley added 2 commits April 16, 2025 09:51

Merge branch 'main' into ds.feat/core-js

5c0b06e

fix(clerk-js): Default targets to browserslist

91a3e3e

vercel bot deployed to Preview April 16, 2025 18:35 View deployment

jacekradko reviewed Apr 16, 2025

View reviewed changes

packages/clerk-js/rspack.config.js Outdated Show resolved Hide resolved

jacekradko reviewed Apr 16, 2025

View reviewed changes

packages/clerk-js/rspack.config.js Outdated Show resolved Hide resolved

fix(clerk-js): Use correct variable

da1e493

Co-authored-by: Jacek Radko <[email protected]>

vercel bot deployed to Preview April 16, 2025 20:23 View deployment

fix(clerk-js): Always use installed core-js version

82222b0

vercel bot deployed to Preview April 16, 2025 20:31 View deployment

Merge branch 'main' into ds.feat/core-js

3d30778

vercel bot deployed to Preview April 17, 2025 17:10 View deployment

Merge branch 'main' into ds.feat/core-js

a01916b

vercel bot deployed to Preview April 18, 2025 13:52 View deployment

jacekradko approved these changes Apr 18, 2025

View reviewed changes

dstaley merged commit 6f4cf71 into main Apr 18, 2025
30 checks passed

dstaley deleted the ds.feat/core-js branch April 18, 2025 21:57

clerk-cookie mentioned this pull request Apr 18, 2025

ci(repo): Version packages #5665

Merged

feat(clerk-js): Introduce legacy browser variant #5495

feat(clerk-js): Introduce legacy browser variant #5495

Uh oh!

Conversation

dstaley commented Mar 31, 2025 • edited 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 Mar 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Mar 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dstaley commented Mar 31, 2025

Uh oh!

clerk-cookie commented Mar 31, 2025

Uh oh!

Uh oh!

dstaley Mar 31, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

LekoArts left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dstaley commented Apr 1, 2025

Uh oh!

dstaley Apr 14, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

LekoArts left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jacekradko left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dstaley commented Mar 31, 2025 •

edited

Loading

changeset-bot bot commented Mar 31, 2025 •

edited

Loading

vercel bot commented Mar 31, 2025 •

edited

Loading