chore(shared,clerk-react,types): Improve Typedoc

.changeset/green-donuts-press.md

@@ -0,0 +1,7 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+Improve JSDoc documentation

.typedoc/custom-plugin.mjs

@@ -1,5 +1,43 @@
 // @ts-check
-import { MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+import { MarkdownPageEvent, MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+
+/**
+ * A list of files where we want to remove any headings
+ */
+const FILES_WITHOUT_HEADINGS = [
+ 'use-organization-return.mdx',
+ 'use-organization-params.mdx',
+ 'paginated-resources.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'paginated-hook-config.mdx',
+ 'use-organization-list-return.mdx',
+ 'use-organization-list-params.mdx',
+];
+
+/**
+ * An array of tuples where the first element is the file name and the second element is the new path.
+ */
+const LINK_REPLACEMENTS = [
+ ['clerk-paginated-response', '/docs/references/javascript/types/clerk-paginated-response'],
+ ['paginated-resources', '#paginated-resources'],
+];
+
+/**
+ * Inside the generated MDX files are links to other generated MDX files. These relative links need to be replaced with absolute links to pages that exist on clerk.com.
+ * For example, `[Foobar](../../foo/bar.mdx)` needs to be replaced with `[Foobar](/docs/foo/bar)`.
+ * It also shouldn't matter how level deep the relative link is.
+ *
+ * This function returns an array of `{ pattern: string, replace: string }` to pass into the `typedoc-plugin-replace-text` plugin.
+ */
+function getRelativeLinkReplacements() {
+ return LINK_REPLACEMENTS.map(([fileName, newPath]) => {
+ return {
+ pattern: new RegExp(`\\((?:\\.{1,2}\\/)+.*?${fileName}\\.mdx\\)`, 'g'),
+ replace: `(${newPath})`,
+ };
+ });
+}
 
 /**
  * @param {string} str
@@ -13,8 +51,9 @@ function toKebabCase(str) {
  */
 export function load(app) {
  app.renderer.on(MarkdownRendererEvent.BEGIN, output => {
- // Do not output README.mdx files
+ // Modify the output object
  output.urls = output.urls
+ // Do not output README.mdx files
  ?.filter(e => !e.url.endsWith('README.mdx'))
  .map(e => {
  // Convert URLs (by default camelCase) to kebab-case
@@ -23,7 +62,37 @@ export function load(app) {
  e.url = kebabUrl;
  e.model.url = kebabUrl;
 
+ /**
+ * For the `@clerk/shared` package it outputs the hooks as for example: shared/react/hooks/use-clerk/functions/use-clerk.mdx.
+ * It also places the interfaces as shared/react/hooks/use-organization/interfaces/use-organization-return.mdx
+ * Group all those .mdx files under shared/react/hooks
+ */
+ if (e.url.includes('shared/react/hooks')) {
+ e.url = e.url.replace(/\/[^/]+\/(functions|interfaces)\//, '/');
+ e.model.url = e.url;
+ }
+
  return e;
  });
  });
+
+ app.renderer.on(MarkdownPageEvent.END, output => {
+ const fileName = output.url.split('/').pop();
+ const linkReplacements = getRelativeLinkReplacements();
+
+ for (const { pattern, replace } of linkReplacements) {
+ if (output.contents) {
+ output.contents = output.contents.replace(pattern, replace);
+ }
+ }
+
+ if (fileName) {
+ if (FILES_WITHOUT_HEADINGS.includes(fileName)) {
+ if (output.contents) {
+ // Remove any headings from the file, irrespective of the level
+ output.contents = output.contents.replace(/^#+\s.+/gm, '');
+ }
+ }
+ }
+ });
 }

.typedoc/custom-theme.mjs

@@ -1,5 +1,5 @@
 // @ts-check
-import { ReflectionKind } from 'typedoc';
+import { ArrayType, IntersectionType, ReflectionKind, ReflectionType, UnionType } from 'typedoc';
 import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';
 
 /**
@@ -36,7 +36,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
  this.partials = {
  ...superPartials,
  /**
- * Copied from default theme / source code. This hides the return type from the output
+ * Copied from default theme / source code. This hides the return type heading over the table from the output
  * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/179a54c502b318cd4f3951e5e8b90f7f7a4752d8/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts
  * @param {import('typedoc').SignatureReflection} model
  * @param {{ headingLevel: number }} options
@@ -235,6 +235,114 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
  md.push(this.partials.body(model, { headingLevel: options.headingLevel }));
 
+ return md.join('\n\n');
+ },
+ /**
+ * Copied from default theme / source code. This hides the "Type parameters" section and the declaration title from the output
+ * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/e798507a3c04f9ddf7710baf4cc7836053e438ff/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
+ * @param {import('typedoc').DeclarationReflection} model
+ * @param {{ headingLevel: number, nested?: boolean }} options
+ */
+ declaration: (model, options = { headingLevel: 2, nested: false }) => {
+ const md = [];
+
+ const opts = {
+ nested: false,
+ ...options,
+ };
+
+ if (!opts.nested && model.sources && !this.options.getValue('disableSources')) {
+ md.push(this.partials.sources(model));
+ }
+
+ if (model?.documents) {
+ md.push(
+ this.partials.documents(model, {
+ headingLevel: options.headingLevel,
+ }),
+ );
+ }
+
+ /**
+ * @type any
+ */
+ const modelType = model.type;
+ /**
+ * @type {import('typedoc').DeclarationReflection}
+ */
+ let typeDeclaration = modelType?.declaration;
+
+ if (model.type instanceof ArrayType && model.type?.elementType instanceof ReflectionType) {
+ typeDeclaration = model.type?.elementType?.declaration;
+ }
+
+ const hasTypeDeclaration =
+ Boolean(typeDeclaration) ||
+ (model.type instanceof UnionType && model.type?.types.some(type => type instanceof ReflectionType));
+
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: true,
+ showTags: false,
+ }),
+ );
+ }
+
+ if (model.type instanceof IntersectionType) {
+ model.type?.types?.forEach(intersectionType => {
+ if (intersectionType instanceof ReflectionType && !intersectionType.declaration.signatures) {
+ if (intersectionType.declaration.children) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ md.push(
+ this.partials.typeDeclaration(intersectionType.declaration, {
+ headingLevel: opts.headingLevel,
+ }),
+ );
+ }
+ }
+ });
+ }
+
+ if (hasTypeDeclaration) {
+ if (model.type instanceof UnionType) {
+ if (this.helpers.hasUsefulTypeDetails(model.type)) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ model.type.types.forEach(type => {
+ if (type instanceof ReflectionType) {
+ md.push(this.partials.someType(type, { forceCollapse: true }));
+ md.push(this.partials.typeDeclarationContainer(model, type.declaration, options));
+ } else {
+ md.push(`${this.partials.someType(type)}`);
+ }
+ });
+ }
+ } else {
+ const useHeading =
+ typeDeclaration?.children?.length &&
+ (model.kind !== ReflectionKind.Property || this.helpers.useTableFormat('properties'));
+ if (useHeading) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+ }
+ md.push(this.partials.typeDeclarationContainer(model, typeDeclaration, options));
+ }
+ }
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: false,
+ showTags: true,
+ showReturns: true,
+ }),
+ );
+ }
+
+ md.push(this.partials.inheritance(model, { headingLevel: opts.headingLevel }));
+
  return md.join('\n\n');
  },
  };

.typedoc/typedoc-prettier-config.json

@@ -0,0 +1,8 @@
+{
+ "tabWidth": 2,
+ "semi": false,
+ "singleQuote": true,
+ "printWidth": 120,
+ "useTabs": false,
+ "bracketSpacing": true
+}

package.json

@@ -48,7 +48,7 @@
  "test:integration:tanstack-start": "E2E_APP_ID=tanstack.start pnpm test:integration:base --grep @tanstack-start",
  "test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue",
  "turbo:clean": "turbo daemon clean",
- "typedoc:generate": "typedoc --tsconfig tsconfig.typedoc.json",
+ "typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/react/.gitignore

