chore(shared,react-router,tanstack-start): Create shared environment variable retrieval function

[wobsoriano]

Description

This PR introduces an isomorphic environment variable retrieval function that provides consistent config access across Node, Vite and Cloudflare Workers.

Right now it's only implemented in the React Router and TanStack Start SDKs as Next doesn't have a straightforward way of passing cloudflare context. See my comment in a related issue here.

Resolves ECO-302

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:

[vercel]

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	Feb 5, 2025 10:42pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 71ff504

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

This PR includes changesets to release 19 packages

Name	Type
@clerk/shared	Minor
@clerk/tanstack-start	Patch
@clerk/react-router	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/clerk-expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/clerk-react	Patch
@clerk/remix	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

[wobsoriano]

To support import.meta.env, esbuild needs a target of es2020 or above

[wobsoriano]

With the introduction of es2020 target, would it make sense to publish a minor version?

[LekoArts]

Seems fine 👍

[LekoArts]

Can you publish a snapshot release and test it on the different platforms?

Do you intend to use this shared package in the Next.js SDK in a follow-up?

[LekoArts]

Seems fine 👍

[wobsoriano]

Can you publish a snapshot release and test it on the different platforms?

Do you intend to use this shared package in the Next.js SDK in a follow-up?

Yes I intend to use this on other fullstack SDKs we have. I originally planned on adding Next.js SDK here but there's a blocker here regarding passing Cloudflare context that needs more research. I will do a follow up once resolved 👍🏼 For now I gave the user in that issue a solution that is actually a recommended approach

[wobsoriano]

!snapshot

[clerk-cookie]

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

Package	Version
@clerk/astro	2.1.20-snapshot.v20250204165902
@clerk/backend	1.23.12-snapshot.v20250204165902
@clerk/chrome-extension	2.2.7-snapshot.v20250204165902
@clerk/clerk-js	5.52.1-snapshot.v20250204165902
@clerk/elements	0.22.20-snapshot.v20250204165902
@clerk/clerk-expo	2.7.5-snapshot.v20250204165902
@clerk/expo-passkeys	0.1.19-snapshot.v20250204165902
@clerk/express	1.3.47-snapshot.v20250204165902
@clerk/fastify	2.1.20-snapshot.v20250204165902
@clerk/nextjs	6.11.1-snapshot.v20250204165902
@clerk/nuxt	1.1.3-snapshot.v20250204165902
@clerk/clerk-react	5.22.11-snapshot.v20250204165902
@clerk/react-router	1.0.6-snapshot.v20250204165902
@clerk/remix	4.4.22-snapshot.v20250204165902
@clerk/shared	2.21.0-snapshot.v20250204165902
@clerk/tanstack-start	0.9.4-snapshot.v20250204165902
@clerk/testing	1.4.21-snapshot.v20250204165902
@clerk/ui	0.3.21-snapshot.v20250204165902
@clerk/vue	1.1.11-snapshot.v20250204165902

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

npm i @clerk/astro@2.1.20-snapshot.v20250204165902 --save-exact

@clerk/backend

npm i @clerk/backend@1.23.12-snapshot.v20250204165902 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@2.2.7-snapshot.v20250204165902 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@5.52.1-snapshot.v20250204165902 --save-exact

@clerk/elements

npm i @clerk/elements@0.22.20-snapshot.v20250204165902 --save-exact

@clerk/clerk-expo

npm i @clerk/clerk-expo@2.7.5-snapshot.v20250204165902 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@0.1.19-snapshot.v20250204165902 --save-exact

@clerk/express

npm i @clerk/express@1.3.47-snapshot.v20250204165902 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.1.20-snapshot.v20250204165902 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@6.11.1-snapshot.v20250204165902 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@1.1.3-snapshot.v20250204165902 --save-exact

@clerk/clerk-react

npm i @clerk/clerk-react@5.22.11-snapshot.v20250204165902 --save-exact

@clerk/react-router

npm i @clerk/react-router@1.0.6-snapshot.v20250204165902 --save-exact

@clerk/remix

npm i @clerk/remix@4.4.22-snapshot.v20250204165902 --save-exact

@clerk/shared

npm i @clerk/shared@2.21.0-snapshot.v20250204165902 --save-exact

@clerk/tanstack-start

npm i @clerk/tanstack-start@0.9.4-snapshot.v20250204165902 --save-exact

@clerk/testing

npm i @clerk/testing@1.4.21-snapshot.v20250204165902 --save-exact

@clerk/ui

npm i @clerk/ui@0.3.21-snapshot.v20250204165902 --save-exact

@clerk/vue

npm i @clerk/vue@1.1.11-snapshot.v20250204165902 --save-exact

[wobsoriano]

Can you publish a snapshot release and test it on the different platforms?

Do you intend to use this shared package in the Next.js SDK in a follow-up?

Tested in a simple app for both Next.js and a Vite Vue app in this repo. They work as expected 🫡

[LekoArts]

Code looks good 👍

One last thing to test would be Expo. We had problems with @clerk/shared in the past with Expo because their Metro bundler is particularly picky about what it supports and what not. Since we don't have E2E tests, just to be sure that it supports es2020 target 🙏

[wobsoriano]

Code looks good 👍

One last thing to test would be Expo. We had problems with @clerk/shared in the past with Expo because their Metro bundler is particularly picky about what it supports and what not. Since we don't have E2E tests, just to be sure that it supports es2020 target 🙏

Tested on Expo. Works great 👍🏼