Ensure all hooks are using typedocs + have code examples for each supported SDK

[SarahSoutoul]

🔎 Previews:

• All previews can be accessed via the linked hooks under the Testing section below. This section is meant to help for the testing process and helps keep track of everything. Please note that the returns and params will be broken when checking the hooks on the preview links - this is normal as this PR will need to be merged first.. I would focus on reviewing the code examples on this PR.

What does this solve?

Fixes https://linear.app/clerk/issue/DOCS-10983/ensure-all-hooks-are-using-typedocs-have-code-examples-for-each.

This PR is part of a broader project aimed at adding more code examples to our hooks documentation. During project discussions, we agreed that the current structure of our hooks docs needed to be revisited. Currently, most of the hook pages are fully rendered through Typedoc, including code examples. However, adding additional examples through Typedoc would have required significant restructuring of the JavaScript repo.

To address this, we decided to:

• Use Typedoc only for documenting returns and parameters. PR on javascript for this: hhttps://github.com/docs(repo): Generate all params and return types (hooks work) javascript#6901.
• Write SDK-specific explanations and code examples directly in the docs instead of generating them via Typedoc. This is achieved through this PR.

Additionally, not all hooks currently use Typedoc. This PR also ensures that all hooks are properly configured to use Typedoc for their returns and parameters.

This PR includes:

• Adding code examples for all supported SDKs.
• Ensuring the updated Typedoc outputs are properly integrated into the docs site.

This PR will be the second in a sequence. First, we need to merge the javascript PR, which:

• Adds JSDoc comments to the billing hooks so their returns and parameters are correctly pulled from Typedoc.
• Updates the documentation setup to ensure Typedoc is used only for returns and parameters, not for examples or SDK explanations.

What changed?

This PR adds all the code examples for the supported SDKs for each hook + uses the newly rendered Typedoc returns/ parameters, placing them after the examples for the most part.

---

Testing

• useAuth - already using typedoc, but examples need to be moved out

  • astro
  • chrome-extension
  • expo
  • react-router
  • tanstack-react-start

• useClerk - already using typedoc, but examples need to be moved out

  • chrome-extension
  • expo
  • react-router
  • tanstack-react-start

• useUser - already using typedoc, but examples need to be moved out

  • chrome-extension
  • expo
  • nextjs
  • react-router
  • tanstack-react-start

• useSession - already using typedoc, but examples need to be moved out

  • chrome-extension
  • expo
  • react-router
  • tanstack-react-start

• useSessionList - already using typedoc, but examples need to be moved out

  • chrome-extension
  • expo
  • react-router
  • tanstack-react-start

• useSignIn - already using typedoc, but examples need to be moved out

  • chrome-extension
  • expo
  • react-router
  • tanstack-react-start

• useSignUp - - already using typedoc, but examples need to be moved out

  • chrome-extension
  • expo
  • react-router
  • tanstack-react-start

• useCheckout - need to be using typedoc

  • React

• usePaymentAttempts - need to be using typedoc

  • React

• usePaymentElement - need to be using typedoc

  • React

• usePaymentMethods - need to be using typedoc

  • React

• usePlans - need to be using typedoc

  • React

• useStatements - need to be using typedoc

  • React

• useSubscription - need to be using typedoc

  • React

• useReverification - need to be using typedoc (examples already done)

Checklist

• I have clicked on "Files changed" and performed a thorough self-review
• All existing checks pass

[vercel]

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

Project	Deployment	Preview	Updated (UTC)
clerk-docs	Error		Oct 16, 2025 11:09pm

[alexisintech]

these property sections are stuck as h2's because they're being outputted by typedoc, and i guess in our configuration we have property sections always use h2's. i'm gonna have to dig and fix this - i'm thinking we remove that heading altogether and only produce the property tables, so that we can control the heading on the docs.

[alexisintech]

I cleaned up some of the examples, and moved the parameters and returns sections back to the top - I think for the hooks, they should come first. some of the examples are super long, and push all that important information really far down. for components, i think it's probably fine to have their properties at the bottom, but for hooks, i feel like you'd want to understand the hook, like what's available for the hook, before trying to use it - its a little different than just dropping in a component. let me know your stance on this though 🤔

[SarahSoutoul]

these property sections are stuck as h2's because they're being outputted by typedoc, and i guess in our configuration we have property sections always use h2's. i'm gonna have to dig and fix this - i'm thinking we remove that heading altogether and only produce the property tables, so that we can control the heading on the docs.

Oooh nice catch. Yeah I'm already doing this for other ones, so I can make sure to do it for this one and others with the same issue. That's no problem.

Update: Fixed here: Fix headings for usePaymentElement + here in the javascript repo: Fix headings for usePaymentElement

[SarahSoutoul]

I cleaned up some of the examples, and moved the parameters and returns sections back to the top - I think for the hooks, they should come first. some of the examples are super long, and push all that important information really far down. for components, i think it's probably fine to have their properties at the bottom, but for hooks, i feel like you'd want to understand the hook, like what's available for the hook, before trying to use it - its a little different than just dropping in a component. let me know your stance on this though 🤔

Yeah I was divided on this, but I agree, think it's much better to have those first and then the examples. Thanks for moving them!

[SarahSoutoul]

@alexisintech In the live docs, this section is followed a copy essentially of the shared/use-checkout-options, which is why I had it twice on this document. I'm not sure if it's an error, but from my understanding they're here twice to show that you can use these parameters for either the useCheckout hook or as a parameter to the CheckoutProvider component. See what I mean below.

Under CheckoutProvider section:

As part of the parameters: