docs(shared,ui): 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.

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]

⚠️ No Changeset found

Latest commit: 3657c38

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

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

Click here to learn what changesets are, and how to add one.

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

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Skipped		Apr 18, 2026 1:02am

[SarahSoutoul]

@alexisintech I have pushed a docs review with a few quick / straightforward fixes, but let me know if anything doesn't look right. It does the following:

• Adds a link replacement for SessionTask as it wasn't properly linked and would lead to a 404 when clicking on it.
• Changed some of the logic within getRelativeLinkReplacements to take into account nested object-doc links to fix the issue raised here.
• Added a replacement for LastAuthenticationStrategy as it wasn't linked at all, as it should comparing to the current docs.
• For the Clerk object, added a more detailed intro than Main Clerk SDK object which can then be used as a Typedoc output.
• Fixed the link for authenticateWithGoogleOneTap(), as it would appear as an external link as such and be 404 when clicked (see what I mean below). Since the destination exists on the same page we're on, it just needed to be an hashtag.

Have found some other issues that I wasn't sure about but will make a separate comment for those.

[SarahSoutoul]

@alexisintech Okay here are the issues I have found while testing:

1. The tooltip isn't translating as it should on the Clerk page - instead of being displayed as a tooltip, it gets displayed as a link and leads to 404 when clicked. See below (left locally, right live docs).

   

2. Another link (screenshot 1) that leads to 404, mostly because it doesn't exist. The params are now listed right below with the changes (screenshot 2) vs being separate on the current docs (screenshot 3).

   Screenshot 1

   

   Screenshot 2

   

   Screenshot 3

   

3. Not an issue per se, but wondering if this (screenshot 1) is purely for documentation to exist on the javascript repo, because it doesn't create a Typedoc output and isn't being used in the docs. That info is inputted manually in the docs (screenshot 2)

   Screenshot 1

   

   Screenshot 2

   

4. Some of the properties that caught my attention - first one, not sure if we want a description and second one, the type just says any but was expecting what we have on the current docs (screenshot 3)

   Screenshot 1

   

   Screenshot 2

   

   Screenshot 3

   

These are all spotted on the Clerk object page, but the Client object page looked quite good to me at first glance. The Clerk page was quite meaty to go through and test, so I may have missed some stuff but will give it a second look for peace of mind.

[alexisintech]

@alexisintech Okay here are the issues I have found while testing:

1. The tooltip isn't translating as it should on the Clerk page - instead of being displayed as a tooltip, it gets displayed as a link and leads to 404 when clicked. See below (left locally, right live docs).
   
2. Another link (screenshot 1) that leads to 404, mostly because it doesn't exist. The params are now listed right below with the changes (screenshot 2) vs being separate on the current docs (screenshot 3).
   Screenshot 1
   
   Screenshot 2
   
   Screenshot 3
   
3. Not an issue per se, but wondering if this (screenshot 1) is purely for documentation to exist on the javascript repo, because it doesn't create a Typedoc output and isn't being used in the docs. That info is inputted manually in the docs (screenshot 2)
   Screenshot 1
   
   Screenshot 2
   
4. Some of the properties that caught my attention - first one, not sure if we want a description and second one, the type just says any but was expecting what we have on the current docs (screenshot 3)
   Screenshot 1
   
   Screenshot 2
   
   Screenshot 3
   

These are all spotted on the Clerk object page, but the Client object page looked quite good to me at first glance. The Clerk page was quite meaty to go through and test, so I may have missed some stuff but will give it a second look for peace of mind.

1. yeah the tooltip issue is on my agenda 😢
2. yep - i'm still creating some of those docs, they are in a list on my sticky note. but good eye! thank you for pointing out 🙏
3. yes it's not getting output by typedoc so i have it manually added, and then that line you highlighted we can stick in an <If sdk="js-frontend"> so good catch! not sure what the question is though - are you wondering if i meant to do that??
4. yeah not sure what's happening with the appearance output - I can take a look but if the type is outputting as any then we can simply link to the appearance docs in the description of the prop instead of the type column, so that the user can still access that info. and yes let me look into the clerkUI one! good catches 😸💖

[alexisintech]

@SarahSoutoul should I link it on object or should I add a sentence: See the Appearance docs for more information.

[alexisintech]

fixed clerkui and appearance descriptions c99e565 - we can update the appearance one how we want once you reply with your thoughts @SarahSoutoul

i also wrapped the constructor() method in an If sdk="js-frontend" in the clerk-docs PR 4f89cc7

[SarahSoutoul]

@SarahSoutoul should I link it on object or should I add a sentence: See the Appearance docs for more information.

@alexisintech I would go with the second option, actually! Have a: See the Appearance docs for more information.

For this:

yes it's not getting output by typedoc so i have it manually added, and then that line you highlighted we can stick in an so good catch! not sure what the question is though - are you wondering if i meant to do that??

My question was more around okay we're documenting it in the javascript repo, but it doesn't output any Typedoc and isn't being used in the docs. So is it just there as good documentation to exist in the javascript repo, aka is it needed there bcs if it isn't, it could just be removed, since we're not using it in our docs? It's not a massive issue at all and can be left alone - more of a curiosity question.

Everything else looks resolved! I will give it a second review once you add the extra stuff.

[alexisintech]

posting this here to track:
non-blocking UI issue but sometimes the type values, when they are links, have the gray backgrounds (like inline code usually does) but when they are in unions, e.g. a | b, they don't have the gray background