-
Notifications
You must be signed in to change notification settings - Fork 969
Components/ hooks contributing guide #2820
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.
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
Merged
Merged
Changes from all commits
Commits
Show all changes
23 commits
Select commit
Hold shift + click to select a range
18e667e
Initial draft
SarahSoutoul 433c83c
Refinements
SarahSoutoul cceeef7
Merge branch 'main' into ss/DOCS-11180
SarahSoutoul 2355034
Add table of contents
SarahSoutoul 83e9113
Merge branch 'main' into ss/DOCS-11180
SarahSoutoul 9451551
Fix linting
SarahSoutoul ff9757f
Fix components in table of contents
SarahSoutoul 3d9092c
Fix wrong links
SarahSoutoul bc6e975
Fix linking table
SarahSoutoul 444f29d
Update contributing/CONTRIBUTING-COMPONENTS-HOOKS.md
SarahSoutoul 22121f2
Changes post feedback
SarahSoutoul 50fc563
Formatting and refinements
SarahSoutoul 8dd2283
Fixing links
SarahSoutoul 144cb89
Final refinements
SarahSoutoul 90d465d
Fix linting
SarahSoutoul 9f90645
Merge branch 'main' into ss/DOCS-11180
SarahSoutoul 554d2c0
formatting
NWylynko a84a787
Merge branch 'main' into ss/DOCS-11180
SarahSoutoul 6df9f09
Apply suggestions from code review
SarahSoutoul a6596e3
Update contributing/CONTRIBUTING-COMPONENTS-HOOKS.md
SarahSoutoul 8001557
Update contributing/CONTRIBUTING-COMPONENTS-HOOKS.md
SarahSoutoul 07fa451
Final refinements post feedback
SarahSoutoul b11a78a
Refinements after testing
SarahSoutoul File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,119 @@ | ||
| # 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. | ||
|
|
||
| <details open="open"> | ||
| <summary><strong>Table of contents</strong></summary> | ||
|
|
||
| - [Contributing to Clerk's hooks and components documentation](#contributing-to-clerks-hooks-and-components-documentation) | ||
| - [Components](#components) | ||
| - [How component documentation works](#how-component-documentation-works) | ||
| - [How to update component documentation](#how-to-update-component-documentation) | ||
| - [Hooks](#hooks) | ||
| - [How hook documentation works](#how-hook-documentation-works) | ||
| - [How to update hook documentation](#how-to-update-hook-documentation) | ||
|
|
||
| </details> | ||
|
|
||
| ## Components | ||
|
|
||
| All existing components are listed in the [Component Reference overview](https://clerk.com/docs/reference/components/overview), and live under [`docs/reference/components`](/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>`](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#properties-1) 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](https://clerk.com/docs/reference/components/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](https://linear.app/clerk/team/DSN/all). Learn [how to add images to the docs](./CONTRIBUTING.md#images-and-static-assets). | ||
| - Provide SDK-specific code examples for each supported SDK, using the [`<If>`](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#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`](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#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](https://clerk.com/docs/reference/hooks/overview), and live under [`docs/reference/hooks`](/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](https://jsdoc.app/about-getting-started) 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 />`](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#typedoc-) component. You can learn more about this process in [this section](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md#authoring-typedoc-information). | ||
|
|
||
| > [!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: | ||
|
|
||
| ```mdx | ||
| <Typedoc src="clerk-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](https://github.com/clerk/javascript) repository, when adding or updating parameters, return types, or type definitions through JSDoc. | ||
| - The [clerk-docs](https://github.com/clerk/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: | ||
|
|
||
| ```mdx | ||
| <Typedoc src="clerk-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: | ||
|
|
||
| ```mdx | ||
| <Typedoc src="shared/<FILENAME>" /> | ||
| ``` | ||
|
|
||
| This ensures that when you embed a Typedoc block (e.g., parameters or returns), you load the correct MDX file. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.