@@ -1,2 +1,3 @@
 /*/
 !/src/
+!/docs/

packages/react/docs/use-auth.md

@@ -0,0 +1,43 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/external-data/page.tsx' }}
+'use client';
+
+import { useAuth } from '@clerk/nextjs';
+
+export default function ExternalDataPage() {
+ const { userId, sessionId, getToken, isLoaded, isSignedIn } = useAuth();
+
+ const fetchExternalData = async () => {
+ const token = await getToken();
+
+ // Fetch data from an external API
+ const response = await fetch('https://api.example.com/data', {
+ headers: {
+ Authorization: `Bearer ${token}`,
+ },
+ });
+
+ return response.json();
+ };
+
+ if (!isLoaded) {
+ return <div>Loading...</div>;
+ }
+
+ if (!isSignedIn) {
+ return <div>Sign in to view this page</div>;
+ }
+
+ return (
+ <div>
+ <p>
+ Hello, {userId}! Your current active session is {sessionId}.
+ </p>
+ <button onClick={fetchExternalData}>Fetch Data</button>
+ </div>
+ );
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-in.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-in/page.tsx' }}
+'use client';
+
+import { useSignIn } from '@clerk/nextjs';
+
+export default function SignInPage() {
+ const { isLoaded, signIn } = useSignIn();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-in attempt status is {signIn?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-up.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-up/page.tsx' }}
+'use client';
+
+import { useSignUp } from '@clerk/nextjs';
+
+export default function SignUpPage() {
+ const { isLoaded, signUp } = useSignUp();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-up attempt status is {signUp?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/src/hooks/useAuth.ts

@@ -21,6 +21,9 @@ import { createGetToken, createSignOut } from './utils';
  *
  * The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/ExternalDataPage.tsx' }}
  * import { useAuth } from '@clerk/clerk-react'
  *
@@ -58,6 +61,14 @@ import { createGetToken, createSignOut } from './utils';
  * )
  * }
  * ```
+ *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-auth.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
  */
 export const useAuth = (initialAuthState: any = {}): UseAuthReturn => {
  useAssertWrappedByClerkProvider('useAuth');

packages/react/src/hooks/useSignIn.ts

@@ -13,6 +13,9 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  *
  * The following example uses the `useSignIn()` hook to access the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/SignInPage.tsx' }}
  * import { useSignIn } from '@clerk/clerk-react'
  *
@@ -28,6 +31,14 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  * }
  * ```
  *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-sign-in.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
+ *
  * @example
  * ### Create a custom sign-in flow with `useSignIn()`
  *

.changeset/green-donuts-press.md

@@ -0,0 +1,7 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+Improve JSDoc documentation

.typedoc/custom-plugin.mjs

@@ -1,5 +1,43 @@
 // @ts-check
-import { MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+import { MarkdownPageEvent, MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+
+/**
+ * A list of files where we want to remove any headings
+ */
+const FILES_WITHOUT_HEADINGS = [
+ 'use-organization-return.mdx',
+ 'use-organization-params.mdx',
+ 'paginated-resources.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'paginated-hook-config.mdx',
+ 'use-organization-list-return.mdx',
+ 'use-organization-list-params.mdx',
+];
+
+/**
+ * An array of tuples where the first element is the file name and the second element is the new path.
+ */
+const LINK_REPLACEMENTS = [
+ ['clerk-paginated-response', '/docs/references/javascript/types/clerk-paginated-response'],
+ ['paginated-resources', '#paginated-resources'],
+];
+
+/**
+ * Inside the generated MDX files are links to other generated MDX files. These relative links need to be replaced with absolute links to pages that exist on clerk.com.
+ * For example, `[Foobar](../../foo/bar.mdx)` needs to be replaced with `[Foobar](/docs/foo/bar)`.
+ * It also shouldn't matter how level deep the relative link is.
+ *
+ * This function returns an array of `{ pattern: string, replace: string }` to pass into the `typedoc-plugin-replace-text` plugin.
+ */
+function getRelativeLinkReplacements() {
+ return LINK_REPLACEMENTS.map(([fileName, newPath]) => {
+ return {
+ pattern: new RegExp(`\\((?:\\.{1,2}\\/)+.*?${fileName}\\.mdx\\)`, 'g'),
+ replace: `(${newPath})`,
+ };
+ });
+}
 
 /**
  * @param {string} str
@@ -13,8 +51,9 @@ function toKebabCase(str) {
  */
 export function load(app) {
  app.renderer.on(MarkdownRendererEvent.BEGIN, output => {
- // Do not output README.mdx files
+ // Modify the output object
  output.urls = output.urls
+ // Do not output README.mdx files
  ?.filter(e => !e.url.endsWith('README.mdx'))
  .map(e => {
  // Convert URLs (by default camelCase) to kebab-case
@@ -23,7 +62,37 @@ export function load(app) {
  e.url = kebabUrl;
  e.model.url = kebabUrl;
 
+ /**
+ * For the `@clerk/shared` package it outputs the hooks as for example: shared/react/hooks/use-clerk/functions/use-clerk.mdx.
+ * It also places the interfaces as shared/react/hooks/use-organization/interfaces/use-organization-return.mdx
+ * Group all those .mdx files under shared/react/hooks
+ */
+ if (e.url.includes('shared/react/hooks')) {
+ e.url = e.url.replace(/\/[^/]+\/(functions|interfaces)\//, '/');
+ e.model.url = e.url;
+ }
+
  return e;
  });
  });
+
+ app.renderer.on(MarkdownPageEvent.END, output => {
+ const fileName = output.url.split('/').pop();
+ const linkReplacements = getRelativeLinkReplacements();
+
+ for (const { pattern, replace } of linkReplacements) {
+ if (output.contents) {
+ output.contents = output.contents.replace(pattern, replace);
+ }
+ }
+
+ if (fileName) {
+ if (FILES_WITHOUT_HEADINGS.includes(fileName)) {
+ if (output.contents) {
+ // Remove any headings from the file, irrespective of the level
+ output.contents = output.contents.replace(/^#+\s.+/gm, '');
+ }
+ }
+ }
+ });
 }

.typedoc/custom-theme.mjs

@@ -1,5 +1,5 @@
 // @ts-check
-import { ReflectionKind } from 'typedoc';
+import { ArrayType, IntersectionType, ReflectionKind, ReflectionType, UnionType } from 'typedoc';
 import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';
 
 /**
@@ -36,7 +36,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
  this.partials = {
  ...superPartials,
  /**
- * Copied from default theme / source code. This hides the return type from the output
+ * Copied from default theme / source code. This hides the return type heading over the table from the output
  * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/179a54c502b318cd4f3951e5e8b90f7f7a4752d8/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts
  * @param {import('typedoc').SignatureReflection} model
  * @param {{ headingLevel: number }} options
@@ -235,6 +235,114 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
  md.push(this.partials.body(model, { headingLevel: options.headingLevel }));
 
+ return md.join('\n\n');
+ },
+ /**
+ * Copied from default theme / source code. This hides the "Type parameters" section and the declaration title from the output
+ * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/e798507a3c04f9ddf7710baf4cc7836053e438ff/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
+ * @param {import('typedoc').DeclarationReflection} model
+ * @param {{ headingLevel: number, nested?: boolean }} options
+ */
+ declaration: (model, options = { headingLevel: 2, nested: false }) => {
+ const md = [];
+
+ const opts = {
+ nested: false,
+ ...options,
+ };
+
+ if (!opts.nested && model.sources && !this.options.getValue('disableSources')) {
+ md.push(this.partials.sources(model));
+ }
+
+ if (model?.documents) {
+ md.push(
+ this.partials.documents(model, {
+ headingLevel: options.headingLevel,
+ }),
+ );
+ }
+
+ /**
+ * @type any
+ */
+ const modelType = model.type;
+ /**
+ * @type {import('typedoc').DeclarationReflection}
+ */
+ let typeDeclaration = modelType?.declaration;
+
+ if (model.type instanceof ArrayType && model.type?.elementType instanceof ReflectionType) {
+ typeDeclaration = model.type?.elementType?.declaration;
+ }
+
+ const hasTypeDeclaration =
+ Boolean(typeDeclaration) ||
+ (model.type instanceof UnionType && model.type?.types.some(type => type instanceof ReflectionType));
+
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: true,
+ showTags: false,
+ }),
+ );
+ }
+
+ if (model.type instanceof IntersectionType) {
+ model.type?.types?.forEach(intersectionType => {
+ if (intersectionType instanceof ReflectionType && !intersectionType.declaration.signatures) {
+ if (intersectionType.declaration.children) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ md.push(
+ this.partials.typeDeclaration(intersectionType.declaration, {
+ headingLevel: opts.headingLevel,
+ }),
+ );
+ }
+ }
+ });
+ }
+
+ if (hasTypeDeclaration) {
+ if (model.type instanceof UnionType) {
+ if (this.helpers.hasUsefulTypeDetails(model.type)) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ model.type.types.forEach(type => {
+ if (type instanceof ReflectionType) {
+ md.push(this.partials.someType(type, { forceCollapse: true }));
+ md.push(this.partials.typeDeclarationContainer(model, type.declaration, options));
+ } else {
+ md.push(`${this.partials.someType(type)}`);
+ }
+ });
+ }
+ } else {
+ const useHeading =
+ typeDeclaration?.children?.length &&
+ (model.kind !== ReflectionKind.Property || this.helpers.useTableFormat('properties'));
+ if (useHeading) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+ }
+ md.push(this.partials.typeDeclarationContainer(model, typeDeclaration, options));
+ }
+ }
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: false,
+ showTags: true,
+ showReturns: true,
+ }),
+ );
+ }
+
+ md.push(this.partials.inheritance(model, { headingLevel: opts.headingLevel }));
+
  return md.join('\n\n');
  },
  };

.typedoc/typedoc-prettier-config.json

@@ -0,0 +1,8 @@
+{
+ "tabWidth": 2,
+ "semi": false,
+ "singleQuote": true,
+ "printWidth": 120,
+ "useTabs": false,
+ "bracketSpacing": true
+}

package.json

@@ -48,7 +48,7 @@
  "test:integration:tanstack-start": "E2E_APP_ID=tanstack.start pnpm test:integration:base --grep @tanstack-start",
  "test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue",
  "turbo:clean": "turbo daemon clean",
- "typedoc:generate": "typedoc --tsconfig tsconfig.typedoc.json",
+ "typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/react/.gitignore

@@ -1,2 +1,3 @@
 /*/
 !/src/
+!/docs/

packages/react/docs/use-auth.md

@@ -0,0 +1,43 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/external-data/page.tsx' }}
+'use client';
+
+import { useAuth } from '@clerk/nextjs';
+
+export default function ExternalDataPage() {
+ const { userId, sessionId, getToken, isLoaded, isSignedIn } = useAuth();
+
+ const fetchExternalData = async () => {
+ const token = await getToken();
+
+ // Fetch data from an external API
+ const response = await fetch('https://api.example.com/data', {
+ headers: {
+ Authorization: `Bearer ${token}`,
+ },
+ });
+
+ return response.json();
+ };
+
+ if (!isLoaded) {
+ return <div>Loading...</div>;
+ }
+
+ if (!isSignedIn) {
+ return <div>Sign in to view this page</div>;
+ }
+
+ return (
+ <div>
+ <p>
+ Hello, {userId}! Your current active session is {sessionId}.
+ </p>
+ <button onClick={fetchExternalData}>Fetch Data</button>
+ </div>
+ );
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-in.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-in/page.tsx' }}
+'use client';
+
+import { useSignIn } from '@clerk/nextjs';
+
+export default function SignInPage() {
+ const { isLoaded, signIn } = useSignIn();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-in attempt status is {signIn?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-up.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-up/page.tsx' }}
+'use client';
+
+import { useSignUp } from '@clerk/nextjs';
+
+export default function SignUpPage() {
+ const { isLoaded, signUp } = useSignUp();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-up attempt status is {signUp?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/src/hooks/useAuth.ts

@@ -21,6 +21,9 @@ import { createGetToken, createSignOut } from './utils';
  *
  * The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/ExternalDataPage.tsx' }}
  * import { useAuth } from '@clerk/clerk-react'
  *
@@ -58,6 +61,14 @@ import { createGetToken, createSignOut } from './utils';
  * )
  * }
  * ```
