feat(clerk-js,localizations,shared,ui): Annual-only plans by dstaley · Pull Request #8012 · clerk/javascript

dstaley · 2026-03-09T19:18:53Z

Description

This PR adds support for annual-only billing plans. An annual-only billing plan is a plan where the fee is null. This is a new concept, so the UI needed to be updated to remove all assumptions of fee being always available. This is mostly small logic changes, but the most significant change is in the PricingTable and PlanDetails components where we now render Only billed monthly when a plan only supports being billed annually.

Testing Instructions

Checkout locally, run pnpm i && turbo build, then pnpm dev:sandbox to start the sandbox and go to it at http://localhost:4000
Open the development tools console
run scenario.setScenario(AVAILABLE_SCENARIOS.AnnualOnlyPlans)
after refresh run components.pricingTable.setProps({ for: 'user' })
navigate to the pricing table page
confirm that three plans are rendered: one monthly-only, one that supports monthly and annual, and one annual only
confirm changing the toggle on the middle plan does not impact rendering on the first or third plans

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

Summary by CodeRabbit

New Features
- Support for annual-only billing plans and plans that can omit a base monthly fee
- Period toggle to switch monthly/annual where applicable
- Checkout automatically selects an appropriate billing period
UI
- Updated plan details and pricing table to use consolidated fee formatting and unified period handling
Localization
- Added label: "Only billed annually"
Sandbox
- New annual-only plans scenario and updated demo billing flags

vercel · 2026-03-09T19:18:58Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 9, 2026 8:53pm

changeset-bot · 2026-03-09T19:19:02Z

🦋 Changeset detected

Latest commit: 1968bf5

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

This PR includes changesets to release 21 packages

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

coderabbitai · 2026-03-09T19:21:49Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 41d6eb84-c8e6-45e6-91bb-d9950b8e8628

📥 Commits

Reviewing files that changed from the base of the PR and between 7648ea3 and 1968bf5.

📒 Files selected for processing (1)

packages/ui/src/components/PricingTable/PricingTableDefault.tsx

🚧 Files skipped from review as they are similar to previous changes (1)

packages/ui/src/components/PricingTable/PricingTableDefault.tsx

📝 Walkthrough

Walkthrough

Introduces a changeset and makes BillingPlan.fee nullable across backend, shared types, clerk-js resources, and JSON shapes. Adds a sandbox scenario AnnualOnlyPlans and a localization key billing.billedAnnuallyOnly. UI components (Plans/PlanDetails, PricingTable) were refactored to handle nullable fees and to use a new PeriodToggle component. Adds determinePlanPeriod helper used in the checkout flow. Updates MSW single-session environment to enable billing flags.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding support for annual-only billing plans across multiple packages.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

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

pkg-pr-new · 2026-03-09T19:24:29Z

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 1968bf5

mzhong9723 · 2026-03-09T22:33:53Z

-          enabled: false,
-          has_paid_plans: false,
+          enabled: true,
+          has_paid_plans: true,
        },
        stripe_publishable_key: '',
        user: {
-          enabled: false,
-          has_paid_plans: false,
+          enabled: true,
+          has_paid_plans: true,


(not blocking just curious) what is this change for?

this is for the mock scenario system. this sets all mock scenarios to default to having billing enabled.

dstaley added 3 commits March 9, 2026 10:25

feat(clerk-js,localizations,shared,ui): Annual-only plans

5c88c16

feat(ui): Update PricingTable for annual only plans

e15d316

fix(msw): Enable billing by default

df2dad2

github-actions Bot added clerk-js localizations ui labels Mar 9, 2026

dstaley changed the title ~~Ds.feat/annual only~~ feat(clerk-js,localizations,shared,ui): Annual-only plans Mar 9, 2026

vercel Bot deployed to Preview March 9, 2026 19:19 View deployment

chore(repo): Add changeset

430c73c

vercel Bot deployed to Preview March 9, 2026 19:22 View deployment

feat(backend): Add support for annual-only Billing plans

5c4beab

github-actions Bot added the backend label Mar 9, 2026

vercel Bot deployed to Preview March 9, 2026 19:25 View deployment

fix(ui): Determine plan period correctly

7648ea3

vercel Bot deployed to Preview March 9, 2026 19:39 View deployment

chore(ui): Simplify component

1968bf5

vercel Bot deployed to Preview March 9, 2026 20:53 View deployment

brkalow approved these changes Mar 9, 2026

View reviewed changes

dstaley requested a review from a team March 9, 2026 22:12

mzhong9723 approved these changes Mar 9, 2026

View reviewed changes

dstaley merged commit 3e63793 into main Mar 10, 2026
68 of 70 checks passed

dstaley deleted the ds.feat/annual-only branch March 10, 2026 00:33

clerk-cookie mentioned this pull request Mar 10, 2026

ci(repo): Version packages #8016

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(clerk-js,localizations,shared,ui): Annual-only plans#8012

feat(clerk-js,localizations,shared,ui): Annual-only plans#8012
dstaley merged 7 commits into
mainfrom
ds.feat/annual-only

dstaley commented Mar 9, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

vercel Bot commented Mar 9, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Mar 9, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Mar 9, 2026 •

edited

Loading

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

pkg-pr-new Bot commented Mar 9, 2026 •

edited

Loading

Uh oh!

mzhong9723 Mar 9, 2026

Uh oh!

dstaley Mar 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

dstaley commented Mar 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing Instructions

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

vercel Bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

❌ Failed checks (1 warning)

Uh oh!

pkg-pr-new Bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mzhong9723 Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

dstaley Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dstaley commented Mar 9, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented Mar 9, 2026 •

edited

Loading

changeset-bot Bot commented Mar 9, 2026 •

edited

Loading

coderabbitai Bot commented Mar 9, 2026 •

edited

Loading

pkg-pr-new Bot commented Mar 9, 2026 •

edited

Loading