Add documentation for new custom flow APIs

[dstaley]

🔎 Previews:

• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/nextjs/reference/hooks/use-sign-in
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/nextjs/reference/hooks/use-sign-up
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/nextjs/reference/hooks/legacy/use-sign-in
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/nextjs/reference/hooks/legacy/use-sign-up
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/guides/development/custom-flows/authentication/email-password
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/guides/development/custom-flows/authentication/email-password-mfa
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/guides/development/custom-flows/authentication/email-sms-otp
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/guides/development/custom-flows/authentication/legacy/email-password
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/reference/javascript/sign-in-future
• https://clerk.com/docs/pr/dsfeat-custom-flow-apis/reference/javascript/sign-up-future

What does this solve?

This PR adds documentation for our new custom flows APIs, which are available in JavaScript-based SDKs built on top of React. These APIs will become the default APIs in the next major version of @clerk/react.

What changed?

One of the challenges of documenting these new APIs is that they've diverged from the APIs previously used for other SDKs, primarily our iOS and Android SDKs. This poses a unique challenge because the concept of what must be done to accomplish a sign-in or sign-up is now dependent upon the SDK used, whereas the current documentation depends on all SDKs using the same foundational ideas. For example, the new APIs no longer have the concept of "preparing", which the current docs reference. To alleviate this, the new guides utilize the <If> conditional component to selectively render different language and code examples based on the selected SDK, which allows us to directly reference the new API methods when the currently selected SDK is one that utilizes the new APIs.

This, however, causes another issue, which is what content should be shown when the current selected SDK doesn't have any examples for custom flows? As is, selecting a SDK such as Express would result in neither of the <If> statements being true, which would prevent any content from showing. To prevent showing blank content, the new guides utilize the sdk front matter attribute to only show the guides in the sidebar when a relevant SDK is selected.

Also, since the previous APIs are still available for backwards compatibility, the original docs have been copied to the /legacy folder to allow customers to still access the guides for reference.

Note

As of writing, the legacy guides do not utilize the sdk front matter attribute, but they probably should, otherwise the sidebar will look like this:

The new custom flow APIs are built upon the SignInFuture and SignUpFuture classes. Since we're not planning a major release of clerk-js, these classes are being made available to access the new APIs. The documentation for these new classes have been added alongside the existing SignIn and SignUp API documentation, and serves as the canonical reference documentation for the signIn and signUp exports of the new useSignIn and useSignUp hooks.

Note

I'm working on getting the <Typedoc> component to work well with the new SignInFuture and SignUpFuture types for the autogenerated documentation for useSignIn and useSignUp. If I'm unable to get it to work, I'll link out to the SignInFuture and SignUpFuture documentation.

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	Ready	Preview	Oct 15, 2025 4:36pm

[alexisintech]

This, however, causes another issue, which is what content should be shown when the current selected SDK doesn't have any examples for custom flows? As is, selecting a SDK such as Express would result in neither of the statements being true, which would prevent any content from showing. To prevent showing blank content, the new guides utilize the sdk front matter attribute to only show the guides in the sidebar when a relevant SDK is selected.

This is exactly correct! If you take a look at how we do our component references, this is the exact logic we do. If the user is on the Express SDK, and tries to visit a component page like /docs/reference/components/user/user-button , they will be shown this page:

This will happen for the custom flows as well, if you use the sdk frontmatter property to scope the page