+ *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-auth.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
  */
 export const useAuth = (initialAuthState: any = {}): UseAuthReturn => {
  useAssertWrappedByClerkProvider('useAuth');

packages/react/src/hooks/useSignIn.ts

@@ -13,6 +13,9 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  *
  * The following example uses the `useSignIn()` hook to access the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/SignInPage.tsx' }}
  * import { useSignIn } from '@clerk/clerk-react'
  *
@@ -28,6 +31,14 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  * }
  * ```
  *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-sign-in.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
+ *
  * @example
  * ### Create a custom sign-in flow with `useSignIn()`
  *

.changeset/green-donuts-press.md

@@ -0,0 +1,7 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+Improve JSDoc documentation

.typedoc/custom-plugin.mjs

@@ -1,5 +1,43 @@
 // @ts-check
-import { MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+import { MarkdownPageEvent, MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+
+/**
+ * A list of files where we want to remove any headings
+ */
+const FILES_WITHOUT_HEADINGS = [
+ 'use-organization-return.mdx',
+ 'use-organization-params.mdx',
+ 'paginated-resources.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'paginated-hook-config.mdx',
+ 'use-organization-list-return.mdx',
+ 'use-organization-list-params.mdx',
+];
+
+/**
+ * An array of tuples where the first element is the file name and the second element is the new path.
+ */
+const LINK_REPLACEMENTS = [
+ ['clerk-paginated-response', '/docs/references/javascript/types/clerk-paginated-response'],
+ ['paginated-resources', '#paginated-resources'],
+];
+
+/**
+ * Inside the generated MDX files are links to other generated MDX files. These relative links need to be replaced with absolute links to pages that exist on clerk.com.
+ * For example, `[Foobar](../../foo/bar.mdx)` needs to be replaced with `[Foobar](/docs/foo/bar)`.
+ * It also shouldn't matter how level deep the relative link is.
+ *
+ * This function returns an array of `{ pattern: string, replace: string }` to pass into the `typedoc-plugin-replace-text` plugin.
+ */
+function getRelativeLinkReplacements() {
+ return LINK_REPLACEMENTS.map(([fileName, newPath]) => {
+ return {
+ pattern: new RegExp(`\\((?:\\.{1,2}\\/)+.*?${fileName}\\.mdx\\)`, 'g'),
+ replace: `(${newPath})`,
+ };
+ });
+}
 
 /**
  * @param {string} str
@@ -13,8 +51,9 @@ function toKebabCase(str) {
  */
 export function load(app) {
  app.renderer.on(MarkdownRendererEvent.BEGIN, output => {
- // Do not output README.mdx files
+ // Modify the output object
  output.urls = output.urls
+ // Do not output README.mdx files
  ?.filter(e => !e.url.endsWith('README.mdx'))
  .map(e => {
  // Convert URLs (by default camelCase) to kebab-case
@@ -23,7 +62,37 @@ export function load(app) {
  e.url = kebabUrl;
  e.model.url = kebabUrl;
 
+ /**
+ * For the `@clerk/shared` package it outputs the hooks as for example: shared/react/hooks/use-clerk/functions/use-clerk.mdx.
+ * It also places the interfaces as shared/react/hooks/use-organization/interfaces/use-organization-return.mdx
+ * Group all those .mdx files under shared/react/hooks
+ */
+ if (e.url.includes('shared/react/hooks')) {
+ e.url = e.url.replace(/\/[^/]+\/(functions|interfaces)\//, '/');
+ e.model.url = e.url;
+ }
+
  return e;
  });
  });
+
+ app.renderer.on(MarkdownPageEvent.END, output => {
+ const fileName = output.url.split('/').pop();
+ const linkReplacements = getRelativeLinkReplacements();
+
+ for (const { pattern, replace } of linkReplacements) {
+ if (output.contents) {
+ output.contents = output.contents.replace(pattern, replace);
+ }
+ }
+
+ if (fileName) {
+ if (FILES_WITHOUT_HEADINGS.includes(fileName)) {
+ if (output.contents) {
+ // Remove any headings from the file, irrespective of the level
+ output.contents = output.contents.replace(/^#+\s.+/gm, '');
+ }
+ }
+ }
+ });
 }

.typedoc/custom-theme.mjs

@@ -1,5 +1,5 @@
 // @ts-check
-import { ReflectionKind } from 'typedoc';
+import { ArrayType, IntersectionType, ReflectionKind, ReflectionType, UnionType } from 'typedoc';
 import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';
 
 /**
@@ -36,7 +36,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
  this.partials = {
  ...superPartials,
  /**
- * Copied from default theme / source code. This hides the return type from the output
+ * Copied from default theme / source code. This hides the return type heading over the table from the output
  * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/179a54c502b318cd4f3951e5e8b90f7f7a4752d8/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts
  * @param {import('typedoc').SignatureReflection} model
  * @param {{ headingLevel: number }} options
@@ -235,6 +235,114 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
  md.push(this.partials.body(model, { headingLevel: options.headingLevel }));
 
+ return md.join('\n\n');
+ },
+ /**
+ * Copied from default theme / source code. This hides the "Type parameters" section and the declaration title from the output
+ * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/e798507a3c04f9ddf7710baf4cc7836053e438ff/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
+ * @param {import('typedoc').DeclarationReflection} model
+ * @param {{ headingLevel: number, nested?: boolean }} options
+ */
+ declaration: (model, options = { headingLevel: 2, nested: false }) => {
+ const md = [];
+
+ const opts = {
+ nested: false,
+ ...options,
+ };
+
+ if (!opts.nested && model.sources && !this.options.getValue('disableSources')) {
+ md.push(this.partials.sources(model));
+ }
+
+ if (model?.documents) {
+ md.push(
+ this.partials.documents(model, {
+ headingLevel: options.headingLevel,
+ }),
+ );
+ }
+
+ /**
+ * @type any
+ */
+ const modelType = model.type;
+ /**
+ * @type {import('typedoc').DeclarationReflection}
+ */
+ let typeDeclaration = modelType?.declaration;
+
+ if (model.type instanceof ArrayType && model.type?.elementType instanceof ReflectionType) {
+ typeDeclaration = model.type?.elementType?.declaration;
+ }
+
+ const hasTypeDeclaration =
+ Boolean(typeDeclaration) ||
+ (model.type instanceof UnionType && model.type?.types.some(type => type instanceof ReflectionType));
+
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: true,
+ showTags: false,
+ }),
+ );
+ }
+
+ if (model.type instanceof IntersectionType) {
+ model.type?.types?.forEach(intersectionType => {
+ if (intersectionType instanceof ReflectionType && !intersectionType.declaration.signatures) {
+ if (intersectionType.declaration.children) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ md.push(
+ this.partials.typeDeclaration(intersectionType.declaration, {
+ headingLevel: opts.headingLevel,
+ }),
+ );
+ }
+ }
+ });
+ }
+
+ if (hasTypeDeclaration) {
+ if (model.type instanceof UnionType) {
+ if (this.helpers.hasUsefulTypeDetails(model.type)) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ model.type.types.forEach(type => {
+ if (type instanceof ReflectionType) {
+ md.push(this.partials.someType(type, { forceCollapse: true }));
+ md.push(this.partials.typeDeclarationContainer(model, type.declaration, options));
+ } else {
+ md.push(`${this.partials.someType(type)}`);
+ }
+ });
+ }
+ } else {
+ const useHeading =
+ typeDeclaration?.children?.length &&
+ (model.kind !== ReflectionKind.Property || this.helpers.useTableFormat('properties'));
+ if (useHeading) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+ }
+ md.push(this.partials.typeDeclarationContainer(model, typeDeclaration, options));
+ }
+ }
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: false,
+ showTags: true,
+ showReturns: true,
+ }),
+ );
+ }
+
+ md.push(this.partials.inheritance(model, { headingLevel: opts.headingLevel }));
+
  return md.join('\n\n');
  },
  };

.typedoc/typedoc-prettier-config.json

@@ -0,0 +1,8 @@
+{
+ "tabWidth": 2,
+ "semi": false,
+ "singleQuote": true,
+ "printWidth": 120,
+ "useTabs": false,
+ "bracketSpacing": true
+}

package.json

@@ -48,7 +48,7 @@
  "test:integration:tanstack-start": "E2E_APP_ID=tanstack.start pnpm test:integration:base --grep @tanstack-start",
  "test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue",
  "turbo:clean": "turbo daemon clean",
- "typedoc:generate": "typedoc --tsconfig tsconfig.typedoc.json",
+ "typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/react/.gitignore

@@ -1,2 +1,3 @@
 /*/
 !/src/
+!/docs/

packages/react/docs/use-auth.md

@@ -0,0 +1,43 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/external-data/page.tsx' }}
+'use client';
+
+import { useAuth } from '@clerk/nextjs';
+
+export default function ExternalDataPage() {
+ const { userId, sessionId, getToken, isLoaded, isSignedIn } = useAuth();
+
+ const fetchExternalData = async () => {
+ const token = await getToken();
+
+ // Fetch data from an external API
+ const response = await fetch('https://api.example.com/data', {
+ headers: {
+ Authorization: `Bearer ${token}`,
+ },
+ });
+
+ return response.json();
+ };
+
+ if (!isLoaded) {
+ return <div>Loading...</div>;
+ }
+
+ if (!isSignedIn) {
+ return <div>Sign in to view this page</div>;
+ }
+
+ return (
+ <div>
+ <p>
+ Hello, {userId}! Your current active session is {sessionId}.
+ </p>
+ <button onClick={fetchExternalData}>Fetch Data</button>
+ </div>
+ );
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-in.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-in/page.tsx' }}
+'use client';
+
+import { useSignIn } from '@clerk/nextjs';
+
+export default function SignInPage() {
+ const { isLoaded, signIn } = useSignIn();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-in attempt status is {signIn?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-up.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-up/page.tsx' }}
+'use client';
+
+import { useSignUp } from '@clerk/nextjs';
+
+export default function SignUpPage() {
+ const { isLoaded, signUp } = useSignUp();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-up attempt status is {signUp?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/src/hooks/useAuth.ts

@@ -21,6 +21,9 @@ import { createGetToken, createSignOut } from './utils';
  *
  * The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/ExternalDataPage.tsx' }}
  * import { useAuth } from '@clerk/clerk-react'
  *
@@ -58,6 +61,14 @@ import { createGetToken, createSignOut } from './utils';
  * )
  * }
  * ```
