chore(repo): Align method prefixes, remove unused unstable methods by brkalow · Pull Request #7361 · clerk/javascript

brkalow · 2025-12-03T22:11:33Z

Description

fixes USER-3043
Adds some docs on internal/experimental method naming
Adds an eslint rule to disallow the previous __unstable_ naming pattern

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-12-03T22:11:38Z

🦋 Changeset detected

Latest commit: 0f83c0d

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

This PR includes changesets to release 19 packages

Name	Type
@clerk/clerk-js	Major
@clerk/react	Major
@clerk/nextjs	Major
@clerk/vue	Major
@clerk/astro	Major
@clerk/expo	Major
@clerk/chrome-extension	Major
@clerk/shared	Major
@clerk/ui	Major
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/nuxt	Patch
@clerk/agent-toolkit	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/testing	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-12-03T22:11:38Z

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

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Dec 4, 2025 8:41am

coderabbitai · 2025-12-03T22:11:39Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch brk.chore/align-method-prefixes

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

brkalow · 2025-12-03T23:04:44Z

!allow-major

brkalow · 2025-12-03T23:06:44Z

.changeset/align-experimental-unstable-prefixes.md

+- `__unstable_manageBillingUrl` (removed)
+- `__unstable_manageBillingLabel` (removed)
+- `__unstable_manageBillingMembersLimit` (removed)


As far as I can tell, these are unused and were to support Dashboard's use of our orgs components a few years ago

brkalow · 2025-12-03T23:07:03Z

.changeset/align-experimental-unstable-prefixes.md

+- `__unstable_manageBillingUrl` (removed)
+- `__unstable_manageBillingLabel` (removed)
+- `__unstable_manageBillingMembersLimit` (removed)
+- `experimental__forceOauthFirst` (removed)


Underlying properties on the API response object were removed in core 2, so finishing the cleanup here

brkalow · 2025-12-03T23:07:18Z

.changeset/align-experimental-unstable-prefixes.md

+- `experimental_createTheme` / `__experimental_createTheme` → `createTheme` (now exported from `@clerk/ui/themes/experimental`)
+- `experimental__simple` / `__experimental_simple` → `simple` (now exported from `@clerk/ui/themes/experimental`)


Moving to the preferred /experimental export pattern

brkalow · 2025-12-03T23:07:38Z

.changeset/align-experimental-unstable-prefixes.md

+- `experimental__simple` / `__experimental_simple` → `simple` (now exported from `@clerk/ui/themes/experimental`)
+
+### @clerk/chrome-extension
+- `__unstable__createClerkClient` → `createClerkClient` (exported from `@clerk/chrome-extension/background`)


I'm not sure if this should remain experimental/internal 🤔 @tmilewski do you have context?

@brkalow Yeah, this can be moved to stable at this point.

brkalow · 2025-12-03T23:08:01Z

docs/CONTRIBUTING.md

+### Experimental and internal APIs
+
+In some cases, we might need to add new methods to our publicly exposed APIs that are meant for internal use, or as experimental releases before the APIs are stabilized. For internal methods or properties, use the `__internal_` prefix. For experimental methods or properties that are attached to existing APIs, use the `__experimental_` prefix. For new exports, it is also acceptable to export from an `/experimental` subpath. Exports from `/experimental` are not covered by regular SemVer guarantees.


Documenting new patterns

brkalow · 2025-12-03T23:08:33Z

eslint.config.mjs

  },
 };

+const noUnstableMethods = {


New ESLint rule that should hopefully avoid any accidental addition of __unstable_ prefixes

pkg-pr-new · 2025-12-03T23:09:11Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7361

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 0f83c0d

brkalow · 2025-12-04T04:24:44Z

!allow-major

…fixes

brkalow added 3 commits December 3, 2025 15:44

Align method prefixes, remove unused unstable methods

6c6201c

update changeset

c57388f

Adds eslint rule and update contributing docs

082580a

clerk-cookie added clerk-js nextjs react expo chrome-extension playground integration astro vue labels Dec 3, 2025

Tweak export for experimental theme APIs

8505a75

vercel bot deployed to Preview December 3, 2025 22:44 View deployment

Update names to be consistent

49d4d8f

vercel bot deployed to Preview December 3, 2025 23:04 View deployment

brkalow commented Dec 3, 2025

View reviewed changes

nikosdouvlis approved these changes Dec 4, 2025

View reviewed changes

Merge branch 'vincent-and-the-doctor' into brk.chore/align-method-pre…

0f83c0d

…fixes

vercel bot deployed to Preview December 4, 2025 08:41 View deployment

nikosdouvlis merged commit e35960f into vincent-and-the-doctor Dec 4, 2025
32 of 41 checks passed

nikosdouvlis deleted the brk.chore/align-method-prefixes branch December 4, 2025 08:52

		- `experimental_createTheme` / `__experimental_createTheme` → `createTheme` (now exported from `@clerk/ui/themes/experimental`)
		- `experimental__simple` / `__experimental_simple` → `simple` (now exported from `@clerk/ui/themes/experimental`)

		### Experimental and internal APIs

		In some cases, we might need to add new methods to our publicly exposed APIs that are meant for internal use, or as experimental releases before the APIs are stabilized. For internal methods or properties, use the `__internal_` prefix. For experimental methods or properties that are attached to existing APIs, use the `__experimental_` prefix. For new exports, it is also acceptable to export from an `/experimental` subpath. Exports from `/experimental` are not covered by regular SemVer guarantees.

Conversation

brkalow commented Dec 3, 2025

Description

Checklist

Type of change

Uh oh!

changeset-bot bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

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

Uh oh!

Uh oh!

coderabbitai bot commented Dec 3, 2025

Review skipped

Uh oh!

brkalow commented Dec 3, 2025

Uh oh!

brkalow Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

brkalow Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

brkalow Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

brkalow Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

tmilewski Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

brkalow Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

brkalow Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

pkg-pr-new bot commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brkalow commented Dec 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

changeset-bot bot commented Dec 3, 2025 •

edited

Loading

vercel bot commented Dec 3, 2025 •

edited

Loading

pkg-pr-new bot commented Dec 3, 2025 •

edited

Loading