docs(backend,shared): Generate typedoc output for backend docs

[alexisintech]

Summary

• Adds JSDoc comments to resources in packages/backend/src/api/endpoints/**/*.
• Adds a custom @expandProperties modifier tag (handled by .typedoc/custom-plugin.mjs) so generic-instantiation aliases like UserListParams = ClerkPaginationRequest<{...}> render as a single merged properties table instead of an empty page. typedoc-plugin-markdown otherwise has no rendering branch for top-level ReferenceTypes. Tag applied to ClerkPaginationRequest and ClerkPaginationParams.
• Wires backend API endpoint classes into the existing extract-methods.mjs pipeline via a new BACKEND_API_CONFIG in .typedoc/reference-objects.mjs. Each endpoint class registered here gets a backend/<kebab-name>/ folder containing <name>.mdx (main page) and methods/<method>.mdx (one file per public method, with description + TypeScript signature + parameters).
• extract-methods.mjs now supports two output styles via a methodFormat option plumbed from the config:
  • reference (existing reference-object pages — Clerk, UserResource, etc.): ### foo() title + #### Parameters heading. Designed for pages aggregating many methods.
  • page (new, used by BACKEND_API_CONFIG): no method-name title, ## Parameters heading. Designed for one-method-per-docs-page consumption.
• getPrimaryCallSignature skips @deprecated overloads (preferring the canonical signature when multiple are exposed). parametersMarkdownTable overlays @param block tags from sig.comment onto each parameter when their own comment is missing — fixes overloaded methods where the implementation's JSDoc carries the descriptions but typedoc only wires them onto the hidden implementation signature, leaving overloads with no per-parameter descriptions.
• nestedParameterRowsFromDocumentedProperties strips line breaks in the description column, so JSDoc descriptions containing <ul> blocks no longer shatter the markdown table.
• resolveDeclarationWithObjectMembers now unwraps ArrayType.elementType so params: Array<{...}> (e.g. CreateBulkOrganizationInvitationParams) flattens into nested params.* rows instead of dumping the inline shape into the Type column.
• formatNestedParamNameColumn now appends ? to nested rows when the child property is optional (read from child.flags?.isOptional) — matches the inline-{ ... } flatten behavior in clerkParametersTable.flattenParams. Retroactively adds ? markers to previously-incorrect rows like update-user.mdx's params.backupCodes?, params.firstName?, etc.

[changeset-bot]

🦋 Changeset detected

Latest commit: 49556f8

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

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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 (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 18, 2026 8:31pm
swingset	Building	Preview, Comment	Jun 18, 2026 8:31pm

[coderabbitai]

Important

Review skipped

Draft detected.

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.

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro

Run ID: fbb0de84-60b0-485f-bc8c-f1dbde6ff81d

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

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 9cb19e5

[SarahSoutoul]

@alexisintech Have just committed a small docs review - organization for the Organization stuff. It fixes two things:

• Capitalizes organization -> Organization for the createOrganization() method.
• Added @generateWithEmptyComment to the GetInstanceOrganizationMembershipListParams to display the params properly.

See before

See after

Have noticed a few odd things but wanted to get your opinion first, so will post a separate comment for those on clerk-docs PR.

[SarahSoutoul]

@alexisintech Adding both UserApi.ts and OrganizationApi.ts as Typedoc entrypoints produces standalone page collisions for shared param type names like GetOrganizationMembershipListParams and GetOrganizationInvitationListParams.

The generated output currently includes both the canonical file and a -1 variant, for example:

We could add a small post-processing step for these known endpoint param collisions so the generated files get stable scoped names (for example user-... vs organization-...) instead of leaking TypeDoc -1 suffixes into the public docs output?

So after Typedoc runs:

• Detect the colliding generated pages

• Rename them to stable names like:

  user-get-organization-membership-list-params.mdx
  organization-get-organization-membership-list-params.mdx
  

• Rewrite generated links to use those names

[alexisintech]

yes this was a big issue I kept trying to find the solution for and this is what me and my AFF came to - we don't actually use these files at all so while yes, we could add logic to handle these file names, it wouldn't be for anything. I'd rather not add unnecessary tech debt!

[SarahSoutoul]

@alexisintech Imo, the new description for provider looks a bit ambiguous next to the generated signature. The prose example says custom_google, but the rendered type resolves to oauth_custom_${string}, so I think it's easy to read the example as the full argument value rather than just the provider-name portion. Could we make the example explicit (for example oauth_custom_google) so the docs match the rendered signature more clearly?

[SarahSoutoul]

@alexisintech have left a docs review - user for the User stuff. It fixes two things.

• One of the PaginatedResourceResponse was missing the backticks, which didn't render it properly like the other ones.
• Updated getUserOauthAccessToken() so the generated docs now surface the preferred OAuthProvider overload instead of the deprecated oauth_-prefixed OAuthStrategy one. What changed:
  • Reordered the overloads in UserApi.ts so the preferred OAuthProvider signature comes first
  • Moved the main JSDoc onto that preferred overload so Typedoc attaches the full param/return descriptions to the right signature
  • Kept the deprecated prefixed overload in place for backwards compatibility
  • Updated the Typedoc link rewrites so both OAuthStrategy and OAuthProvider resolve correctly, rather than replacing one with the other

Also submitted a docs review - user in the clerk-docs repo.

Other than that, one issue I did find is the following:

updateUser() lost the deprecation guidance for publicMetadata, privateMetadata, and unsafeMetadata. But the source still marks those fields deprecated in UserApi.ts and explicitly tells readers to use updateUserMetadata() / replaceUserMetadata() instead. That guidance was present in the old live docs and seems important to preserve.

Old live docs

VS now

[SarahSoutoul]

@alexisintech Made a docs review - domains, allowlist and billing doing the following:

• For the delete() method, I removed the description next to the @deprecated tag, as it looked odd on the UI, and was already in the warning callout above.

  

• Added some missing {{ target: '_blank' }} to Backend API links to make sure they were external in the Typedoc output

And made a docs review - domains, allowlist and billing on the clerk-docs repo too.

One remaining thing I noticed is the descriptions of the params for createAllowlistIdentifier() are a bit more thorough in the live docs compared to the current Typedoc output. Think it might be worth adding that info unless it was omitted for any specific reason.

[alexisintech]

@alexisintech Made a docs review - domains, allowlist and billing doing the following:

• For the delete() method, I removed the description next to the @deprecated tag, as it looked odd on the UI, and was already in the warning callout above.
  
• Added some missing {{ target: '_blank' }} to Backend API links to make sure they were external in the Typedoc output

And made a docs review - domains, allowlist and billing on the clerk-docs repo too.

One remaining thing I noticed is the descriptions of the params for createAllowlistIdentifier() are a bit more thorough in the live docs compared to the current Typedoc output. Think it might be worth adding that info unless it was omitted for any specific reason.

we still need the deprecated tag on the method for users that need that information in their IDE's when using the method, so we wouldn't want to remove that text from the tag - I have some work locally for a solution for deprecated tags producing output, so I'll work on this and get back to you! I'm glad to see you were able to catch this too! :)

and I agree with you on the needing that extra information! I will update those params with the extra information