+ *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-auth.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
  */
 export const useAuth = (initialAuthState: any = {}): UseAuthReturn => {
  useAssertWrappedByClerkProvider('useAuth');

packages/react/src/hooks/useSignIn.ts

@@ -13,6 +13,9 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  *
  * The following example uses the `useSignIn()` hook to access the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/SignInPage.tsx' }}
  * import { useSignIn } from '@clerk/clerk-react'
  *
@@ -28,6 +31,14 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  * }
  * ```
  *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-sign-in.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
+ *
  * @example
  * ### Create a custom sign-in flow with `useSignIn()`
  *

.changeset/green-donuts-press.md

@@ -0,0 +1,7 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+Improve JSDoc documentation

.typedoc/custom-plugin.mjs

@@ -1,5 +1,43 @@
 // @ts-check
-import { MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+import { MarkdownPageEvent, MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+
+/**
+ * A list of files where we want to remove any headings
+ */
+const FILES_WITHOUT_HEADINGS = [
+ 'use-organization-return.mdx',
+ 'use-organization-params.mdx',
+ 'paginated-resources.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'paginated-hook-config.mdx',
+ 'use-organization-list-return.mdx',
+ 'use-organization-list-params.mdx',
+];
+
+/**
+ * An array of tuples where the first element is the file name and the second element is the new path.
+ */
+const LINK_REPLACEMENTS = [
+ ['clerk-paginated-response', '/docs/references/javascript/types/clerk-paginated-response'],
+ ['paginated-resources', '#paginated-resources'],
+];
+
+/**
+ * Inside the generated MDX files are links to other generated MDX files. These relative links need to be replaced with absolute links to pages that exist on clerk.com.
+ * For example, `[Foobar](../../foo/bar.mdx)` needs to be replaced with `[Foobar](/docs/foo/bar)`.
+ * It also shouldn't matter how level deep the relative link is.
+ *
+ * This function returns an array of `{ pattern: string, replace: string }` to pass into the `typedoc-plugin-replace-text` plugin.
+ */
+function getRelativeLinkReplacements() {
+ return LINK_REPLACEMENTS.map(([fileName, newPath]) => {
+ return {
+ pattern: new RegExp(`\\((?:\\.{1,2}\\/)+.*?${fileName}\\.mdx\\)`, 'g'),
+ replace: `(${newPath})`,
+ };
+ });
+}
 
 /**
  * @param {string} str
@@ -13,8 +51,9 @@ function toKebabCase(str) {
  */
 export function load(app) {
  app.renderer.on(MarkdownRendererEvent.BEGIN, output => {
- // Do not output README.mdx files
+ // Modify the output object
  output.urls = output.urls
+ // Do not output README.mdx files
  ?.filter(e => !e.url.endsWith('README.mdx'))
  .map(e => {
  // Convert URLs (by default camelCase) to kebab-case
@@ -23,7 +62,37 @@ export function load(app) {
  e.url = kebabUrl;
  e.model.url = kebabUrl;
 
+ /**
+ * For the `@clerk/shared` package it outputs the hooks as for example: shared/react/hooks/use-clerk/functions/use-clerk.mdx.
+ * It also places the interfaces as shared/react/hooks/use-organization/interfaces/use-organization-return.mdx
+ * Group all those .mdx files under shared/react/hooks
+ */
+ if (e.url.includes('shared/react/hooks')) {
+ e.url = e.url.replace(/\/[^/]+\/(functions|interfaces)\//, '/');
+ e.model.url = e.url;
+ }
+
  return e;
  });
  });
+
+ app.renderer.on(MarkdownPageEvent.END, output => {
+ const fileName = output.url.split('/').pop();
+ const linkReplacements = getRelativeLinkReplacements();
+
+ for (const { pattern, replace } of linkReplacements) {
+ if (output.contents) {
+ output.contents = output.contents.replace(pattern, replace);
+ }
+ }
+
+ if (fileName) {
+ if (FILES_WITHOUT_HEADINGS.includes(fileName)) {
+ if (output.contents) {
+ // Remove any headings from the file, irrespective of the level
+ output.contents = output.contents.replace(/^#+\s.+/gm, '');
+ }
+ }
+ }
+ });
 }

.typedoc/custom-theme.mjs

@@ -1,5 +1,5 @@
 // @ts-check
-import { ReflectionKind } from 'typedoc';
+import { ArrayType, IntersectionType, ReflectionKind, ReflectionType, UnionType } from 'typedoc';
 import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';
 
 /**
@@ -36,7 +36,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
  this.partials = {
  ...superPartials,
  /**
- * Copied from default theme / source code. This hides the return type from the output
+ * Copied from default theme / source code. This hides the return type heading over the table from the output
  * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/179a54c502b318cd4f3951e5e8b90f7f7a4752d8/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts
  * @param {import('typedoc').SignatureReflection} model
  * @param {{ headingLevel: number }} options
@@ -235,6 +235,114 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
  md.push(this.partials.body(model, { headingLevel: options.headingLevel }));
 
+ return md.join('\n\n');
+ },
+ /**
+ * Copied from default theme / source code. This hides the "Type parameters" section and the declaration title from the output
+ * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/e798507a3c04f9ddf7710baf4cc7836053e438ff/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
+ * @param {import('typedoc').DeclarationReflection} model
+ * @param {{ headingLevel: number, nested?: boolean }} options
+ */
+ declaration: (model, options = { headingLevel: 2, nested: false }) => {
+ const md = [];
+
+ const opts = {
+ nested: false,
+ ...options,
+ };
+
+ if (!opts.nested && model.sources && !this.options.getValue('disableSources')) {
+ md.push(this.partials.sources(model));
+ }
+
+ if (model?.documents) {
+ md.push(
+ this.partials.documents(model, {
+ headingLevel: options.headingLevel,
+ }),
+ );
+ }
+
+ /**
+ * @type any
+ */
+ const modelType = model.type;
+ /**
+ * @type {import('typedoc').DeclarationReflection}
+ */
+ let typeDeclaration = modelType?.declaration;
+
+ if (model.type instanceof ArrayType && model.type?.elementType instanceof ReflectionType) {
+ typeDeclaration = model.type?.elementType?.declaration;
+ }
+
+ const hasTypeDeclaration =
+ Boolean(typeDeclaration) ||
+ (model.type instanceof UnionType && model.type?.types.some(type => type instanceof ReflectionType));
+
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: true,
+ showTags: false,
+ }),
+ );
+ }
+
+ if (model.type instanceof IntersectionType) {
+ model.type?.types?.forEach(intersectionType => {
+ if (intersectionType instanceof ReflectionType && !intersectionType.declaration.signatures) {
+ if (intersectionType.declaration.children) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ md.push(
+ this.partials.typeDeclaration(intersectionType.declaration, {
+ headingLevel: opts.headingLevel,
+ }),
+ );
+ }
+ }
+ });
+ }
+
+ if (hasTypeDeclaration) {
+ if (model.type instanceof UnionType) {
+ if (this.helpers.hasUsefulTypeDetails(model.type)) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ model.type.types.forEach(type => {
+ if (type instanceof ReflectionType) {
+ md.push(this.partials.someType(type, { forceCollapse: true }));
+ md.push(this.partials.typeDeclarationContainer(model, type.declaration, options));
+ } else {
+ md.push(`${this.partials.someType(type)}`);
+ }
+ });
+ }
+ } else {
+ const useHeading =
+ typeDeclaration?.children?.length &&
+ (model.kind !== ReflectionKind.Property || this.helpers.useTableFormat('properties'));
+ if (useHeading) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+ }
+ md.push(this.partials.typeDeclarationContainer(model, typeDeclaration, options));
+ }
+ }
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: false,
+ showTags: true,
+ showReturns: true,
+ }),
+ );
+ }
+
+ md.push(this.partials.inheritance(model, { headingLevel: opts.headingLevel }));
+
  return md.join('\n\n');
  },
  };

.typedoc/typedoc-prettier-config.json

@@ -0,0 +1,8 @@
+{
+ "tabWidth": 2,
+ "semi": false,
+ "singleQuote": true,
+ "printWidth": 120,
+ "useTabs": false,
+ "bracketSpacing": true
+}

package.json

@@ -48,7 +48,7 @@
  "test:integration:tanstack-start": "E2E_APP_ID=tanstack.start pnpm test:integration:base --grep @tanstack-start",
  "test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue",
  "turbo:clean": "turbo daemon clean",
- "typedoc:generate": "typedoc --tsconfig tsconfig.typedoc.json",
+ "typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/react/.gitignore

@@ -1,2 +1,3 @@
 /*/
 !/src/
+!/docs/

packages/react/docs/use-auth.md

@@ -0,0 +1,43 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/external-data/page.tsx' }}
+'use client';
+
+import { useAuth } from '@clerk/nextjs';
+
+export default function ExternalDataPage() {
+ const { userId, sessionId, getToken, isLoaded, isSignedIn } = useAuth();
+
+ const fetchExternalData = async () => {
+ const token = await getToken();
+
+ // Fetch data from an external API
+ const response = await fetch('https://api.example.com/data', {
+ headers: {
+ Authorization: `Bearer ${token}`,
+ },
+ });
+
+ return response.json();
+ };
+
+ if (!isLoaded) {
+ return <div>Loading...</div>;
+ }
+
+ if (!isSignedIn) {
+ return <div>Sign in to view this page</div>;
+ }
+
+ return (
+ <div>
+ <p>
+ Hello, {userId}! Your current active session is {sessionId}.
+ </p>
+ <button onClick={fetchExternalData}>Fetch Data</button>
+ </div>
+ );
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-in.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-in/page.tsx' }}
+'use client';
+
+import { useSignIn } from '@clerk/nextjs';
+
+export default function SignInPage() {
+ const { isLoaded, signIn } = useSignIn();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-in attempt status is {signIn?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-up.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-up/page.tsx' }}
+'use client';
+
+import { useSignUp } from '@clerk/nextjs';
+
+export default function SignUpPage() {
+ const { isLoaded, signUp } = useSignUp();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-up attempt status is {signUp?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/src/hooks/useAuth.ts

@@ -21,6 +21,9 @@ import { createGetToken, createSignOut } from './utils';
  *
  * The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/ExternalDataPage.tsx' }}
  * import { useAuth } from '@clerk/clerk-react'
  *
@@ -58,6 +61,14 @@ import { createGetToken, createSignOut } from './utils';
  * )
  * }
  * ```
