Thanks to visit codestin.com
Credit goes to github.com

Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 38 commits into
base: main
Choose a base branch
from
Open

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

wants to merge 38 commits into from

Conversation

@SarahSoutoul
Copy link
Contributor

@SarahSoutoul SarahSoutoul commented Sep 30, 2025 •
edited
Loading

🔎 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:

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

@SarahSoutoul SarahSoutoul self-assigned this Sep 30, 2025
@vercel
Copy link

vercel bot commented Sep 30, 2025 •
edited
Loading

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

Project Deployment Preview Updated (UTC)
clerk-docs Error Error Oct 24, 2025 8:07pm

@SarahSoutoul SarahSoutoul marked this pull request as ready for review October 15, 2025 18:03
@SarahSoutoul SarahSoutoul requested a review from a team as a code owner October 15, 2025 18:03
@alexisintech
Copy link
Member

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.

Screenshot 2025-10-16 at 17 12 55

@alexisintech
Copy link
Member

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
Copy link
Contributor Author

SarahSoutoul commented Oct 16, 2025 •
edited
Loading

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.

Screenshot 2025-10-16 at 17 12 55

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
Copy link
Contributor Author

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
SarahSoutoul commented Oct 16, 2025
View reviewed changes
@alexisintech
Copy link
Member

i think this is pretty much good to go - just waiting on a reply for clerk/javascript#6901 (comment)

@SarahSoutoul
Copy link
Contributor Author

i think this is pretty much good to go - just waiting on a reply for clerk/javascript#6901 (comment)

Thanks @alexisintech - I've replied. I'm getting @wobsoriano to look at the JS PR to make sure it's all good as well and it doesn't impact anything we may have not thought of, just to let you know.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@manovotny manovotny Awaiting requested review from manovotny

@NWylynko NWylynko Awaiting requested review from NWylynko

@alexisintech alexisintech Awaiting requested review from alexisintech

At least 1 approving review is required to merge this pull request.

Assignees

@SarahSoutoul SarahSoutoul

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@SarahSoutoul @alexisintech @NWylynko