chore(repo): Hide @experimental from typedoc rendering #6651
Conversation
This reverts commit 659a1bb60c3a4cf18e3bad1b04c544e144b49a75.
This reverts commit a36bdf7df3c42a47829139af3da330d7369c5890.
This reverts commit 54c8c22b1e3841122392014b08b4fa16af6ecf6f.
🦋 Changeset detectedLatest commit: b36edf5 The changes in this PR will be included in the next version bump. This PR includes changesets to release 22 packages
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 |
WalkthroughUpdated TypeDoc tooling and many JSDoc comments across packages: standardized @experimental phrasing and dependency-pinning guidance, enhanced commerce type docs, added Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant TD as TypeDoc Renderer
participant Theme as MarkdownThemeContext
participant Partial as partials.memberWithGroups
participant Super as superPartials.memberWithGroups
TD->>Theme: render member with groups
Theme->>Partial: partials.memberWithGroups(member)
Note over Partial: Step 1 — filter out Methods group
Partial->>Partial: locate Accessors group in filtered set
alt Accessors present with children
Partial->>Partial: compute groupsWithoutAccessors
Partial->>Super: render non-accessor groups (groupsWithoutAccessors)
Note right of Partial: render Accessors as "Properties" table\n(columns: Property, Type, Description)
else No Accessors
Partial->>Super: render filtered groups
end
Note over Theme: restore original groups after render
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests
Comment |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
@clerk/agent-toolkit
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/elements
@clerk/clerk-expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/clerk-react
@clerk/react-router
@clerk/remix
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/themes
@clerk/types
@clerk/upgrade
@clerk/vue
commit: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (7)
package.json (1)
55-55: Use Vitest’s canonical update flag.Prefer
-u(or--update) over--ufor clarity and future-proofing.Apply:
- "test:typedoc:update": "pnpm typedoc:generate && cd ./.typedoc && vitest --u", + "test:typedoc:update": "pnpm typedoc:generate && cd ./.typedoc && vitest -u",packages/clerk-js/src/core/resources/__tests__/README-snapshots.md (4)
72-73: Align snapshot update command with repo tooling (pnpm + Vitest).Docs currently suggest
npm test -- --update-snapshots. In this repo we use pnpm and Vitest; recommendpnpm test -- -u.-5. **Update When Intentional**: When you intentionally change a resource's structure, update the snapshots using `npm test -- --update-snapshots`. +5. **Update When Intentional**: When you intentionally change a resource's structure, update the snapshots using `pnpm test -- -u`.
77-85: Use pnpm in examples and the short update flag.Keep CLI examples consistent with package manager and Vitest flags.
-# Run all resource tests -npm test -- src/core/resources/__tests__/*.spec.ts +# Run all resource tests +pnpm test -- src/core/resources/__tests__/*.spec.ts -# Run specific test file -npm test -- src/core/resources/__tests__/Client.spec.ts +# Run specific test file +pnpm test -- src/core/resources/__tests__/Client.spec.ts -# Update snapshots when structure changes intentionally -npm test -- --update-snapshots +# Update snapshots when structure changes intentionally +pnpm test -- -u
37-43: Avoidas anyin examples; prefer minimal types or Partial.Using
as anyin docs encourages bypassing type safety. SuggestPartial<ResourceName>or explicit optional props.-} as any); // Use 'as any' if TypeScript complains about null values +} as Partial<ResourceName>); // Allow null/empty for snapshot variants without bypassing types
64-66: Add reminder to restore timers to prevent test bleed.When using fake timers, always revert.
1. **Use Fixed Dates**: Use `vi.useFakeTimers()` and `vi.setSystemTime()` to ensure consistent timestamps in snapshots. + Remember to call `vi.useRealTimers()` in `afterEach` to avoid leaking fake timers across tests..typedoc/custom-theme.mjs (2)
239-251: Simplify experimental group handling and clarify naming.Early-return logic is fine; rename for clarity.
- const experimentalGroups = originalGroups?.find(g => + const experimentalGroups = originalGroups?.find(g => g?.owningReflection?.comment?.modifierTags.has('@experimental'), ); - if (experimentalGroups) { - const groupsWithoutMethods = originalGroups?.filter(g => g.title === 'Properties'); - - customizedModel.groups = groupsWithoutMethods; + if (experimentalGroups) { + const propertiesOnlyGroups = originalGroups?.filter(g => g.title === 'Properties'); + customizedModel.groups = propertiesOnlyGroups; const nonAccessorOutput = superPartials.memberWithGroups(customizedModel, options); customizedModel.groups = originalGroups; return nonAccessorOutput; }
259-262: Remove unreachable duplicate check.This
if (experimentalGroups)path cannot be hit due to the earlier early return.- if (experimentalGroups) { - return nonAccessorOutput; - }
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
.typedoc/custom-plugin.mjs(2 hunks).typedoc/custom-theme.mjs(2 hunks)package.json(2 hunks)packages/clerk-js/src/core/resources/__tests__/README-snapshots.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
packages/clerk-js/src/core/resources/__tests__/README-snapshots.mdpackage.json
🪛 LanguageTool
packages/clerk-js/src/core/resources/__tests__/README-snapshots.md
[grammar] ~100-~100: There might be a mistake here.
Context: ...etermine if the change is intentional**: - If yes: Update the snapshot with `--upda...
(QB_NEW_EN)
[grammar] ~101-~101: There might be a mistake here.
Context: ...: - If yes: Update the snapshot with --update-snapshots - If no: Fix the code to maintain backward...
(QB_NEW_EN)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)
- GitHub Check: Formatting | Dedupe | Changeset
- GitHub Check: Build Packages
- GitHub Check: semgrep/ci
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (2)
package.json (1)
36-36: Confirm billing E2E app ID scopePlease verify whether it’s intentional to run your billing integration tests against only the withBilling.next.appRouter variant, since there are additional Billing presets defined. Narrowing from a wildcard to a single app ID will skip:
integration/presets/longRunningApps.ts (lines 45, 47, 72):
• withBilling.next.appRouter
• withBilling.vue.vite
• withBilling.astro.nodeAll other @billing tests (e.g. pricing-table.test.ts using
testAgainstRunningApps({ withEnv: [envs.withBilling] })) expect to exercise every “withBilling.*” scenario, not just the Next App Router variant.If you intend to cover every Billing stack, consider updating the test script to use a wildcard (e.g.
E2E_APP_ID=withBilling.*) or adding separate commands per variant. Otherwise, confirm that limiting to withBilling.next.appRouter matches your intended test surface..typedoc/custom-plugin.mjs (1)
1-1: Enabling // @ts-check is a good safety net.
This reverts commit b037879.
panteliselef
force-pushed
the
elef/remove-experimental-from-typedoc
branch
from
8c1cd5e to
def7a20
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
.typedoc/custom-theme.mjs (2)
65-66: Fix ESLint: remove unused variable.
lineis never used. The refactor above eliminates it by avoiding the destructure. If you keep the current structure, at minimum rename to_lineor remove the destructure.
245-257: Handle missing “Properties” group; avoid rendering nothing.If the class/interface is experimental but has no “Properties” group, this returns an empty section. Guard and fall back to default rendering (or decide on another group).
- if (experimentalGroups) { - const groupsWithoutMethods = originalGroups?.filter(g => g.title === 'Properties'); - - customizedModel.groups = groupsWithoutMethods; - const nonAccessorOutput = superPartials.memberWithGroups(customizedModel, options); - customizedModel.groups = originalGroups; - - return nonAccessorOutput; - } + if (experimentalGroups) { + const propertiesGroups = originalGroups?.filter(g => g.title === 'Properties') ?? []; + if (propertiesGroups.length === 0) { + // Nothing to filter to; render default groups instead. + return superPartials.memberWithGroups(customizedModel, options); + } + customizedModel.groups = propertiesGroups; + const nonAccessorOutput = superPartials.memberWithGroups(customizedModel, options); + customizedModel.groups = originalGroups; + return nonAccessorOutput; + }
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
.typedoc/custom-plugin.mjs(1 hunks).typedoc/custom-theme.mjs(2 hunks)
✅ Files skipped from review due to trivial changes (1)
- .typedoc/custom-plugin.mjs
🧰 Additional context used
🪛 ESLint
.typedoc/custom-theme.mjs
[error] 65-65: 'line' is assigned a value but never used. Allowed unused vars must match /^_/u.
(no-unused-vars)
[error] 65-65: 'line' is assigned a value but never used. Allowed unused vars must match /^_/u.
(@typescript-eslint/no-unused-vars)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (26)
- GitHub Check: Integration Tests (billing, chrome)
- GitHub Check: Integration Tests (nextjs, chrome, 14)
- GitHub Check: Integration Tests (machine, chrome)
- GitHub Check: Integration Tests (react-router, chrome)
- GitHub Check: Integration Tests (nuxt, chrome)
- GitHub Check: Integration Tests (expo-web, chrome)
- GitHub Check: Integration Tests (nextjs, chrome, 15)
- GitHub Check: Integration Tests (tanstack-react-router, chrome)
- GitHub Check: Integration Tests (tanstack-react-start, chrome)
- GitHub Check: Integration Tests (vue, chrome)
- GitHub Check: Integration Tests (astro, chrome)
- GitHub Check: Integration Tests (localhost, chrome)
- GitHub Check: Integration Tests (elements, chrome)
- GitHub Check: Integration Tests (sessions, chrome)
- GitHub Check: Integration Tests (ap-flows, chrome)
- GitHub Check: Integration Tests (generic, chrome)
- GitHub Check: Integration Tests (quickstart, chrome)
- GitHub Check: Integration Tests (express, chrome)
- GitHub Check: Unit Tests (18, --filter=@clerk/astro --filter=@clerk/backend --filter=@clerk/express --filter=@c...
- GitHub Check: Publish with pkg-pr-new
- GitHub Check: Unit Tests (22, **)
- GitHub Check: Static analysis
- GitHub Check: semgrep/ci
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.typedoc/custom-theme.mjs (1)
426-434: Harden parsing of@unionReturnHeadings; avoid crashes on invalid JSON.
JSON.parseon user-authored tag content is brittle. Wrap in try/catch and default gracefully.- const content = this.helpers.getCommentParts(unionReturnHeadings.content); - const unionHeadings = JSON.parse(content); + let unionHeadings = []; + try { + const content = this.helpers.getCommentParts(unionReturnHeadings.content); + const parsed = JSON.parse(content); + unionHeadings = Array.isArray(parsed) ? parsed : []; + } catch { + unionHeadings = []; + } @@ - headings.push(unionHeadings[i]); + headings.push(unionHeadings[i] ?? `Variant ${i + 1}`);
♻️ Duplicate comments (1)
.typedoc/custom-theme.mjs (1)
49-68: Do not mutate Comment; clone (or locally shadow) and guard API calls.Mutating
modelwithremoveModifier/removeTagscan leak side effects into other partials. Also,hasModifier/removeTags/removeModifiermay be undefined across TypeDoc versions; guard them and fall back to safeblockTagsfiltering.Apply:
- comment: (model, options) => { - if ( - model.hasModifier('@experimental') && - [ReflectionKind.Class, ReflectionKind.Interface].includes(this.page?.model?.kind) - ) { - model.removeModifier('@experimental'); - model.removeTags('@example'); - model.removeTags('@see'); - - const res = superPartials.comment(model, options); - - return res.replace(/^\n+/, ''); - } - return superPartials.comment(model, options); - }, + comment: (model, options) => { + if ( + model?.hasModifier?.('@experimental') && + [ReflectionKind.Class, ReflectionKind.Interface].includes(this.page?.model?.kind) + ) { + // Avoid side effects: operate on a cloned/shadowed comment. + const temp = + typeof model.clone === 'function' + ? model.clone() + : (() => { + const shallow = Object.assign(Object.create(Object.getPrototypeOf(model)), model); + if (Array.isArray(shallow.blockTags)) shallow.blockTags = [...shallow.blockTags]; + if (shallow.modifierTags instanceof Set) shallow.modifierTags = new Set(shallow.modifierTags); + return shallow; + })(); + // Strip experimental + noisy sections with guards for older/newer TypeDoc APIs. + temp.removeModifier?.('@experimental'); + if (typeof temp.removeTags === 'function') { + temp.removeTags('@example'); + temp.removeTags('@see'); + } else if (Array.isArray(temp.blockTags)) { + temp.blockTags = temp.blockTags.filter(t => !['@example', '@see'].includes(t.tag || t.name)); + } + const res = superPartials.comment(temp, options); + return res.replace(/^\n+/, ''); + } + return superPartials.comment(model, options); + },To verify, run the TypeDoc snapshot tests for pages that render comments both before and after
commentto ensure no tag leakage or missing content.
🧹 Nitpick comments (1)
.typedoc/custom-theme.mjs (1)
447-453: Union comment memoization key can collide across pages; include reflection IDs.
${model.name}-${decl.name}is not globally unique. Use stable reflection IDs to avoid cross-contamination.- const id = `${model.name}-${decl.name}`; + const pageId = this.page?.model?.id ?? 'p'; + const modelId = typeof model?.id === 'number' ? model.id : model?.name; + const declId = typeof decl?.id === 'number' ? decl.id : decl?.name; + const id = `${pageId}-${modelId}-${declId}`;
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
.typedoc/custom-theme.mjs(2 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)
- GitHub Check: Formatting | Dedupe | Changeset
- GitHub Check: Build Packages
- GitHub Check: semgrep/ci
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
| // When an interface extends another interface, typedoc will generate a "Methods" group | ||
| // We want to hide this group from being rendered | ||
| const groupsWithoutMethods = originalGroups?.filter(g => g.title !== 'Methods'); | ||
|
|
||
| // Extract the Accessors group (if any) and prevent default rendering for it | ||
| const accessorsGroup = groupsWithoutMethods?.find(g => g.title === 'Accessors'); | ||
| const groupsWithoutAccessors = groupsWithoutMethods?.filter(g => g.title !== 'Accessors'); |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Hiding every “Methods” group is too broad; restrict to interfaces (extends case).
As written, you’ll also remove legitimate methods from classes. Limit the filter to interface pages only.
- const groupsWithoutMethods = originalGroups?.filter(g => g.title !== 'Methods');
+ const isInterface = customizedModel?.kind === ReflectionKind.Interface;
+ const groupsWithoutMethods = isInterface
+ ? originalGroups?.filter(g => g.title !== 'Methods')
+ : originalGroups;Build a sample class with methods in the docs to confirm the Methods section remains visible.
🏁 Script executed:
#!/bin/bash
# Locate ReflectionKind usage and import in custom-theme.mjs
grep -R "ReflectionKind" -n .typedoc/custom-theme.mjs || true
# Locate where customizedModel is defined or passed in
grep -R "customizedModel" -n .typedoc/custom-theme.mjs || trueLength of output: 1133
Restrict “Methods” filtering to interfaces only
Only omit the “Methods” group when customizedModel.kind === ReflectionKind.Interface; leave it intact for classes.
- const groupsWithoutMethods = originalGroups?.filter(g => g.title !== 'Methods');
+ const isInterface = customizedModel.kind === ReflectionKind.Interface;
+ const groupsWithoutMethods = isInterface
+ ? originalGroups.filter(g => g.title !== 'Methods')
+ : originalGroups;[matches .typedoc/custom-theme.mjs:243]
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| // When an interface extends another interface, typedoc will generate a "Methods" group | |
| // We want to hide this group from being rendered | |
| const groupsWithoutMethods = originalGroups?.filter(g => g.title !== 'Methods'); | |
| // Extract the Accessors group (if any) and prevent default rendering for it | |
| const accessorsGroup = groupsWithoutMethods?.find(g => g.title === 'Accessors'); | |
| const groupsWithoutAccessors = groupsWithoutMethods?.filter(g => g.title !== 'Accessors'); | |
| // When an interface extends another interface, typedoc will generate a "Methods" group | |
| // We want to hide this group from being rendered | |
| const isInterface = customizedModel.kind === ReflectionKind.Interface; | |
| const groupsWithoutMethods = isInterface | |
| ? originalGroups.filter(g => g.title !== 'Methods') | |
| : originalGroups; | |
| // Extract the Accessors group (if any) and prevent default rendering for it | |
| const accessorsGroup = groupsWithoutMethods?.find(g => g.title === 'Accessors'); | |
| const groupsWithoutAccessors = groupsWithoutMethods?.filter(g => g.title !== 'Accessors'); |
🤖 Prompt for AI Agents
In .typedoc/custom-theme.mjs around lines 243 to 249, the current code always
filters out the "Methods" group; change this to only filter when the model is an
interface by wrapping the "Methods" removal in a conditional that checks if
customizedModel.kind === ReflectionKind.Interface (ensure ReflectionKind is
imported/available in this module). Leave the "Accessors" extraction and
subsequent filtering unchanged so accessors are still handled the same way.
alexisintech
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
.typedoc/custom-theme.mjs (2)
64-66: Don’t mutatemodel.typeParametersinsignature; restore after render.Side effects can leak into downstream partials. Save and restore.
- const customizedModel = model; - customizedModel.typeParameters = undefined; + const customizedModel = model; + const originalTypeParameters = customizedModel.typeParameters; + customizedModel.typeParameters = undefined; @@ - return output; + // Restore to avoid side effects + customizedModel.typeParameters = originalTypeParameters; + return output;Also applies to: 95-96
296-313:declarationpartial: restoretypeParametersafter render.Unsetting without restore may affect later render steps.
declaration: (model, options = { headingLevel: 2, nested: false }) => { @@ const customizedModel = model; - customizedModel.typeParameters = undefined; + const originalTypeParameters = customizedModel.typeParameters; + customizedModel.typeParameters = undefined; @@ - return output; + // Restore + customizedModel.typeParameters = originalTypeParameters; + return output;
♻️ Duplicate comments (1)
.typedoc/custom-theme.mjs (1)
217-236: Avoid persistent mutations inmemberWithGroups; also limit “Methods” removal to interfaces.Restore
typeParametersand only drop “Methods” for interfaces; classes should keep method sections.memberWithGroups: (model, options) => { const customizedModel = model; - customizedModel.typeParameters = undefined; + const originalTypeParameters = customizedModel.typeParameters; + customizedModel.typeParameters = undefined; const originalGroups = customizedModel.groups; - - // When an interface extends another interface, typedoc will generate a "Methods" group - // We want to hide this group from being rendered - const groupsWithoutMethods = originalGroups?.filter(g => g.title !== 'Methods'); + // Hide "Methods" only for interfaces that extend others + const isInterface = customizedModel?.kind === ReflectionKind.Interface; + const groupsWithoutMethods = isInterface + ? originalGroups?.filter(g => g.title !== 'Methods') + : originalGroups; @@ customizedModel.groups = originalGroups; + customizedModel.typeParameters = originalTypeParameters;
🧹 Nitpick comments (4)
.typedoc/custom-theme.mjs (1)
406-416: Harden@unionReturnHeadingsparsing.Invalid JSON in docs will currently throw and break rendering. Wrap
JSON.parsedefensively.- const content = this.helpers.getCommentParts(unionReturnHeadings.content); - const unionHeadings = JSON.parse(content); + const content = this.helpers.getCommentParts(unionReturnHeadings.content); + let unionHeadings = []; + try { + const parsed = JSON.parse(content); + if (Array.isArray(parsed)) { + unionHeadings = parsed; + } + } catch { + // Ignore invalid headings; fall back to no tabs + }packages/types/src/clerk.ts (3)
241-243: Billing experimental note: tighten copy and move guidance to @remarksShorten the summary line and shift the pinning advice into a
@remarksblock for better TypeDoc summaries and line-length conformity.- /** - * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://docs.renovatebot.com/dependency-pinning/#what-is-dependency-pinning) the SDK version and the clerk-js version to avoid breaking changes. - */ + /** + * @experimental Public beta; subject to change. + * @remarks To avoid breaking changes, [pin](https://docs.renovatebot.com/dependency-pinning/#what-is-dependency-pinning) both the SDK and clerk-js versions. + */
484-486: Incorrect @param on a zero-argument method
__experimental_prefetchOrganizationSwitchertakes no parameters, but the docblock documents@param props. Remove it to avoid misleading TypeDoc output./** * Prefetches the data displayed by an organization switcher. * It can be used when `mountOrganizationSwitcher({ asStandalone: true})`, to avoid unwanted loading states. - * - * @experimental This experimental API is subject to change. - * @param props Optional user verification configuration parameters. + * + * @experimental This experimental API is subject to change. */
1867-1869: Unify experimental/beta copy across billing-related typesReplace the repeated verbose @experimental sentence with the concise block below; apply to packages/types/src/clerk.ts at lines 241, 1867, 1886, 1907, 1929, 1953, 1969.
-/** - * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://docs.renovatebot.com/dependency-pinning/#what-is-dependency-pinning) the SDK version and the clerk-js version to avoid breaking changes. - */ +/** + * @experimental Public beta; subject to change. + * @remarks To avoid breaking changes, [pin](https://docs.renovatebot.com/dependency-pinning/#what-is-dependency-pinning) both the SDK and clerk-js versions. + */
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (26)
.typedoc/custom-theme.mjs(1 hunks)packages/backend/src/api/endpoints/BillingApi.ts(4 hunks)packages/backend/src/api/resources/CommercePlan.ts(1 hunks)packages/backend/src/api/resources/CommerceSubscription.ts(1 hunks)packages/backend/src/api/resources/CommerceSubscriptionItem.ts(1 hunks)packages/backend/src/api/resources/Feature.ts(1 hunks)packages/backend/src/api/resources/JSON.ts(2 hunks)packages/clerk-js/src/core/clerk.ts(2 hunks)packages/expo/src/provider/ClerkProvider.tsx(1 hunks)packages/expo/src/provider/singleton/types.ts(1 hunks)packages/react/src/components/CheckoutButton.tsx(2 hunks)packages/react/src/components/PlanDetailsButton.tsx(2 hunks)packages/react/src/components/SubscriptionDetailsButton.tsx(2 hunks)packages/react/src/components/uiComponents.tsx(4 hunks)packages/react/src/hooks/useClerkSignal.ts(2 hunks)packages/shared/src/jwtPayloadParser.ts(1 hunks)packages/shared/src/react/hooks/useOrganization.tsx(2 hunks)packages/shared/src/react/hooks/useSubscription.tsx(1 hunks)packages/shared/src/react/types.ts(2 hunks)packages/types/src/apiKeys.ts(1 hunks)packages/types/src/clerk.ts(8 hunks)packages/types/src/commerce.ts(10 hunks)packages/types/src/json.ts(13 hunks)packages/types/src/jwtv2.ts(2 hunks)packages/types/src/state.ts(1 hunks)typedoc.config.mjs(3 hunks)
✅ Files skipped from review due to trivial changes (17)
- packages/react/src/components/SubscriptionDetailsButton.tsx
- packages/expo/src/provider/ClerkProvider.tsx
- packages/react/src/hooks/useClerkSignal.ts
- packages/backend/src/api/resources/Feature.ts
- packages/backend/src/api/resources/JSON.ts
- packages/types/src/apiKeys.ts
- packages/clerk-js/src/core/clerk.ts
- packages/types/src/state.ts
- packages/react/src/components/PlanDetailsButton.tsx
- packages/types/src/json.ts
- packages/expo/src/provider/singleton/types.ts
- packages/shared/src/react/hooks/useSubscription.tsx
- packages/shared/src/react/hooks/useOrganization.tsx
- packages/backend/src/api/resources/CommerceSubscriptionItem.ts
- packages/react/src/components/uiComponents.tsx
- packages/shared/src/jwtPayloadParser.ts
- packages/types/src/jwtv2.ts
🚧 Files skipped from review as they are similar to previous changes (1)
- typedoc.config.mjs
🧰 Additional context used
📓 Path-based instructions (8)
**/*.{js,jsx,ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Profile and optimize critical paths
Validate all inputs and sanitize outputs
Implement proper logging with different levels
Files:
packages/backend/src/api/resources/CommerceSubscription.tspackages/backend/src/api/endpoints/BillingApi.tspackages/react/src/components/CheckoutButton.tsxpackages/shared/src/react/types.tspackages/backend/src/api/resources/CommercePlan.tspackages/types/src/commerce.tspackages/types/src/clerk.ts
**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
packages/backend/src/api/resources/CommerceSubscription.tspackages/backend/src/api/endpoints/BillingApi.tspackages/react/src/components/CheckoutButton.tsxpackages/shared/src/react/types.tspackages/backend/src/api/resources/CommercePlan.tspackages/types/src/commerce.tspackages/types/src/clerk.ts
packages/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
TypeScript is required for all packages
Files:
packages/backend/src/api/resources/CommerceSubscription.tspackages/backend/src/api/endpoints/BillingApi.tspackages/react/src/components/CheckoutButton.tsxpackages/shared/src/react/types.tspackages/backend/src/api/resources/CommercePlan.tspackages/types/src/commerce.tspackages/types/src/clerk.ts
packages/**/*.{ts,tsx,d.ts}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Packages should export TypeScript types alongside runtime code
Files:
packages/backend/src/api/resources/CommerceSubscription.tspackages/backend/src/api/endpoints/BillingApi.tspackages/react/src/components/CheckoutButton.tsxpackages/shared/src/react/types.tspackages/backend/src/api/resources/CommercePlan.tspackages/types/src/commerce.tspackages/types/src/clerk.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use proper TypeScript error types
**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoidanytype - preferunknownwhen type is uncertain, then narrow with type guards
Useinterfacefor object shapes that might be extended
Usetypefor unions, primitives, and computed types
Preferreadonlyproperties for immutable data structures
Useprivatefor internal implementation details
Useprotectedfor inheritance hierarchies
Usepublicexplicitly for clarity in public APIs
Preferreadonlyfor properties that shouldn't change after construction
Prefer composition and interfaces over deep inheritance chains
Use mixins for shared behavior across unrelated classes
Implement dependency injection for loose coupling
Let TypeScript infer when types are obvious
Useconst assertionsfor literal types:as const
Usesatisfiesoperator for type checking without widening
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Use type-only imports:import type { ... } from ...
Noanytypes without justification
Proper error handling with typed errors
Consistent use ofreadonlyfor immutable data
Proper generic constraints
No unused type parameters
Proper use of utility types instead of manual type construction
Type-only imports where possible
Proper tree-shaking friendly exports
No circular dependencies
Efficient type computations (avoid deep recursion)
Files:
packages/backend/src/api/resources/CommerceSubscription.tspackages/backend/src/api/endpoints/BillingApi.tspackages/react/src/components/CheckoutButton.tsxpackages/shared/src/react/types.tspackages/backend/src/api/resources/CommercePlan.tspackages/types/src/commerce.tspackages/types/src/clerk.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Support multiple Clerk environment variables (CLERK_, NEXT_PUBLIC_CLERK_, etc.) for configuration.
Files:
packages/backend/src/api/resources/CommerceSubscription.tspackages/backend/src/api/endpoints/BillingApi.tspackages/react/src/components/CheckoutButton.tsxpackages/shared/src/react/types.tspackages/backend/src/api/resources/CommercePlan.tspackages/types/src/commerce.tspackages/types/src/clerk.ts
**/*.{jsx,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
**/*.{jsx,tsx}: Use error boundaries in React components
Minimize re-renders in React components
**/*.{jsx,tsx}: Always use functional components with hooks instead of class components
Follow PascalCase naming for components:UserProfile,NavigationMenu
Keep components focused on a single responsibility - split large components
Limit component size to 150-200 lines; extract logic into custom hooks
Use composition over inheritance - prefer smaller, composable components
Export components as named exports for better tree-shaking
One component per file with matching filename and component name
Use useState for simple state management
Use useReducer for complex state logic
Implement proper state initialization
Use proper state updates with callbacks
Implement proper state cleanup
Use Context API for theme/authentication
Implement proper state selectors
Use proper state normalization
Implement proper state persistence
Use React.memo for expensive components
Implement proper useCallback for handlers
Use proper useMemo for expensive computations
Implement proper virtualization for lists
Use proper code splitting with React.lazy
Implement proper cleanup in useEffect
Use proper refs for DOM access
Implement proper event listener cleanup
Use proper abort controllers for fetch
Implement proper subscription cleanup
Use proper HTML elements
Implement proper ARIA attributes
Use proper heading hierarchy
Implement proper form labels
Use proper button types
Implement proper focus management
Use proper keyboard shortcuts
Implement proper tab order
Use proper skip links
Implement proper focus traps
Implement proper error boundaries
Use proper error logging
Implement proper error recovery
Use proper error messages
Implement proper error fallbacks
Use proper form validation
Implement proper error states
Use proper error messages
Implement proper form submission
Use proper form reset
Use proper component naming
Implement proper file naming
Use proper prop naming
Implement proper...
Files:
packages/react/src/components/CheckoutButton.tsx
**/*.tsx
📄 CodeRabbit inference engine (.cursor/rules/react.mdc)
**/*.tsx: Use proper type definitions for props and state
Leverage TypeScript's type inference where possible
Use proper event types for handlers
Implement proper generic types for reusable components
Use proper type guards for conditional rendering
Files:
packages/react/src/components/CheckoutButton.tsx
🧬 Code graph analysis (2)
packages/types/src/commerce.ts (3)
packages/types/src/pagination.ts (2)
ClerkPaginatedResponse(21-30)ClerkPaginationParams(35-46)packages/types/src/resource.ts (1)
ClerkResource(8-21)packages/clerk-js/src/core/resources/CommerceStatement.ts (1)
CommerceStatementGroup(39-58)
packages/types/src/clerk.ts (2)
packages/types/src/state.ts (1)
State(131-158)packages/clerk-js/src/core/state.ts (1)
State(19-68)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (9)
packages/backend/src/api/resources/CommerceSubscription.ts (1)
7-10: Docs tweak LGTM.Updated link text and standardized @experimental guidance read clearly; no API/RT changes.
packages/shared/src/react/types.ts (2)
118-121: Moving @experimental after @hidden is fine.Placement aligns with the new TypeDoc handling; no type changes.
145-149: Formatting/placement LGTM.Blank line + tag ordering is consistent with other blocks.
packages/backend/src/api/resources/CommercePlan.ts (1)
7-10: Docs tweak LGTM.Consistent with the Subscription resource changes; no runtime impact.
packages/react/src/components/CheckoutButton.tsx (2)
10-11: Intro text cleanup LGTM.Clearer description; matches usage constraints.
47-48: @experimental notice LGTM.Message + pinning guidance consistent with backend/types docs.
packages/backend/src/api/endpoints/BillingApi.ts (1)
28-29: Standardized @experimental copy across methods — OK.Consistent wording/link; no behavior change.
Also applies to: 39-40, 51-52, 62-63
packages/types/src/commerce.ts (1)
540-543: Unify @experimental phrasing to the linked form.
Replace occurrences of “pin to a specific version” with the linked Renovate-docs phrasing for consistency.
Locations: packages/types/src/commerce.ts — lines 195–197, 534–537, 540–543.
Verification: ranpnpm -w run test:typedoc:update— failed (turbo not found / node_modules missing). Re-run after installing deps to confirm typedoc rendering.packages/types/src/clerk.ts (1)
235-236: Marking__internal_stateas experimental looks goodDoc-only change; no API impact. Please confirm the TypeDoc theme renders the experimental badge as intended.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (7)
packages/types/src/commerce.ts (7)
150-156: Move @experimental to the bottom of this JSDoc so the descriptive text remains visible.Right now the prose (“Specifies the subscriber type…”) follows the tag and will be hidden when TypeDoc suppresses the block-tag content.
/** - * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://docs.renovatebot.com/dependency-pinning/#what-is-dependency-pinning) the SDK version and the clerk-js version to avoid breaking changes. - * - * Specifies the subscriber type this plan is designed for. - * - * Each plan is exclusively created for either individual users or organizations, - * and cannot be used interchangeably. + * Specifies the subscriber type this plan is designed for. + * + * Each plan is exclusively created for either individual users or organizations, + * and cannot be used interchangeably. + * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://docs.renovatebot.com/dependency-pinning/#what-is-dependency-pinning) the SDK version and the clerk-js version to avoid breaking changes. */ forPayerType: CommercePayerResourceType;
744-747: Doc/type mismatch: Date vs “Unix timestamp (milliseconds)”.Type is
Date | nullbut the doc says “Unix timestamp (milliseconds)”.- /** - * Unix timestamp (milliseconds) of when the free trial ends. - */ + /** + * The date when the free trial ends. + */ freeTrialEndsAt: Date | null;
301-304: Prefer optional property overstring | undefined.Use
walletType?: string;for consistency with the rest of the file and clearer intent.- walletType: string | undefined; + walletType?: string;
468-469: Resolve TODO: decide nullability ofpaymentSourceId.If a subscription item can exist without a bound payment source, make it
string | nulland document it; otherwise remove the TODO.- //TODO(@COMMERCE): should this be nullable ? - paymentSourceId: string; + /** + * The payment source ID used for this subscription item, or `null` if none is set. + */ + paymentSourceId: string | null;If null is not allowed, delete the TODO line instead.
724-727: Mixed timestamp representations (number vs Date).
planPeriodStart?: number(epoch ms) vsfreeTrialEndsAt: Date | null. Mixing primitives andDatecomplicates consumers. Pick one representation for new fields, or add a file-level note clarifying the contract.Also applies to: 744-747
520-522: Normalize the @experimental blurb wording/link.Some blocks use “pin the SDK version…” while others say “pin … to a specific version” without a link. Standardize to one phrasing and include the link everywhere (or nowhere).
Also applies to: 585-586
13-15: Separate@experimentalfrom the description — put the tag on its own JSDoc line.packages/types/src/commerce.ts contains many JSDoc blocks with
@experimentalfollowed by prose on the same line; change from:
/**
- @experimental This is an experimental API...
/
to:
/*- @experimental
- This is an experimental API...
*/
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (11)
package.json(2 hunks)packages/backend/src/api/endpoints/BillingApi.ts(4 hunks)packages/backend/src/api/resources/JSON.ts(2 hunks)packages/clerk-js/src/core/clerk.ts(2 hunks)packages/react/src/components/uiComponents.tsx(4 hunks)packages/shared/src/jwtPayloadParser.ts(1 hunks)packages/shared/src/react/hooks/useSubscription.tsx(1 hunks)packages/shared/src/react/types.ts(2 hunks)packages/types/src/clerk.ts(8 hunks)packages/types/src/commerce.ts(10 hunks)packages/types/src/json.ts(13 hunks)
✅ Files skipped from review due to trivial changes (4)
- packages/backend/src/api/resources/JSON.ts
- packages/backend/src/api/endpoints/BillingApi.ts
- packages/react/src/components/uiComponents.tsx
- packages/clerk-js/src/core/clerk.ts
🚧 Files skipped from review as they are similar to previous changes (6)
- packages/shared/src/jwtPayloadParser.ts
- package.json
- packages/shared/src/react/types.ts
- packages/types/src/json.ts
- packages/types/src/clerk.ts
- packages/shared/src/react/hooks/useSubscription.tsx
🧰 Additional context used
📓 Path-based instructions (6)
**/*.{js,jsx,ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Profile and optimize critical paths
Validate all inputs and sanitize outputs
Implement proper logging with different levels
Files:
packages/types/src/commerce.ts
**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
packages/types/src/commerce.ts
packages/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
TypeScript is required for all packages
Files:
packages/types/src/commerce.ts
packages/**/*.{ts,tsx,d.ts}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Packages should export TypeScript types alongside runtime code
Files:
packages/types/src/commerce.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use proper TypeScript error types
**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoidanytype - preferunknownwhen type is uncertain, then narrow with type guards
Useinterfacefor object shapes that might be extended
Usetypefor unions, primitives, and computed types
Preferreadonlyproperties for immutable data structures
Useprivatefor internal implementation details
Useprotectedfor inheritance hierarchies
Usepublicexplicitly for clarity in public APIs
Preferreadonlyfor properties that shouldn't change after construction
Prefer composition and interfaces over deep inheritance chains
Use mixins for shared behavior across unrelated classes
Implement dependency injection for loose coupling
Let TypeScript infer when types are obvious
Useconst assertionsfor literal types:as const
Usesatisfiesoperator for type checking without widening
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Use type-only imports:import type { ... } from ...
Noanytypes without justification
Proper error handling with typed errors
Consistent use ofreadonlyfor immutable data
Proper generic constraints
No unused type parameters
Proper use of utility types instead of manual type construction
Type-only imports where possible
Proper tree-shaking friendly exports
No circular dependencies
Efficient type computations (avoid deep recursion)
Files:
packages/types/src/commerce.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Support multiple Clerk environment variables (CLERK_, NEXT_PUBLIC_CLERK_, etc.) for configuration.
Files:
packages/types/src/commerce.ts
🧬 Code graph analysis (1)
packages/types/src/commerce.ts (2)
packages/types/src/pagination.ts (2)
ClerkPaginatedResponse(21-30)ClerkPaginationParams(35-46)packages/types/src/resource.ts (1)
ClerkResource(8-21)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)
- GitHub Check: Build Packages
- GitHub Check: Formatting | Dedupe | Changeset
- GitHub Check: semgrep/ci
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (2)
packages/types/src/commerce.ts (2)
13-15: LGTM on converting @experimental to a block tag throughout.Consistent application enables
notRenderedTagsto hide the right content in TypeDoc.Also applies to: 18-19, 23-24, 28-29, 33-34, 38-39, 43-44, 48-49, 53-54, 59-60, 64-65, 69-70, 81-82, 85-86, 91-92, 95-96, 103-104, 107-108, 118-119, 122-123, 126-127, 130-131, 134-135, 138-139, 142-143, 146-147, 150-151, 159-160, 163-164, 167-168, 171-172, 175-176, 179-180, 183-183, 223-224, 228-229, 233-234, 237-238, 243-244, 247-248, 251-252, 257-258, 262-263, 269-270, 321-322, 325-326, 329-330, 333-334, 339-340, 344-345, 349-350, 354-355, 358-359, 362-363, 370-371, 375-376, 379-380, 383-384, 393-394, 398-399, 403-404, 409-410, 414-415, 418-419, 422-423, 432-435, 448-449, 455-456, 460-461, 466-467, 471-472, 475-476, 479-480, 483-484, 487-488, 491-492, 495-496, 499-500, 503-504, 507-508, 511-512, 516-517, 585-586, 609-610, 647-648, 651-652, 655-656, 663-664, 696-697, 754-755, 758-759, 762-763, 766-767, 770-771, 774-775, 778-779, 782-783, 790-791, 794-795
374-381: Verify TypeDoc: ensure @deprecated still renders when @experimental is hidden.The JSDoc block in packages/types/src/commerce.ts (lines 374–381) combines @deprecated and @experimental — confirm your TypeDoc config uses notRenderedTags only for "@experimental" (not "@deprecated"/excludeTags) and that the generated docs contain the deprecation text "Use
subscriptionIteminstead" (e.g. build docs and grep output: rg -n "Use `subscriptionItem` instead" --glob "docs/**").
|
@panteliselef updated the PR description to be aligned with all the changes, once my PR is merged into yours! |
panteliselef
changed the title
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
.changeset/quiet-signs-peel.md (1)
10-10: Clarify the release note as docs‑only and call out the specific TypeDoc changes.Make the entry explicit to reduce noise for consumers.
Apply this diff:
-Update jsdocs mentions of `@experimental` tag. +Docs: Update JSDoc use of `@experimental`. + +- Treat `@experimental` as a block tag in TypeDoc so it can be hidden via `notRenderedTags`. +- Move `@experimental` to the bottom of comments so only trailing text is captured. +- Enable `hideOverrides: true` in the TypeDoc config to hide the “Overrides” column. + +No runtime or public API/typing changes; docs generation only.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
.changeset/quiet-signs-peel.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
.changeset/**
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Automated releases must use Changesets.
Files:
.changeset/quiet-signs-peel.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (2)
.changeset/quiet-signs-peel.md (2)
1-8: Valid changeset structure; patch bumps across impacted packages look fine.Front‑matter and multi‑package patch bumps align with a docs‑only change.
2-7: Confirm packages in .changeset/quiet-signs-peel.md actually changed — remove unchanged entries.
Automated verification failed due to script errors; I couldn't determine which packages have file changes. Run the verification locally and remove any of these packages from the changeset if they have no file changes: @clerk/clerk-js, @clerk/backend, @clerk/shared, @clerk/clerk-react, @clerk/types, @clerk/clerk-expo.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
packages/backend/src/api/factory.ts (1)
56-58: Keep docs visible after hiding @experimental — add a summary line above the tagSince
@experimentalis now treated as a block tag and likely hidden vianotRenderedTags, this block will render no visible docs forbilling. Add a short description above the tag; keep the tag last so only its trailing text is hidden.Apply this diff:
- /** - * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. - */ + /** + * Billing API client for Clerk backend usage. + * @experimental Public beta; the API may change. Pin both the SDK and clerk-js versions to avoid breaking changes. See [pin](/docs/pinning). + */
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (14)
packages/backend/src/api/endpoints/BillingApi.ts(5 hunks)packages/backend/src/api/factory.ts(1 hunks)packages/backend/src/api/resources/CommercePlan.ts(1 hunks)packages/backend/src/api/resources/CommerceSubscription.ts(1 hunks)packages/backend/src/api/resources/CommerceSubscriptionItem.ts(1 hunks)packages/backend/src/api/resources/Feature.ts(1 hunks)packages/backend/src/api/resources/JSON.ts(2 hunks)packages/react/src/components/CheckoutButton.tsx(2 hunks)packages/react/src/components/PlanDetailsButton.tsx(2 hunks)packages/react/src/components/SubscriptionDetailsButton.tsx(2 hunks)packages/shared/src/react/hooks/useSubscription.tsx(1 hunks)packages/types/src/clerk.ts(8 hunks)packages/types/src/commerce.ts(10 hunks)packages/types/src/json.ts(13 hunks)
✅ Files skipped from review due to trivial changes (1)
- packages/backend/src/api/resources/CommerceSubscriptionItem.ts
🚧 Files skipped from review as they are similar to previous changes (12)
- packages/backend/src/api/endpoints/BillingApi.ts
- packages/shared/src/react/hooks/useSubscription.tsx
- packages/react/src/components/SubscriptionDetailsButton.tsx
- packages/react/src/components/CheckoutButton.tsx
- packages/types/src/commerce.ts
- packages/backend/src/api/resources/JSON.ts
- packages/backend/src/api/resources/Feature.ts
- packages/react/src/components/PlanDetailsButton.tsx
- packages/backend/src/api/resources/CommercePlan.ts
- packages/backend/src/api/resources/CommerceSubscription.ts
- packages/types/src/json.ts
- packages/types/src/clerk.ts
🧰 Additional context used
📓 Path-based instructions (6)
**/*.{js,jsx,ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Profile and optimize critical paths
Validate all inputs and sanitize outputs
Implement proper logging with different levels
Files:
packages/backend/src/api/factory.ts
**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
packages/backend/src/api/factory.ts
packages/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
TypeScript is required for all packages
Files:
packages/backend/src/api/factory.ts
packages/**/*.{ts,tsx,d.ts}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Packages should export TypeScript types alongside runtime code
Files:
packages/backend/src/api/factory.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use proper TypeScript error types
**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoidanytype - preferunknownwhen type is uncertain, then narrow with type guards
Useinterfacefor object shapes that might be extended
Usetypefor unions, primitives, and computed types
Preferreadonlyproperties for immutable data structures
Useprivatefor internal implementation details
Useprotectedfor inheritance hierarchies
Usepublicexplicitly for clarity in public APIs
Preferreadonlyfor properties that shouldn't change after construction
Prefer composition and interfaces over deep inheritance chains
Use mixins for shared behavior across unrelated classes
Implement dependency injection for loose coupling
Let TypeScript infer when types are obvious
Useconst assertionsfor literal types:as const
Usesatisfiesoperator for type checking without widening
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Use type-only imports:import type { ... } from ...
Noanytypes without justification
Proper error handling with typed errors
Consistent use ofreadonlyfor immutable data
Proper generic constraints
No unused type parameters
Proper use of utility types instead of manual type construction
Type-only imports where possible
Proper tree-shaking friendly exports
No circular dependencies
Efficient type computations (avoid deep recursion)
Files:
packages/backend/src/api/factory.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Support multiple Clerk environment variables (CLERK_, NEXT_PUBLIC_CLERK_, etc.) for configuration.
Files:
packages/backend/src/api/factory.ts
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
# Conflicts: # packages/types/src/commerce.ts
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/types/src/commerce.ts (1)
660-686: Enforce gateway requirement in ConfirmCheckoutParams.Docs say gateway is required with
paymentTokenoruseTestCard, but the types don’t enforce it.export type ConfirmCheckoutParams = | { /** * The ID of a saved payment source to use for this checkout. */ - paymentSourceId?: string; + paymentSourceId: string; } | { /** * A token representing payment details, usually from a payment form. **Requires** `gateway` to be provided. */ - paymentToken?: string; + paymentToken: string; /** * The payment gateway to use. For example, `'stripe'` or `'paypal'`. **Required** if `paymentToken` or `useTestCard` is provided. */ - gateway?: PaymentGateway; + gateway: PaymentGateway; } | { /** * The payment gateway to use. For example, `'stripe'` or `'paypal'`. **Required** if `paymentToken` or `useTestCard` is provided. */ - gateway?: PaymentGateway; + gateway: PaymentGateway; /** * If true, uses a test card for the checkout. **Requires** `gateway` to be provided. */ - useTestCard?: boolean; + useTestCard: true; };
🧹 Nitpick comments (13)
packages/backend/src/api/resources/Feature.ts (1)
6-6: Nit: tighten wording and name the package explicitly.Clearer grammar and precise package name improve the guidance.
Apply this diff:
- * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. + * @experimental Billing is in public beta and subject to change. We recommend [pinning](https://clerk.com/docs/pinning) your SDK and `@clerk/clerk-js` versions to avoid breaking changes.packages/types/src/commerce.ts (5)
150-157: Place @experimental at the bottom of the block to avoid hiding the description.Having
@experimentalfirst turns the whole comment into the tag payload, so TypeDoc will hide the actual description.- /** - * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. - * - * Specifies the subscriber type this plan is designed for. - * - * Each plan is exclusively created for either individual users or organizations, - * and cannot be used interchangeably. - */ + /** + * Specifies the subscriber type this plan is designed for. + * + * Each plan is exclusively created for either individual users or organizations, + * and cannot be used interchangeably. + * + * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. + */
739-742: Fix type/docs mismatch for freeTrialEndsAt.Doc says “Unix timestamp (milliseconds)” but the type is
Date | null.- /** - * Unix timestamp (milliseconds) of when the free trial ends. - */ - freeTrialEndsAt: Date | null; + /** + * The date when the free trial ends. + */ + freeTrialEndsAt: Date | null;
301-304: Prefer optional overstring | undefinedfor walletType.Aligns with typical TS style and runtime shape (field may be absent).
- walletType: string | undefined; + walletType?: string;
61-67: Unify payer type tokens ('org'vs'organization').
CommercePayerResourceTypeuses'org', whileForPayerTypeuses'organization'. This inconsistency leaks into APIs and docs.Would you like to standardize on
'organization'and add a deprecated alias for'org'to ease migration?
461-465: Resolve TODO: nullable paymentSourceId.If the field can be absent for some items, encode that in the type and docs now to reduce downstream checks.
Possible options:
paymentSourceId?: string(omitted when unknown)paymentSourceId: string | null(present but unknown)I can push a follow-up diff once you confirm which semantics match the API.
packages/types/src/clerk.ts (7)
481-488: Remove stray @param from prefetch method (no params).Doc mentions a
propsparam that doesn’t exist./** * Prefetches the data displayed by an organization switcher. * It can be used when `mountOrganizationSwitcher({ asStandalone: true})`, to avoid unwanted loading states. * - * @experimental This experimental API is subject to change. - * @param props Optional user verification configuration parameters. + * @experimental This experimental API is subject to change. */ __experimental_prefetchOrganizationSwitcher: () => void;
318-323: Fix closeGoogleOneTap description.Says “Opens” but this is the close method.
/** - * Opens the Google One Tap component. - * If the component is not already open, results in a noop. + * Closes the Google One Tap component. + * If the component is not already open, results in a noop. */ closeGoogleOneTap: () => void;
475-479: Correct component name in unmountOrganizationSwitcher docs.Minor copy issue and stray asterisk.
/** - * Unmount the organization profile component from the target node.* + * Unmount the OrganizationSwitcher component from the target node. * @param targetNode Target node to unmount the OrganizationSwitcher component from. */ unmountOrganizationSwitcher: (targetNode: HTMLDivElement) => void;
534-541: Grammar: “API keys” phrasing./** * This API is in early access and may change in future releases. * - * Mount a api keys component at the target element. + * Mount an API keys component at the target element. * @experimental * @param targetNode Target to mount the APIKeys component. * @param props Configuration parameters. */
541-549: Grammar: “API keys” phrasing./** * This API is in early access and may change in future releases. * - * Unmount a api keys component from the target element. + * Unmount an API keys component from the target element. * If there is no component mounted at the target node, results in a noop. * @experimental * @param targetNode Target node to unmount the ApiKeys component from. */
1273-1281: Tighten wording in SignInProps docs.“Full URL or path to for the sign in process.” → “Full URL or path for the sign-in process.”
/** - * Full URL or path to for the sign in process. + * Full URL or path for the sign-in process. * Used to fill the "Sign in" link in the SignUp component. */
1776-1780: Fix typo: ClerkProvider.“ClerkProvided” → “ClerkProvider”.
/** * Customisation options to fully match the Clerk components to your own brand. * These options serve as overrides and will be merged with the global `appearance` - * prop of ClerkProvided (if one is provided) + * prop of ClerkProvider (if one is provided) */
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (14)
packages/backend/src/api/endpoints/BillingApi.ts(5 hunks)packages/backend/src/api/factory.ts(1 hunks)packages/backend/src/api/resources/CommercePlan.ts(1 hunks)packages/backend/src/api/resources/CommerceSubscription.ts(1 hunks)packages/backend/src/api/resources/CommerceSubscriptionItem.ts(1 hunks)packages/backend/src/api/resources/Feature.ts(1 hunks)packages/backend/src/api/resources/JSON.ts(2 hunks)packages/react/src/components/CheckoutButton.tsx(2 hunks)packages/react/src/components/PlanDetailsButton.tsx(2 hunks)packages/react/src/components/SubscriptionDetailsButton.tsx(2 hunks)packages/shared/src/react/hooks/useSubscription.tsx(1 hunks)packages/types/src/clerk.ts(8 hunks)packages/types/src/commerce.ts(10 hunks)packages/types/src/json.ts(13 hunks)
✅ Files skipped from review due to trivial changes (1)
- packages/shared/src/react/hooks/useSubscription.tsx
🚧 Files skipped from review as they are similar to previous changes (10)
- packages/backend/src/api/factory.ts
- packages/backend/src/api/resources/CommercePlan.ts
- packages/backend/src/api/resources/CommerceSubscriptionItem.ts
- packages/backend/src/api/resources/CommerceSubscription.ts
- packages/backend/src/api/resources/JSON.ts
- packages/backend/src/api/endpoints/BillingApi.ts
- packages/react/src/components/PlanDetailsButton.tsx
- packages/react/src/components/CheckoutButton.tsx
- packages/react/src/components/SubscriptionDetailsButton.tsx
- packages/types/src/json.ts
🧰 Additional context used
📓 Path-based instructions (6)
**/*.{js,jsx,ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Profile and optimize critical paths
Validate all inputs and sanitize outputs
Implement proper logging with different levels
Files:
packages/backend/src/api/resources/Feature.tspackages/types/src/clerk.tspackages/types/src/commerce.ts
**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
packages/backend/src/api/resources/Feature.tspackages/types/src/clerk.tspackages/types/src/commerce.ts
packages/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
TypeScript is required for all packages
Files:
packages/backend/src/api/resources/Feature.tspackages/types/src/clerk.tspackages/types/src/commerce.ts
packages/**/*.{ts,tsx,d.ts}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Packages should export TypeScript types alongside runtime code
Files:
packages/backend/src/api/resources/Feature.tspackages/types/src/clerk.tspackages/types/src/commerce.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use proper TypeScript error types
**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoidanytype - preferunknownwhen type is uncertain, then narrow with type guards
Useinterfacefor object shapes that might be extended
Usetypefor unions, primitives, and computed types
Preferreadonlyproperties for immutable data structures
Useprivatefor internal implementation details
Useprotectedfor inheritance hierarchies
Usepublicexplicitly for clarity in public APIs
Preferreadonlyfor properties that shouldn't change after construction
Prefer composition and interfaces over deep inheritance chains
Use mixins for shared behavior across unrelated classes
Implement dependency injection for loose coupling
Let TypeScript infer when types are obvious
Useconst assertionsfor literal types:as const
Usesatisfiesoperator for type checking without widening
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Use type-only imports:import type { ... } from ...
Noanytypes without justification
Proper error handling with typed errors
Consistent use ofreadonlyfor immutable data
Proper generic constraints
No unused type parameters
Proper use of utility types instead of manual type construction
Type-only imports where possible
Proper tree-shaking friendly exports
No circular dependencies
Efficient type computations (avoid deep recursion)
Files:
packages/backend/src/api/resources/Feature.tspackages/types/src/clerk.tspackages/types/src/commerce.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Support multiple Clerk environment variables (CLERK_, NEXT_PUBLIC_CLERK_, etc.) for configuration.
Files:
packages/backend/src/api/resources/Feature.tspackages/types/src/clerk.tspackages/types/src/commerce.ts
🧬 Code graph analysis (2)
packages/types/src/clerk.ts (2)
packages/types/src/state.ts (1)
State(131-158)packages/clerk-js/src/core/state.ts (1)
State(19-68)
packages/types/src/commerce.ts (2)
packages/types/src/pagination.ts (2)
ClerkPaginatedResponse(21-30)ClerkPaginationParams(35-46)packages/types/src/resource.ts (1)
ClerkResource(8-21)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Integration Tests (nextjs, chrome, 14)
- GitHub Check: Integration Tests (nextjs, chrome, 15)
- GitHub Check: Integration Tests (generic, chrome)
🔇 Additional comments (1)
packages/backend/src/api/resources/Feature.ts (1)
6-6: Approve: @experimental JSDoc placement and TypeDoc config verifiedtypedoc.config.mjs registers '@experimental' as a custom block tag (added to notRenderedTags and blockTags, removed from modifierTags) and hideOverrides is true; repo audit shows @experimental consistently placed as the final JSDoc line (including packages/backend/src/api/resources/Feature.ts).
| initializePaymentSource: ( | ||
| params: Exclude<InitializePaymentSourceParams, 'orgId'>, | ||
| ) => Promise<CommerceInitializedPaymentSourceResource>; | ||
| /** |
There was a problem hiding this comment.
Use Omit, not Exclude, to remove a property from an object type.
Exclude doesn’t remove object keys; it filters union members. These parameters still accept orgId today.
Apply:
- initializePaymentSource: (
- params: Exclude<InitializePaymentSourceParams, 'orgId'>,
- ) => Promise<CommerceInitializedPaymentSourceResource>;
+ initializePaymentSource: (
+ params: Omit<InitializePaymentSourceParams, 'orgId'>,
+ ) => Promise<CommerceInitializedPaymentSourceResource>;
- addPaymentSource: (params: Exclude<AddPaymentSourceParams, 'orgId'>) => Promise<CommercePaymentSourceResource>;
+ addPaymentSource: (params: Omit<AddPaymentSourceParams, 'orgId'>) => Promise<CommercePaymentSourceResource>;
- getPaymentSources: (
- params: Exclude<GetPaymentSourcesParams, 'orgId'>,
- ) => Promise<ClerkPaginatedResponse<CommercePaymentSourceResource>>;
+ getPaymentSources: (
+ params: Omit<GetPaymentSourcesParams, 'orgId'>,
+ ) => Promise<ClerkPaginatedResponse<CommercePaymentSourceResource>>;Also applies to: 93-94, 97-100
🤖 Prompt for AI Agents
In packages/types/src/commerce.ts around lines 87-90 (and also at the other
occurrences noted at 93-94 and 97-100), the code uses
Exclude<InitializePaymentSourceParams, 'orgId'> (and similar Exclude uses) which
does not strip an object property; replace each Exclude<..., 'orgId'> with
Omit<..., 'orgId'> so the orgId key is actually removed from the parameter type
definitions, updating all three locations accordingly.
Description
Typedoc considers
@experimentala modifier tag. This PR sets@experimentalto be considered as a block tag. This allows two things:notRenderedTagsoption in our typedoc configWhy do we not want the
@experimentaltext to be included in the docs? Because we already have a callout in the docs that handles this information, and we want to hide the following parts from the docs:Now, the output looks as follows:
This PR also updates all instances of
@experimentaland places it at the bottom of comments. This is because all text that follows will get attached to the@experimentaltag. If it were at the top, it would attach the entire comment to the@experimentaltag, which is not what we want.This PR also adds
hideOverrides: trueto our typedoc config. Classes that extend other classes were adding an "overrides" column to property tables that we want to hide. Typedoc provides this lovely config option to solve that :)Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit
Documentation
Chores