Skip to content

CONTRIBUTING-COMPONENTS-HOOKS.md

Latest commit

 

History

History
119 lines (76 loc) · 7.58 KB

CONTRIBUTING-COMPONENTS-HOOKS.md

File metadata and controls

119 lines (76 loc) · 7.58 KB

Contributing to Clerk's hooks and components documentation

Component and hook documentation includes SDK-specific code examples and supporting content for all supported SDKs to ensure the best user experience. Each component and hook must have code examples for each supported SDK. If you're adding a new component or hook, or updating an existing one, the sections below outline the process.

Table of contents

Components

All existing components are listed in the Component Reference overview, and live under docs/reference/components within our docs. Each component belongs to a specific category (except for <ClerkProvider>), and these categories determine how components are organized in both the sidebar and the reference overview. Therefore, it's important to ensure that the ordering in the sidebar matches the ordering in the reference overview.

How component documentation works

A component page usually includes the following:

  • An image of the component at the top.
  • A description of the component.
  • An SDK-specific code example showing how to use the component, with an explanation.
  • A list of any optional properties the component accepts, rendered via the <Properties> component.
  • Any additional information.

How to update component documentation

All component documentation is directly maintained in this repository.

If you have to make any changes to the components documentation, here are two common scenarios you may encounter:

  • If you need to add a new component to the docs:

    • Add the component to the Component Reference overview under its corresponding category.
    • Add the component to the sidebar under the same category.
    • Include an image of the component at the top of the page, in both SVG and PNG formats. You can request image assets from the Design team by contacting them directly or by creating a ticket in their Linear board. Learn how to add images to the docs.
    • Provide SDK-specific code examples for each supported SDK, using the <If> component. Avoid examples that only show the import statement.
    • Place all code examples before the properties documentation (if applicable).

  • If a component is now supported by an additional SDK, update the sdk property in the frontmatter of that component's page and add the appropriate code example using <If>. For updates to existing code examples, simply modify the relevant example in place.

Hooks

All existing hooks are listed in the Hooks Reference overview, and live under docs/reference/hooks within our docs.

How hook documentation works

A hook page usually includes the following:

  • A description of the hook.
  • A Parameters section, listing the parameters the hook accepts.
  • A Returns section, listing the properties the hook returns.
  • SDK-specific code examples showing how to use the hook, with explanations.
  • Any additional information.

Note

Unlike component documentation, hook documentation is split between two sources. This is intentional, and reflects how we handle type information versus written content. Historically, many hook pages were fully generated from JSDoc + Typedoc, including code examples. However, adding examples for multiple SDKs through Typedoc required significant restructuring of the clerk/javascript repo, so we shifted to a hybrid model.

Each hook page contains two distinct layers:

Typedoc-generated content

The parameters, return types, and type definitions for each hook are autogenerated from JSDoc comments in the clerk/javascript repo. Typedoc converts these comments into MDX output, which lives in clerk-docs in the clerk-typedoc/ folder. These MDX files are embedded via the <Typedoc /> component. You can learn more about this process in this section.

Important

When working locally, Typedoc output lives in /local-clerk-typedoc instead.

For example, in the /reference/hooks/use-auth.mdx file, if you want to render ./clerk-typedoc/clerk-react/use-auth-params.mdx, you would embed the <Typedoc /> component like this:

<Typedoc src="react/use-auth-params" />

Handwritten content

Explanations, usage notes, and SDK-specific code examples live directly in the clerk-docs repository. This makes it easier to improve or expand documentation without touching the SDK source or Typedoc configuration.

Note

Code examples should demonstrate how to use the hook in a real scenario. Avoid examples that only show the import statement.

This split ensures:

  • Type information always stays in sync with the SDK source.
  • Contributors can freely update explanations or add SDK-specific examples without modifying the Typedoc pipeline.

How to update hook documentation

Because hook pages combine two sources, updates may need to happen in two places:

  • The javascript repository, when adding or updating parameters, return types, or type definitions through JSDoc.
  • The clerk-docs repository, when adding or updating explanations, SDK-specific code examples, or any other written content.

If you need to update parameters or return types for a hook, the changes must be made in the clerk/javascript repo:

  • Most hooks live under the packages/shared folder, except for three hooks - useAuth, useSignIn, and useSignup - who live under the packages/react folder.
  • Each hook's source file includes interfaces or types made visible via JSDoc comments.
  • You can add, remove, or update properties and descriptions directly in these JSDoc comments.

When embedding Typedoc output for a hook in the docs, the package you import from inside the clerk-typedoc folder depends on where that hook is exported from in the clerk/javascript repo. Use the following mapping:

  • If the hook is exported from packages/react/src/hooks/index.ts, import its Typedoc output from the clerk-react package, with the exception of useOrganization, useOrganizationList, and useReverification. Here's how the import would look like:

    <Typedoc src="react/<FILENAME>" />

  • If the hook is exported from packages/shared/src/react/hooks/index.ts, import its Typedoc output from the shared package, as such:

    <Typedoc src="shared/<FILENAME>" />

This ensures that when you embed a Typedoc block (e.g., parameters or returns), you load the correct MDX file.