+ *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-auth.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
  */
 export const useAuth = (initialAuthState: any = {}): UseAuthReturn => {
  useAssertWrappedByClerkProvider('useAuth');

packages/react/src/hooks/useSignIn.ts

@@ -13,6 +13,9 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  *
  * The following example uses the `useSignIn()` hook to access the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/SignInPage.tsx' }}
  * import { useSignIn } from '@clerk/clerk-react'
  *
@@ -28,6 +31,14 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  * }
  * ```
  *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-sign-in.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
+ *
  * @example
  * ### Create a custom sign-in flow with `useSignIn()`
  *

.changeset/green-donuts-press.md

@@ -0,0 +1,7 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+Improve JSDoc documentation

.typedoc/custom-plugin.mjs

@@ -1,5 +1,43 @@
 // @ts-check
-import { MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+import { MarkdownPageEvent, MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+
+/**
+ * A list of files where we want to remove any headings
+ */
+const FILES_WITHOUT_HEADINGS = [
+ 'use-organization-return.mdx',
+ 'use-organization-params.mdx',
+ 'paginated-resources.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'paginated-hook-config.mdx',
+ 'use-organization-list-return.mdx',
+ 'use-organization-list-params.mdx',
+];
+
+/**
+ * An array of tuples where the first element is the file name and the second element is the new path.
+ */
+const LINK_REPLACEMENTS = [
+ ['clerk-paginated-response', '/docs/references/javascript/types/clerk-paginated-response'],
+ ['paginated-resources', '#paginated-resources'],
+];
+
+/**
+ * Inside the generated MDX files are links to other generated MDX files. These relative links need to be replaced with absolute links to pages that exist on clerk.com.
+ * For example, `[Foobar](../../foo/bar.mdx)` needs to be replaced with `[Foobar](/docs/foo/bar)`.
+ * It also shouldn't matter how level deep the relative link is.
+ *
+ * This function returns an array of `{ pattern: string, replace: string }` to pass into the `typedoc-plugin-replace-text` plugin.
+ */
+function getRelativeLinkReplacements() {
+ return LINK_REPLACEMENTS.map(([fileName, newPath]) => {
+ return {
+ pattern: new RegExp(`\\((?:\\.{1,2}\\/)+.*?${fileName}\\.mdx\\)`, 'g'),
+ replace: `(${newPath})`,
+ };
+ });
+}
 
 /**
  * @param {string} str
@@ -13,8 +51,9 @@ function toKebabCase(str) {
  */
 export function load(app) {
  app.renderer.on(MarkdownRendererEvent.BEGIN, output => {
- // Do not output README.mdx files
+ // Modify the output object
  output.urls = output.urls
+ // Do not output README.mdx files
  ?.filter(e => !e.url.endsWith('README.mdx'))
  .map(e => {
  // Convert URLs (by default camelCase) to kebab-case
@@ -23,7 +62,37 @@ export function load(app) {
  e.url = kebabUrl;
  e.model.url = kebabUrl;
 
+ /**
+ * For the `@clerk/shared` package it outputs the hooks as for example: shared/react/hooks/use-clerk/functions/use-clerk.mdx.
+ * It also places the interfaces as shared/react/hooks/use-organization/interfaces/use-organization-return.mdx
+ * Group all those .mdx files under shared/react/hooks
+ */
+ if (e.url.includes('shared/react/hooks')) {
+ e.url = e.url.replace(/\/[^/]+\/(functions|interfaces)\//, '/');
+ e.model.url = e.url;
+ }
+
  return e;
  });
  });
+
+ app.renderer.on(MarkdownPageEvent.END, output => {
+ const fileName = output.url.split('/').pop();
+ const linkReplacements = getRelativeLinkReplacements();
+
+ for (const { pattern, replace } of linkReplacements) {
+ if (output.contents) {
+ output.contents = output.contents.replace(pattern, replace);
+ }
+ }
+
+ if (fileName) {
+ if (FILES_WITHOUT_HEADINGS.includes(fileName)) {
+ if (output.contents) {
+ // Remove any headings from the file, irrespective of the level
+ output.contents = output.contents.replace(/^#+\s.+/gm, '');
+ }
+ }
+ }
+ });
 }

.typedoc/custom-theme.mjs

@@ -1,5 +1,5 @@
 // @ts-check
-import { ReflectionKind } from 'typedoc';
+import { ArrayType, IntersectionType, ReflectionKind, ReflectionType, UnionType } from 'typedoc';
 import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';
 
 /**
@@ -36,7 +36,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
  this.partials = {
  ...superPartials,
  /**
- * Copied from default theme / source code. This hides the return type from the output
+ * Copied from default theme / source code. This hides the return type heading over the table from the output
  * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/179a54c502b318cd4f3951e5e8b90f7f7a4752d8/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts
  * @param {import('typedoc').SignatureReflection} model
  * @param {{ headingLevel: number }} options
@@ -235,6 +235,114 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
  md.push(this.partials.body(model, { headingLevel: options.headingLevel }));
 
+ return md.join('\n\n');
+ },
+ /**
+ * Copied from default theme / source code. This hides the "Type parameters" section and the declaration title from the output
+ * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/e798507a3c04f9ddf7710baf4cc7836053e438ff/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
+ * @param {import('typedoc').DeclarationReflection} model
+ * @param {{ headingLevel: number, nested?: boolean }} options
+ */
+ declaration: (model, options = { headingLevel: 2, nested: false }) => {
+ const md = [];
+
+ const opts = {
+ nested: false,
+ ...options,
+ };
+
+ if (!opts.nested && model.sources && !this.options.getValue('disableSources')) {
+ md.push(this.partials.sources(model));
+ }
+
+ if (model?.documents) {
+ md.push(
+ this.partials.documents(model, {
+ headingLevel: options.headingLevel,
+ }),
+ );
+ }
+
+ /**
+ * @type any
+ */
+ const modelType = model.type;
+ /**
+ * @type {import('typedoc').DeclarationReflection}
+ */
+ let typeDeclaration = modelType?.declaration;
+
+ if (model.type instanceof ArrayType && model.type?.elementType instanceof ReflectionType) {
+ typeDeclaration = model.type?.elementType?.declaration;
+ }
+
+ const hasTypeDeclaration =
+ Boolean(typeDeclaration) ||
+ (model.type instanceof UnionType && model.type?.types.some(type => type instanceof ReflectionType));
+
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: true,
+ showTags: false,
+ }),
+ );
+ }
+
+ if (model.type instanceof IntersectionType) {
+ model.type?.types?.forEach(intersectionType => {
+ if (intersectionType instanceof ReflectionType && !intersectionType.declaration.signatures) {
+ if (intersectionType.declaration.children) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ md.push(
+ this.partials.typeDeclaration(intersectionType.declaration, {
+ headingLevel: opts.headingLevel,
+ }),
+ );
+ }
+ }
+ });
+ }
+
+ if (hasTypeDeclaration) {
+ if (model.type instanceof UnionType) {
+ if (this.helpers.hasUsefulTypeDetails(model.type)) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ model.type.types.forEach(type => {
+ if (type instanceof ReflectionType) {
+ md.push(this.partials.someType(type, { forceCollapse: true }));
+ md.push(this.partials.typeDeclarationContainer(model, type.declaration, options));
+ } else {
+ md.push(`${this.partials.someType(type)}`);
+ }
+ });
+ }
+ } else {
+ const useHeading =
+ typeDeclaration?.children?.length &&
+ (model.kind !== ReflectionKind.Property || this.helpers.useTableFormat('properties'));
+ if (useHeading) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+ }
+ md.push(this.partials.typeDeclarationContainer(model, typeDeclaration, options));
+ }
+ }
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: false,
+ showTags: true,
+ showReturns: true,
+ }),
+ );
+ }
+
+ md.push(this.partials.inheritance(model, { headingLevel: opts.headingLevel }));
+
  return md.join('\n\n');
  },
  };

.typedoc/typedoc-prettier-config.json

@@ -0,0 +1,8 @@
+{
+ "tabWidth": 2,
+ "semi": false,
+ "singleQuote": true,
+ "printWidth": 120,
+ "useTabs": false,
+ "bracketSpacing": true
+}

package.json

@@ -48,7 +48,7 @@
  "test:integration:tanstack-start": "E2E_APP_ID=tanstack.start pnpm test:integration:base --grep @tanstack-start",
  "test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue",
  "turbo:clean": "turbo daemon clean",
- "typedoc:generate": "typedoc --tsconfig tsconfig.typedoc.json",
+ "typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/react/.gitignore

@@ -1,2 +1,3 @@
 /*/
 !/src/
+!/docs/

packages/react/docs/use-auth.md

@@ -0,0 +1,43 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/external-data/page.tsx' }}
+'use client';
+
+import { useAuth } from '@clerk/nextjs';
+
+export default function ExternalDataPage() {
+ const { userId, sessionId, getToken, isLoaded, isSignedIn } = useAuth();
+
+ const fetchExternalData = async () => {
+ const token = await getToken();
+
+ // Fetch data from an external API
+ const response = await fetch('https://api.example.com/data', {
+ headers: {
+ Authorization: `Bearer ${token}`,
+ },
+ });
+
+ return response.json();
+ };
+
+ if (!isLoaded) {
+ return <div>Loading...</div>;
+ }
+
+ if (!isSignedIn) {
+ return <div>Sign in to view this page</div>;
+ }
+
+ return (
+ <div>
+ <p>
+ Hello, {userId}! Your current active session is {sessionId}.
+ </p>
+ <button onClick={fetchExternalData}>Fetch Data</button>
+ </div>
+ );
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-in.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-in/page.tsx' }}
+'use client';
+
+import { useSignIn } from '@clerk/nextjs';
+
+export default function SignInPage() {
+ const { isLoaded, signIn } = useSignIn();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-in attempt status is {signIn?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-up.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-up/page.tsx' }}
+'use client';
+
+import { useSignUp } from '@clerk/nextjs';
+
+export default function SignUpPage() {
+ const { isLoaded, signUp } = useSignUp();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-up attempt status is {signUp?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/src/hooks/useAuth.ts

@@ -21,6 +21,9 @@ import { createGetToken, createSignOut } from './utils';
  *
  * The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/ExternalDataPage.tsx' }}
  * import { useAuth } from '@clerk/clerk-react'
  *
@@ -58,6 +61,14 @@ import { createGetToken, createSignOut } from './utils';
  * )
  * }
  * ```
