docs(repo): Add typedoc comments; generate typedoc output for /objects docs

[alexisintech]

⚠️ In conjunction with Generate object reference docs

Description

For the /objects in clerk-docs, we want to generate the reference information. In summary, this PR's main change is that:
When typedoc goes to generate files, it creates a folder for each defined object (which we define in reference-objects.mjs. E.g. clerk object gets .typedoc/docs/shared/clerk folder. This folder will have a <OBJECTNAME>-properties.mdx file and a <OBJECTNAME>-methods folder that includes each of the methods.

In a little more detail:

In reference-objects.mjs, we define these objects by defining the Typedoc output paths and by defining the primary interface/class on each reference object page in order to resolve TypeDoc reflections.

The extract-methods.mjs script will extract all of the methods from that object's primary interface/class and create a dedicated file for each one. I won't go into lengthy detail here, but the file is heavily commented through.

In custom-router.mjs

• Adds logic to ensure that for the defined REFERENCE_OBJECT_PAGE_SYMBOLS, dedicated folders are created for each object. So clerk.mdx no longer gets added to .typedoc/docs/shared/, it gets added to its own folder: .typedoc/docs/shared/clerk/

In custom-plugin.mjs

• Updates all regex so that links are never added to headings (# - #######)
• Adds applyRelativeLinkReplacements() helper that the extract-methods.mjs script uses to incorporate the link replacements into the files it generates
• Adds applyCatchAllMdReplacements() helper that the extract-methods.mjs script uses to incorporate the catch-all replacements into the files it generates
• Adds stripReferenceObjectPropertiesSection() which removes the Properties section from a generated file and puts it into its own file. For example, if shared/clerk/clerk.mdx is generated, it pulls the Properties section from it and puts it into its own shared/clerk/clerk-properties.mdx file.

comment-utils.mjs is used as a helper to remove "TODO" and its following text from generated content.

standalone-page-tag.mjs adds support for a custom tag called @standalonePage that can be used in conjunction with the @inline tag to indicate to typedoc to still generate a dedicated page for that type, even though it is recognized as @inline. Using both of these tags means that the type will show up as inlined in a table, but will also still have a generated MDX file.

Notable additions:

• Parameters that accept objects will include the object's properties in the table as children of that parameter.
  See the following examples (with before on left, after on right):
  
  
• If a parameter links to a dedicated page, parameter children (a?.b, a?.c, a?.d) are not shown in the table.
  
• If a method accepts only one parameter, the parameters section will be of that type. E.g. for joinWaitlist(), it accepts a params object of type JoinWaitlistParams. Instead of a "Parameters" section, it has a "JoinWaitlistParams" section:
  

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 0cdd2a7

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

This PR includes changesets to release 20 packages

Name	Type
@clerk/backend	Patch
@clerk/clerk-js	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/nextjs	Patch
@clerk/react	Patch
@clerk/shared	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/astro	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/chrome-extension	Patch
@clerk/expo-passkeys	Patch
@clerk/localizations	Patch
@clerk/msw	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 28, 2026 1:00am

[SarahSoutoul]

@alexisintech just pushed this Fix external link as the external link wasn't working.

[alexisintech]

make frontend api url open in new tab

sorry was still generating to test, and in between tasks, but thanks for catching! 🤦‍♀️

[manovotny]

Here's some things that caught my eye.

[manovotny]

Why are there several empty comments like this one in the file?

In the following files too:

• packages/shared/src/types/resource.ts
• packages/shared/src/types/session.ts
• packages/shared/src/types/signInFuture.ts
• packages/shared/src/types/signUpFuture.ts
• packages/shared/src/types/user.ts
• packages/shared/src/types/waitlist.ts

(I probably missed a few other files)

[alexisintech]

it's to tell typedoc to generate them. typedoc requires jsdoc comments as a signal that something needs to get generated. these don't always require anything written - if it makes more sense to fill these with descriptions, we can (but will need to test that it doesn't break any output). should we fill these comments so that no one else is confused?

[alexisintech]

so unfortunately, filling those comments will affect the output files and add the descriptions to the top of the files, which is something we don't want because we use those property tables as they are

[alexisintech]

I think something slightly better is we can change it from

/**
 *
 */

to

/** */

I can do it once the other PR gets pulled in here so its not twice the work or causing any merge conflicts

[manovotny]

That would be better. I'd still like to see if we can remove them altogether or have a placeholder reason. But we can revisit both later.

[alexisintech]

i've got the refactor here ready: refactor(repo): Inline extract-methods + tighten parameter rendering

@manovotny

[alexisintech]

unsafeMetadata section added successfully:

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 0cdd2a7

[manovotny]

Pushed some changes directly in 9be16f7.

• Broadened typedoc:generate cache inputs in turbo.json to .typedoc/**/*.mjs so edits to custom-plugin.mjs, custom-router.mjs, custom-theme.mjs, and prepare-markdown-renderer.mjs invalidate the cache.
• Dropped the export on commentContainsTodo in .typedoc/comment-utils.mjs.

[manovotny]

I'm good here, given the incoming changes in #8637 on top of this PR.