feat(shared): use American English spelling in public APIs and JSDoc

[manovotny]

Description

Moves the SDK's public surface to American English spelling, using the first spelling Merriam-Webster lists. This is part of Clerk standardizing on American English, which started in https://github.com/clerk/clerk/pull/3495.

• Adds isReverificationCanceledError() to @clerk/shared/error and the errors entry points of @clerk/react, @clerk/nextjs, @clerk/react-router, and @clerk/tanstack-react-start. isReverificationCancelledError() stays as a deprecated alias of the same function, so existing imports keep working. Internal uses now call the new name.
• Fixes British spellings in JSDoc for exported APIs and types: "cancelled", "towards", "backwards", "afterwards", "unrecognised", "customise", "initialised", "normalised", and "behaviour". This covers cancelSubscriptionItem(), BillingSubscriptionJSON.next_payment, BillingCheckoutTotalsJSON, NeedsReverificationParameters.cancel, currentUser(), buildUrlWithAuth(), fedCmSupport, the Protect loader config, and the appearance logo and social button options.
• Fixes the useReverification() example, which imported from @clerk/react/error (the entry point is @clerk/react/errors) and caught e while checking err.

Adds pnpm lint:american-spelling (scripts/american-spelling.mjs), which runs in pnpm lint and in CI. It's a denylist of British spellings that also splits camelCase and snake_case identifiers, and --fix rewrites what it finds. It skips CHANGELOGs, the lockfile, and the non-en-US localizations, which include en-GB and translations that aren't in English. Its exceptions are the public names listed under "Not changed", the deprecated isReverificationCancelledError alias, and ariaLabelledBy from the ARIA spec. Values that are a bare word go through a scoped american-spelling-ignore-next-line marker instead. These are GitHub Actions' cancelled(), the Electron native code 'cancelled', the Directory Sync API status 'cancelled', the CSS color grey, quoted native Google sign-in messages, and French test strings. --fix cleaned up the rest of the repo, 363 spellings in comments, tests, docs, internal names, and en-US copy. One example is the "Cancelled" Directory Sync status, which now reads "Canceled".

Not changed

These values are emitted at runtime or are part of a cross-version contract. Renaming any of them breaks code that compares against the current spelling, so they're candidates for the next major:

• reverification_cancelled (ClerkRuntimeError code): apps compare err.code against it, and older SDKs check for it.
• passkey_registration_cancelled / passkey_retrieval_cancelled (ClerkRuntimeError codes): apps compare against them across web, Expo, and Electron, and they double as unstable__errors localization keys.
• SIGN_IN_CANCELLED (@clerk/expo-google-signin native error code and its "User cancelled the sign-in flow" message): apps check the code, and @clerk/expo matches on it; the native modules ship separately from the JS.
• 'cancelled' (PasskeyNativeErrorCode from @clerk/electron-passkeys): not exported from a package entry point, but it's the contract between @clerk/electron and the separately versioned native addon, so an older addon would still emit 'cancelled'.
• afterVerificationCancelled (__internal_UserVerificationProps): older @clerk/shared versions pass it to newer @clerk/ui at runtime.
• syncStatus__cancelled (localization key): apps that override localization strings use the key by name.

Also left alone: @clerk/localizations en-GB, CHANGELOGs, and spec terms such as aria-labelledby.

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:

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 35ee4de

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

This PR includes changesets to release 24 packages

Name	Type
@clerk/backend	Patch
@clerk/expo	Patch
@clerk/nextjs	Minor
@clerk/shared	Minor
@clerk/ui	Patch
@clerk/localizations	Patch
@clerk/mosaic	Patch
@clerk/electron	Patch
@clerk/upgrade	Patch
@clerk/react	Minor
@clerk/react-router	Minor
@clerk/tanstack-react-start	Minor
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nuxt	Patch
@clerk/testing	Patch
@clerk/swingset	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/msw	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

[vercel]

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Oct 7, 2026 9:45pm UTC
swingset	Ready	Preview	Oct 7, 2026 9:45pm UTC

[coderabbitai]

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

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-biometrics

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

@clerk/expo-google-signin

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/mosaic

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 35ee4de