+ *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-auth.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
  */
 export const useAuth = (initialAuthState: any = {}): UseAuthReturn => {
  useAssertWrappedByClerkProvider('useAuth');

packages/react/src/hooks/useSignIn.ts

@@ -13,6 +13,9 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  *
  * The following example uses the `useSignIn()` hook to access the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/SignInPage.tsx' }}
  * import { useSignIn } from '@clerk/clerk-react'
  *
@@ -28,6 +31,14 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  * }
  * ```
  *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-sign-in.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
+ *
  * @example
  * ### Create a custom sign-in flow with `useSignIn()`
  *

.changeset/green-donuts-press.md

@@ -0,0 +1,7 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+Improve JSDoc documentation

.typedoc/custom-plugin.mjs

@@ -1,5 +1,43 @@
 // @ts-check
-import { MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+import { MarkdownPageEvent, MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+
+/**
+ * A list of files where we want to remove any headings
+ */
+const FILES_WITHOUT_HEADINGS = [
+ 'use-organization-return.mdx',
+ 'use-organization-params.mdx',
+ 'paginated-resources.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'paginated-hook-config.mdx',
+ 'use-organization-list-return.mdx',
+ 'use-organization-list-params.mdx',
+];
+
+/**
+ * An array of tuples where the first element is the file name and the second element is the new path.
+ */
+const LINK_REPLACEMENTS = [
+ ['clerk-paginated-response', '/docs/references/javascript/types/clerk-paginated-response'],
+ ['paginated-resources', '#paginated-resources'],
+];
+
+/**
+ * Inside the generated MDX files are links to other generated MDX files. These relative links need to be replaced with absolute links to pages that exist on clerk.com.
+ * For example, `[Foobar](../../foo/bar.mdx)` needs to be replaced with `[Foobar](/docs/foo/bar)`.
+ * It also shouldn't matter how level deep the relative link is.
+ *
+ * This function returns an array of `{ pattern: string, replace: string }` to pass into the `typedoc-plugin-replace-text` plugin.
+ */
+function getRelativeLinkReplacements() {
+ return LINK_REPLACEMENTS.map(([fileName, newPath]) => {
+ return {
+ pattern: new RegExp(`\\((?:\\.{1,2}\\/)+.*?${fileName}\\.mdx\\)`, 'g'),
+ replace: `(${newPath})`,
+ };
+ });
+}
 
 /**
  * @param {string} str
@@ -13,8 +51,9 @@ function toKebabCase(str) {
  */
 export function load(app) {
  app.renderer.on(MarkdownRendererEvent.BEGIN, output => {
- // Do not output README.mdx files
+ // Modify the output object
  output.urls = output.urls
+ // Do not output README.mdx files
  ?.filter(e => !e.url.endsWith('README.mdx'))
  .map(e => {
  // Convert URLs (by default camelCase) to kebab-case
@@ -23,7 +62,37 @@ export function load(app) {
  e.url = kebabUrl;
  e.model.url = kebabUrl;
 
+ /**
+ * For the `@clerk/shared` package it outputs the hooks as for example: shared/react/hooks/use-clerk/functions/use-clerk.mdx.
+ * It also places the interfaces as shared/react/hooks/use-organization/interfaces/use-organization-return.mdx
+ * Group all those .mdx files under shared/react/hooks
+ */
+ if (e.url.includes('shared/react/hooks')) {
+ e.url = e.url.replace(/\/[^/]+\/(functions|interfaces)\//, '/');
+ e.model.url = e.url;
+ }
+
  return e;
  });
  });
+
+ app.renderer.on(MarkdownPageEvent.END, output => {
+ const fileName = output.url.split('/').pop();
+ const linkReplacements = getRelativeLinkReplacements();
+
+ for (const { pattern, replace } of linkReplacements) {
+ if (output.contents) {
+ output.contents = output.contents.replace(pattern, replace);
+ }
+ }
+
+ if (fileName) {
+ if (FILES_WITHOUT_HEADINGS.includes(fileName)) {
+ if (output.contents) {
+ // Remove any headings from the file, irrespective of the level
+ output.contents = output.contents.replace(/^#+\s.+/gm, '');
+ }
+ }
+ }
+ });
 }

.typedoc/custom-theme.mjs

@@ -1,5 +1,5 @@
 // @ts-check
-import { ReflectionKind } from 'typedoc';
+import { ArrayType, IntersectionType, ReflectionKind, ReflectionType, UnionType } from 'typedoc';
 import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';
 
 /**
@@ -36,7 +36,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
  this.partials = {
  ...superPartials,
  /**
- * Copied from default theme / source code. This hides the return type from the output
+ * Copied from default theme / source code. This hides the return type heading over the table from the output
  * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/179a54c502b318cd4f3951e5e8b90f7f7a4752d8/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts
  * @param {import('typedoc').SignatureReflection} model
  * @param {{ headingLevel: number }} options
@@ -235,6 +235,114 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
  md.push(this.partials.body(model, { headingLevel: options.headingLevel }));
 
+ return md.join('\n\n');
+ },
+ /**
+ * Copied from default theme / source code. This hides the "Type parameters" section and the declaration title from the output
+ * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/e798507a3c04f9ddf7710baf4cc7836053e438ff/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
+ * @param {import('typedoc').DeclarationReflection} model
+ * @param {{ headingLevel: number, nested?: boolean }} options
+ */
+ declaration: (model, options = { headingLevel: 2, nested: false }) => {
+ const md = [];
+
+ const opts = {
+ nested: false,
+ ...options,
+ };
+
+ if (!opts.nested && model.sources && !this.options.getValue('disableSources')) {
+ md.push(this.partials.sources(model));
+ }
+
+ if (model?.documents) {
+ md.push(
+ this.partials.documents(model, {
+ headingLevel: options.headingLevel,
+ }),
+ );
+ }
+
+ /**
+ * @type any
+ */
+ const modelType = model.type;
+ /**
+ * @type {import('typedoc').DeclarationReflection}
+ */
+ let typeDeclaration = modelType?.declaration;
+
+ if (model.type instanceof ArrayType && model.type?.elementType instanceof ReflectionType) {
+ typeDeclaration = model.type?.elementType?.declaration;
+ }
+
+ const hasTypeDeclaration =
+ Boolean(typeDeclaration) ||
+ (model.type instanceof UnionType && model.type?.types.some(type => type instanceof ReflectionType));
+
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: true,
+ showTags: false,
+ }),
+ );
+ }
+
+ if (model.type instanceof IntersectionType) {
+ model.type?.types?.forEach(intersectionType => {
+ if (intersectionType instanceof ReflectionType && !intersectionType.declaration.signatures) {
+ if (intersectionType.declaration.children) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ md.push(
+ this.partials.typeDeclaration(intersectionType.declaration, {
+ headingLevel: opts.headingLevel,
+ }),
+ );
+ }
+ }
+ });
+ }
+
+ if (hasTypeDeclaration) {
+ if (model.type instanceof UnionType) {
+ if (this.helpers.hasUsefulTypeDetails(model.type)) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ model.type.types.forEach(type => {
+ if (type instanceof ReflectionType) {
+ md.push(this.partials.someType(type, { forceCollapse: true }));
+ md.push(this.partials.typeDeclarationContainer(model, type.declaration, options));
+ } else {
+ md.push(`${this.partials.someType(type)}`);
+ }
+ });
+ }
+ } else {
+ const useHeading =
+ typeDeclaration?.children?.length &&
+ (model.kind !== ReflectionKind.Property || this.helpers.useTableFormat('properties'));
+ if (useHeading) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+ }
+ md.push(this.partials.typeDeclarationContainer(model, typeDeclaration, options));
+ }
+ }
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: false,
+ showTags: true,
+ showReturns: true,
+ }),
+ );
+ }
+
+ md.push(this.partials.inheritance(model, { headingLevel: opts.headingLevel }));
+
  return md.join('\n\n');
  },
  };

.typedoc/typedoc-prettier-config.json

@@ -0,0 +1,8 @@
+{
+ "tabWidth": 2,
+ "semi": false,
+ "singleQuote": true,
+ "printWidth": 120,
+ "useTabs": false,
+ "bracketSpacing": true
+}

package.json

@@ -48,7 +48,7 @@
  "test:integration:tanstack-start": "E2E_APP_ID=tanstack.start pnpm test:integration:base --grep @tanstack-start",
  "test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue",
  "turbo:clean": "turbo daemon clean",
- "typedoc:generate": "typedoc --tsconfig tsconfig.typedoc.json",
+ "typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/react/.gitignore

@@ -1,2 +1,3 @@
 /*/
 !/src/
+!/docs/

packages/react/docs/use-auth.md

@@ -0,0 +1,43 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/external-data/page.tsx' }}
+'use client';
+
+import { useAuth } from '@clerk/nextjs';
+
+export default function ExternalDataPage() {
+ const { userId, sessionId, getToken, isLoaded, isSignedIn } = useAuth();
+
+ const fetchExternalData = async () => {
+ const token = await getToken();
+
+ // Fetch data from an external API
+ const response = await fetch('https://api.example.com/data', {
+ headers: {
+ Authorization: `Bearer ${token}`,
+ },
+ });
+
+ return response.json();
+ };
+
+ if (!isLoaded) {
+ return <div>Loading...</div>;
+ }
+
+ if (!isSignedIn) {
+ return <div>Sign in to view this page</div>;
+ }
+
+ return (
+ <div>
+ <p>
+ Hello, {userId}! Your current active session is {sessionId}.
+ </p>
+ <button onClick={fetchExternalData}>Fetch Data</button>
+ </div>
+ );
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-in.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-in/page.tsx' }}
+'use client';
+
+import { useSignIn } from '@clerk/nextjs';
+
+export default function SignInPage() {
+ const { isLoaded, signIn } = useSignIn();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-in attempt status is {signIn?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-up.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-up/page.tsx' }}
+'use client';
+
+import { useSignUp } from '@clerk/nextjs';
+
+export default function SignUpPage() {
+ const { isLoaded, signUp } = useSignUp();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-up attempt status is {signUp?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/src/hooks/useAuth.ts

@@ -21,6 +21,9 @@ import { createGetToken, createSignOut } from './utils';
  *
  * The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/ExternalDataPage.tsx' }}
  * import { useAuth } from '@clerk/clerk-react'
  *
@@ -58,6 +61,14 @@ import { createGetToken, createSignOut } from './utils';
  * )
  * }
  * ```
+ *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-auth.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
  */
 export const useAuth = (initialAuthState: any = {}): UseAuthReturn => {
  useAssertWrappedByClerkProvider('useAuth');

packages/react/src/hooks/useSignIn.ts

@@ -13,6 +13,9 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  *
  * The following example uses the `useSignIn()` hook to access the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/SignInPage.tsx' }}
  * import { useSignIn } from '@clerk/clerk-react'
  *
@@ -28,6 +31,14 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  * }
  * ```
  *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-sign-in.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
+ *
  * @example
  * ### Create a custom sign-in flow with `useSignIn()`
  *

.changeset/green-donuts-press.md

@@ -0,0 +1,7 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+Improve JSDoc documentation

.typedoc/custom-plugin.mjs

@@ -1,5 +1,43 @@
 // @ts-check
-import { MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+import { MarkdownPageEvent, MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+
+/**
+ * A list of files where we want to remove any headings
+ */
+const FILES_WITHOUT_HEADINGS = [
+ 'use-organization-return.mdx',
+ 'use-organization-params.mdx',
+ 'paginated-resources.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'paginated-hook-config.mdx',
+ 'use-organization-list-return.mdx',
+ 'use-organization-list-params.mdx',
+];
+
+/**
+ * An array of tuples where the first element is the file name and the second element is the new path.
+ */
+const LINK_REPLACEMENTS = [
+ ['clerk-paginated-response', '/docs/references/javascript/types/clerk-paginated-response'],
+ ['paginated-resources', '#paginated-resources'],
+];
+
+/**
+ * Inside the generated MDX files are links to other generated MDX files. These relative links need to be replaced with absolute links to pages that exist on clerk.com.
+ * For example, `[Foobar](../../foo/bar.mdx)` needs to be replaced with `[Foobar](/docs/foo/bar)`.
+ * It also shouldn't matter how level deep the relative link is.
+ *
+ * This function returns an array of `{ pattern: string, replace: string }` to pass into the `typedoc-plugin-replace-text` plugin.
+ */
+function getRelativeLinkReplacements() {
+ return LINK_REPLACEMENTS.map(([fileName, newPath]) => {
+ return {
+ pattern: new RegExp(`\\((?:\\.{1,2}\\/)+.*?${fileName}\\.mdx\\)`, 'g'),
+ replace: `(${newPath})`,
+ };
+ });
+}
 
 /**
  * @param {string} str
@@ -13,8 +51,9 @@ function toKebabCase(str) {
  */
 export function load(app) {
  app.renderer.on(MarkdownRendererEvent.BEGIN, output => {
- // Do not output README.mdx files
+ // Modify the output object
  output.urls = output.urls
+ // Do not output README.mdx files
  ?.filter(e => !e.url.endsWith('README.mdx'))
  .map(e => {
  // Convert URLs (by default camelCase) to kebab-case
@@ -23,7 +62,37 @@ export function load(app) {
  e.url = kebabUrl;
  e.model.url = kebabUrl;
 
+ /**
+ * For the `@clerk/shared` package it outputs the hooks as for example: shared/react/hooks/use-clerk/functions/use-clerk.mdx.
+ * It also places the interfaces as shared/react/hooks/use-organization/interfaces/use-organization-return.mdx
+ * Group all those .mdx files under shared/react/hooks
+ */
+ if (e.url.includes('shared/react/hooks')) {
+ e.url = e.url.replace(/\/[^/]+\/(functions|interfaces)\//, '/');
+ e.model.url = e.url;
+ }
+
  return e;
  });
  });
+
+ app.renderer.on(MarkdownPageEvent.END, output => {
+ const fileName = output.url.split('/').pop();
+ const linkReplacements = getRelativeLinkReplacements();
+
+ for (const { pattern, replace } of linkReplacements) {
+ if (output.contents) {
+ output.contents = output.contents.replace(pattern, replace);
+ }
+ }
+
+ if (fileName) {
+ if (FILES_WITHOUT_HEADINGS.includes(fileName)) {
+ if (output.contents) {
+ // Remove any headings from the file, irrespective of the level
+ output.contents = output.contents.replace(/^#+\s.+/gm, '');
+ }
+ }
+ }
+ });
 }

.typedoc/custom-theme.mjs

@@ -1,5 +1,5 @@
 // @ts-check
-import { ReflectionKind } from 'typedoc';
+import { ArrayType, IntersectionType, ReflectionKind, ReflectionType, UnionType } from 'typedoc';
 import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';
 
 /**
@@ -36,7 +36,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
  this.partials = {
  ...superPartials,
  /**
- * Copied from default theme / source code. This hides the return type from the output
+ * Copied from default theme / source code. This hides the return type heading over the table from the output
  * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/179a54c502b318cd4f3951e5e8b90f7f7a4752d8/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts
  * @param {import('typedoc').SignatureReflection} model
  * @param {{ headingLevel: number }} options
@@ -235,6 +235,114 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
  md.push(this.partials.body(model, { headingLevel: options.headingLevel }));
 
+ return md.join('\n\n');
+ },
+ /**
+ * Copied from default theme / source code. This hides the "Type parameters" section and the declaration title from the output
+ * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/e798507a3c04f9ddf7710baf4cc7836053e438ff/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
+ * @param {import('typedoc').DeclarationReflection} model
+ * @param {{ headingLevel: number, nested?: boolean }} options
+ */
+ declaration: (model, options = { headingLevel: 2, nested: false }) => {
+ const md = [];
+
+ const opts = {
+ nested: false,
+ ...options,
+ };
+
+ if (!opts.nested && model.sources && !this.options.getValue('disableSources')) {
+ md.push(this.partials.sources(model));
+ }
+
+ if (model?.documents) {
+ md.push(
+ this.partials.documents(model, {
+ headingLevel: options.headingLevel,
+ }),
+ );
+ }
+
+ /**
+ * @type any
+ */
+ const modelType = model.type;
+ /**
+ * @type {import('typedoc').DeclarationReflection}
+ */
+ let typeDeclaration = modelType?.declaration;
+
+ if (model.type instanceof ArrayType && model.type?.elementType instanceof ReflectionType) {
+ typeDeclaration = model.type?.elementType?.declaration;
+ }
+
+ const hasTypeDeclaration =
+ Boolean(typeDeclaration) ||
+ (model.type instanceof UnionType && model.type?.types.some(type => type instanceof ReflectionType));
+
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: true,
+ showTags: false,
+ }),
+ );
+ }
+
+ if (model.type instanceof IntersectionType) {
+ model.type?.types?.forEach(intersectionType => {
+ if (intersectionType instanceof ReflectionType && !intersectionType.declaration.signatures) {
+ if (intersectionType.declaration.children) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ md.push(
+ this.partials.typeDeclaration(intersectionType.declaration, {
+ headingLevel: opts.headingLevel,
+ }),
+ );
+ }
+ }
+ });
+ }
+
+ if (hasTypeDeclaration) {
+ if (model.type instanceof UnionType) {
+ if (this.helpers.hasUsefulTypeDetails(model.type)) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ model.type.types.forEach(type => {
+ if (type instanceof ReflectionType) {
+ md.push(this.partials.someType(type, { forceCollapse: true }));
+ md.push(this.partials.typeDeclarationContainer(model, type.declaration, options));
+ } else {
+ md.push(`${this.partials.someType(type)}`);
+ }
+ });
+ }
+ } else {
+ const useHeading =
+ typeDeclaration?.children?.length &&
+ (model.kind !== ReflectionKind.Property || this.helpers.useTableFormat('properties'));
+ if (useHeading) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+ }
+ md.push(this.partials.typeDeclarationContainer(model, typeDeclaration, options));
+ }
+ }
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: false,
+ showTags: true,
+ showReturns: true,
+ }),
+ );
+ }
+
+ md.push(this.partials.inheritance(model, { headingLevel: opts.headingLevel }));
+
  return md.join('\n\n');
  },
  };

.typedoc/typedoc-prettier-config.json

@@ -0,0 +1,8 @@
+{
+ "tabWidth": 2,
+ "semi": false,
+ "singleQuote": true,
+ "printWidth": 120,
+ "useTabs": false,
+ "bracketSpacing": true
+}

package.json

@@ -48,7 +48,7 @@
  "test:integration:tanstack-start": "E2E_APP_ID=tanstack.start pnpm test:integration:base --grep @tanstack-start",
  "test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue",
  "turbo:clean": "turbo daemon clean",
- "typedoc:generate": "typedoc --tsconfig tsconfig.typedoc.json",
+ "typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/react/.gitignore

@@ -1,2 +1,3 @@
 /*/
 !/src/
+!/docs/

packages/react/docs/use-auth.md

@@ -0,0 +1,43 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/external-data/page.tsx' }}
+'use client';
+
+import { useAuth } from '@clerk/nextjs';
+
+export default function ExternalDataPage() {
+ const { userId, sessionId, getToken, isLoaded, isSignedIn } = useAuth();
+
+ const fetchExternalData = async () => {
+ const token = await getToken();
+
+ // Fetch data from an external API
+ const response = await fetch('https://api.example.com/data', {
+ headers: {
+ Authorization: `Bearer ${token}`,
+ },
+ });
+
+ return response.json();
+ };
+
+ if (!isLoaded) {
+ return <div>Loading...</div>;
+ }
+
+ if (!isSignedIn) {
+ return <div>Sign in to view this page</div>;
+ }
+
+ return (
+ <div>
+ <p>
+ Hello, {userId}! Your current active session is {sessionId}.
+ </p>
+ <button onClick={fetchExternalData}>Fetch Data</button>
+ </div>
+ );
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-in.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-in/page.tsx' }}
+'use client';
+
+import { useSignIn } from '@clerk/nextjs';
+
+export default function SignInPage() {
+ const { isLoaded, signIn } = useSignIn();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-in attempt status is {signIn?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-up.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-up/page.tsx' }}
+'use client';
+
+import { useSignUp } from '@clerk/nextjs';
+
+export default function SignUpPage() {
+ const { isLoaded, signUp } = useSignUp();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-up attempt status is {signUp?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/src/hooks/useAuth.ts

@@ -21,6 +21,9 @@ import { createGetToken, createSignOut } from './utils';
  *
  * The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/ExternalDataPage.tsx' }}
  * import { useAuth } from '@clerk/clerk-react'
  *
@@ -58,6 +61,14 @@ import { createGetToken, createSignOut } from './utils';
  * )
  * }
  * ```
+ *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-auth.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
  */
 export const useAuth = (initialAuthState: any = {}): UseAuthReturn => {
  useAssertWrappedByClerkProvider('useAuth');

packages/react/src/hooks/useSignIn.ts

@@ -13,6 +13,9 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  *
  * The following example uses the `useSignIn()` hook to access the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/SignInPage.tsx' }}
  * import { useSignIn } from '@clerk/clerk-react'
  *
@@ -28,6 +31,14 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  * }
  * ```
  *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-sign-in.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
+ *
  * @example
  * ### Create a custom sign-in flow with `useSignIn()`
  *

.changeset/green-donuts-press.md

@@ -0,0 +1,7 @@
+---
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+---
+
+Improve JSDoc documentation

.typedoc/custom-plugin.mjs

@@ -1,5 +1,43 @@
 // @ts-check
-import { MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+import { MarkdownPageEvent, MarkdownRendererEvent } from 'typedoc-plugin-markdown';
+
+/**
+ * A list of files where we want to remove any headings
+ */
+const FILES_WITHOUT_HEADINGS = [
+ 'use-organization-return.mdx',
+ 'use-organization-params.mdx',
+ 'paginated-resources.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'pages-or-infinite-options.mdx',
+ 'paginated-hook-config.mdx',
+ 'use-organization-list-return.mdx',
+ 'use-organization-list-params.mdx',
+];
+
+/**
+ * An array of tuples where the first element is the file name and the second element is the new path.
+ */
+const LINK_REPLACEMENTS = [
+ ['clerk-paginated-response', '/docs/references/javascript/types/clerk-paginated-response'],
+ ['paginated-resources', '#paginated-resources'],
+];
+
+/**
+ * Inside the generated MDX files are links to other generated MDX files. These relative links need to be replaced with absolute links to pages that exist on clerk.com.
+ * For example, `[Foobar](../../foo/bar.mdx)` needs to be replaced with `[Foobar](/docs/foo/bar)`.
+ * It also shouldn't matter how level deep the relative link is.
+ *
+ * This function returns an array of `{ pattern: string, replace: string }` to pass into the `typedoc-plugin-replace-text` plugin.
+ */
+function getRelativeLinkReplacements() {
+ return LINK_REPLACEMENTS.map(([fileName, newPath]) => {
+ return {
+ pattern: new RegExp(`\\((?:\\.{1,2}\\/)+.*?${fileName}\\.mdx\\)`, 'g'),
+ replace: `(${newPath})`,
+ };
+ });
+}
 
 /**
  * @param {string} str
@@ -13,8 +51,9 @@ function toKebabCase(str) {
  */
 export function load(app) {
  app.renderer.on(MarkdownRendererEvent.BEGIN, output => {
- // Do not output README.mdx files
+ // Modify the output object
  output.urls = output.urls
+ // Do not output README.mdx files
  ?.filter(e => !e.url.endsWith('README.mdx'))
  .map(e => {
  // Convert URLs (by default camelCase) to kebab-case
@@ -23,7 +62,37 @@ export function load(app) {
  e.url = kebabUrl;
  e.model.url = kebabUrl;
 
+ /**
+ * For the `@clerk/shared` package it outputs the hooks as for example: shared/react/hooks/use-clerk/functions/use-clerk.mdx.
+ * It also places the interfaces as shared/react/hooks/use-organization/interfaces/use-organization-return.mdx
+ * Group all those .mdx files under shared/react/hooks
+ */
+ if (e.url.includes('shared/react/hooks')) {
+ e.url = e.url.replace(/\/[^/]+\/(functions|interfaces)\//, '/');
+ e.model.url = e.url;
+ }
+
  return e;
  });
  });
+
+ app.renderer.on(MarkdownPageEvent.END, output => {
+ const fileName = output.url.split('/').pop();
+ const linkReplacements = getRelativeLinkReplacements();
+
+ for (const { pattern, replace } of linkReplacements) {
+ if (output.contents) {
+ output.contents = output.contents.replace(pattern, replace);
+ }
+ }
+
+ if (fileName) {
+ if (FILES_WITHOUT_HEADINGS.includes(fileName)) {
+ if (output.contents) {
+ // Remove any headings from the file, irrespective of the level
+ output.contents = output.contents.replace(/^#+\s.+/gm, '');
+ }
+ }
+ }
+ });
 }

.typedoc/custom-theme.mjs

@@ -1,5 +1,5 @@
 // @ts-check
-import { ReflectionKind } from 'typedoc';
+import { ArrayType, IntersectionType, ReflectionKind, ReflectionType, UnionType } from 'typedoc';
 import { MarkdownTheme, MarkdownThemeContext } from 'typedoc-plugin-markdown';
 
 /**
@@ -36,7 +36,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
  this.partials = {
  ...superPartials,
  /**
- * Copied from default theme / source code. This hides the return type from the output
+ * Copied from default theme / source code. This hides the return type heading over the table from the output
  * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/179a54c502b318cd4f3951e5e8b90f7f7a4752d8/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureReturns.ts
  * @param {import('typedoc').SignatureReflection} model
  * @param {{ headingLevel: number }} options
@@ -235,6 +235,114 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
  md.push(this.partials.body(model, { headingLevel: options.headingLevel }));
 
+ return md.join('\n\n');
+ },
+ /**
+ * Copied from default theme / source code. This hides the "Type parameters" section and the declaration title from the output
+ * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/e798507a3c04f9ddf7710baf4cc7836053e438ff/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
+ * @param {import('typedoc').DeclarationReflection} model
+ * @param {{ headingLevel: number, nested?: boolean }} options
+ */
+ declaration: (model, options = { headingLevel: 2, nested: false }) => {
+ const md = [];
+
+ const opts = {
+ nested: false,
+ ...options,
+ };
+
+ if (!opts.nested && model.sources && !this.options.getValue('disableSources')) {
+ md.push(this.partials.sources(model));
+ }
+
+ if (model?.documents) {
+ md.push(
+ this.partials.documents(model, {
+ headingLevel: options.headingLevel,
+ }),
+ );
+ }
+
+ /**
+ * @type any
+ */
+ const modelType = model.type;
+ /**
+ * @type {import('typedoc').DeclarationReflection}
+ */
+ let typeDeclaration = modelType?.declaration;
+
+ if (model.type instanceof ArrayType && model.type?.elementType instanceof ReflectionType) {
+ typeDeclaration = model.type?.elementType?.declaration;
+ }
+
+ const hasTypeDeclaration =
+ Boolean(typeDeclaration) ||
+ (model.type instanceof UnionType && model.type?.types.some(type => type instanceof ReflectionType));
+
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: true,
+ showTags: false,
+ }),
+ );
+ }
+
+ if (model.type instanceof IntersectionType) {
+ model.type?.types?.forEach(intersectionType => {
+ if (intersectionType instanceof ReflectionType && !intersectionType.declaration.signatures) {
+ if (intersectionType.declaration.children) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ md.push(
+ this.partials.typeDeclaration(intersectionType.declaration, {
+ headingLevel: opts.headingLevel,
+ }),
+ );
+ }
+ }
+ });
+ }
+
+ if (hasTypeDeclaration) {
+ if (model.type instanceof UnionType) {
+ if (this.helpers.hasUsefulTypeDetails(model.type)) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+
+ model.type.types.forEach(type => {
+ if (type instanceof ReflectionType) {
+ md.push(this.partials.someType(type, { forceCollapse: true }));
+ md.push(this.partials.typeDeclarationContainer(model, type.declaration, options));
+ } else {
+ md.push(`${this.partials.someType(type)}`);
+ }
+ });
+ }
+ } else {
+ const useHeading =
+ typeDeclaration?.children?.length &&
+ (model.kind !== ReflectionKind.Property || this.helpers.useTableFormat('properties'));
+ if (useHeading) {
+ md.push(heading(opts.headingLevel, this.i18n.theme_type_declaration()));
+ }
+ md.push(this.partials.typeDeclarationContainer(model, typeDeclaration, options));
+ }
+ }
+ if (model.comment) {
+ md.push(
+ this.partials.comment(model.comment, {
+ headingLevel: opts.headingLevel,
+ showSummary: false,
+ showTags: true,
+ showReturns: true,
+ }),
+ );
+ }
+
+ md.push(this.partials.inheritance(model, { headingLevel: opts.headingLevel }));
+
  return md.join('\n\n');
  },
  };

.typedoc/typedoc-prettier-config.json

@@ -0,0 +1,8 @@
+{
+ "tabWidth": 2,
+ "semi": false,
+ "singleQuote": true,
+ "printWidth": 120,
+ "useTabs": false,
+ "bracketSpacing": true
+}

package.json

@@ -48,7 +48,7 @@
  "test:integration:tanstack-start": "E2E_APP_ID=tanstack.start pnpm test:integration:base --grep @tanstack-start",
  "test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue",
  "turbo:clean": "turbo daemon clean",
- "typedoc:generate": "typedoc --tsconfig tsconfig.typedoc.json",
+ "typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/react/.gitignore

@@ -1,2 +1,3 @@
 /*/
 !/src/
+!/docs/

packages/react/docs/use-auth.md

@@ -0,0 +1,43 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/external-data/page.tsx' }}
+'use client';
+
+import { useAuth } from '@clerk/nextjs';
+
+export default function ExternalDataPage() {
+ const { userId, sessionId, getToken, isLoaded, isSignedIn } = useAuth();
+
+ const fetchExternalData = async () => {
+ const token = await getToken();
+
+ // Fetch data from an external API
+ const response = await fetch('https://api.example.com/data', {
+ headers: {
+ Authorization: `Bearer ${token}`,
+ },
+ });
+
+ return response.json();
+ };
+
+ if (!isLoaded) {
+ return <div>Loading...</div>;
+ }
+
+ if (!isSignedIn) {
+ return <div>Sign in to view this page</div>;
+ }
+
+ return (
+ <div>
+ <p>
+ Hello, {userId}! Your current active session is {sessionId}.
+ </p>
+ <button onClick={fetchExternalData}>Fetch Data</button>
+ </div>
+ );
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-in.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-in/page.tsx' }}
+'use client';
+
+import { useSignIn } from '@clerk/nextjs';
+
+export default function SignInPage() {
+ const { isLoaded, signIn } = useSignIn();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-in attempt status is {signIn?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/docs/use-sign-up.md

@@ -0,0 +1,20 @@
+<!-- #region nextjs-01 -->
+
+```tsx {{ filename: 'app/sign-up/page.tsx' }}
+'use client';
+
+import { useSignUp } from '@clerk/nextjs';
+
+export default function SignUpPage() {
+ const { isLoaded, signUp } = useSignUp();
+
+ if (!isLoaded) {
+ // Handle loading state
+ return null;
+ }
+
+ return <div>The current sign-up attempt status is {signUp?.status}.</div>;
+}
+```
+
+<!-- #endregion nextjs-01 -->

packages/react/src/hooks/useAuth.ts

@@ -21,6 +21,9 @@ import { createGetToken, createSignOut } from './utils';
  *
  * The following example demonstrates how to use the `useAuth()` hook to access the current auth state, like whether the user is signed in or not. It also includes a basic example for using the `getToken()` method to retrieve a session token for fetching data from an external resource.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/ExternalDataPage.tsx' }}
  * import { useAuth } from '@clerk/clerk-react'
  *
@@ -58,6 +61,14 @@ import { createGetToken, createSignOut } from './utils';
  * )
  * }
  * ```
+ *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-auth.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
  */
 export const useAuth = (initialAuthState: any = {}): UseAuthReturn => {
  useAssertWrappedByClerkProvider('useAuth');

packages/react/src/hooks/useSignIn.ts

@@ -13,6 +13,9 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  *
  * The following example uses the `useSignIn()` hook to access the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state.
  *
+ * <Tabs items='React,Next.js'>
+ * <Tab>
+ *
  * ```tsx {{ filename: 'src/pages/SignInPage.tsx' }}
  * import { useSignIn } from '@clerk/clerk-react'
  *
@@ -28,6 +31,14 @@ import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvid
  * }
  * ```
  *
+ * </Tab>
+ * <Tab>
+ *
+ * {@include ../../docs/use-sign-in.md#nextjs-01}
+ *
+ * </Tab>
+ * </Tabs>
+ *
  * @example
  * ### Create a custom sign-in flow with `useSignIn()`
  *