docs(shared): Fix Typedoc links by alexisintech · Pull Request #8746 · clerk/javascript

alexisintech · 2026-06-04T00:15:07Z

Description

Fixes broken/sub-optimal documentation links in two places:

@clerk/shared JSDoc URLs — corrects three external links that surface in IDE tooltips and the generated reference docs:
- SessionResource.agent: /reference/objects/agent-task → /reference/types/agent-task
- SignUpFutureSSOParams.strategy: /reference/types/oauth-strategy → /reference/types/sso#o-auth-strategy
- SignUpFutureSSOParams.strategy: /reference/types/enterprise-sso-strategy → /reference/types/sso#enterprise-sso-strategy
.typedoc/custom-plugin.mjs catch-all patterns — unifies 12 link-replacement regexes to the more-encompassing form (?<![\[\w + "" + #]) + "" + ?Foo + "" + ?(?![]\w + "" + ]), so they match identifiers both with and without backticks across more surrounding contexts. Newly linkifies:
- `ClerkAPIResponseError` when wrapped in backticks (previously excluded by the lookbehind)
- OrganizationPublicMetadata inside <code>...</code> HTML pipe-wrappers

Verified by snapshotting .typedoc/docs before/after into tmp/baseline-docs vs tmp/wip-docs — only 3 generated MDX files diff, all expected linkification gains. All 16 .typedoc/ vitest tests pass.

Checklist

pnpm test runs as expected (.typedoc/ vitest suite: 16/16 passing; full-repo test run pending CI).
pnpm build runs as expected (verified via pnpm typedoc:generate:skip-build against existing dist artifacts).
JSDoc comments have been updated for the affected @clerk/shared exports.
No corresponding clerk-docs change needed — the corrected URLs point to pages that already exist.

Type of change

…exts Unify 12 catch-all replacement patterns in `.typedoc/custom-plugin.mjs` to use the more-encompassing form `(?<![\[\w`#])`?Foo`?(?![\]\w`])` so they match both backticked and bare identifiers. Newly linkifies `ClerkAPIResponseError` (was excluded from backticked form) and `OrganizationPublicMetadata` inside `<code>` HTML tags. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

changeset-bot · 2026-06-04T00:15:12Z

🦋 Changeset detected

Latest commit: 4b60067

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-06-04T00:15:13Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 4, 2026 12:21am

pkg-pr-new · 2026-06-04T00:17:54Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8746

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8746

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8746

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8746

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8746

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8746

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8746

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8746

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8746

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8746

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8746

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8746

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8746

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8746

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8746

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8746

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8746

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8746

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8746

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8746

commit: 4b60067

github-actions · 2026-06-04T00:18:46Z

API Changes Report

Generated by Break Check on 2026-06-04T00:22:56.574Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	0
🟡 Non-breaking changes	3
🟢 Additions	0

🤖 This report was reviewed by claude-sonnet-4-6.

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.

@clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.

@clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.

@clerk/testing ./cypress: Symbol not found for identifier: Cypress

@clerk/astro

Current version: 3.3.3
Recommended bump: MINOR → 3.4.0

Subpath `./client`

🟡 Non-breaking Changes (3)

Modified: `$authStore`

  $authStore: nanostores.ReadableAtom<{
      userId: string | null | undefined;
-     user: _clerk_shared__chunks_index_DRe3eUSq.gs | null | undefined;
+     user: _clerk_shared__chunks_index_PY1DuvnM.gs | null | undefined;
      sessionId: string | null | undefined;
-     session: _clerk_shared__chunks_index_DRe3eUSq.ts | null | undefined;
+     session: _clerk_shared__chunks_index_PY1DuvnM.ts | null | undefined;
      sessionStatus: "active" | "pending" | undefined;
-     sessionClaims: _clerk_shared__chunks_index_DRe3eUSq.io | null | undefined;
-     organization: _clerk_shared__chunks_index_DRe3eUSq.wo | null | undefined;
+     sessionClaims: _clerk_shared__chunks_index_PY1DuvnM.io | null | undefined;
+     organization: _clerk_shared__chunks_index_PY1DuvnM.wo | null | undefined;
      orgId: string | null | undefined;
      orgRole: string | null | undefined;
      orgSlug: string | null | undefined;
-     orgPermissions: _clerk_shared__chunks_index_DRe3eUSq.bm<_clerk_shared__chunks_index_DRe3eUSq.do>[] | null | undefined;
-     actor: _clerk_shared__chunks_index_DRe3eUSq.$a | null | undefined;
+     orgPermissions: _clerk_shared__chunks_index_PY1DuvnM.bm<_clerk_shared__chunks_index_PY1DuvnM.do>[] | null | undefined;
+     actor: _clerk_shared__chunks_index_PY1DuvnM.$a | null | undefined;
      factorVerificationAge: [number, number] | null;
  }>

Static analyzer: Breaking change in variable $authStore: Type changed: $authStore:import("nanostores").ReadableAtom<{userId:string|null|undefined;user:!_clerk_shared__chunks_index_DRe3eUSq.g… → $authStore:import("nanostores").ReadableAtom<{userId:string|null|undefined;user:!_clerk_shared__chunks_index_PY1DuvnM.g…

🤖 AI review (reclassified as non-breaking) (85%): The only change is an internal chunk hash rename (DRe3eUSq → PY1DuvnM) in the re-exported type aliases; all named properties and their structural types (userId, sessionId, sessionStatus, factorVerificationAge, etc.) are identical, so no well-typed consumer code is affected.

Modified: `$organizationStore`

- $organizationStore: nanostores.ReadableAtom<_clerk_shared__chunks_index_DRe3eUSq.wo | null | undefined>
+ $organizationStore: nanostores.ReadableAtom<_clerk_shared__chunks_index_PY1DuvnM.wo | null | undefined>

Static analyzer: Breaking change in variable $organizationStore: Type changed: $organizationStore:import("nanostores").ReadableAtom<!_clerk_shared__chunks_index_DRe3eUSq.wo:type|null|undefined> → $organizationStore:import("nanostores").ReadableAtom<!_clerk_shared__chunks_index_PY1DuvnM.wo:type|null|undefined>

🤖 AI review (reclassified as non-breaking) (85%): The change is purely an internal chunk hash rename in the module path; the exposed type alias wo and its structural shape are unchanged, so no consumer-visible type contract is altered.

Modified: `$userStore`

- $userStore: nanostores.ReadableAtom<_clerk_shared__chunks_index_DRe3eUSq.gs | null | undefined>
+ $userStore: nanostores.ReadableAtom<_clerk_shared__chunks_index_PY1DuvnM.gs | null | undefined>

Static analyzer: Breaking change in variable $userStore: Type changed: $userStore:import("nanostores").ReadableAtom<!_clerk_shared__chunks_index_DRe3eUSq.gs:type|null|undefined> → $userStore:import("nanostores").ReadableAtom<!_clerk_shared__chunks_index_PY1DuvnM.gs:type|null|undefined>

🤖 AI review (reclassified as non-breaking) (85%): The change is purely an internal chunk hash rename in the module path; the exposed type alias gs and its structural shape are unchanged, so no consumer-visible type contract is altered.

Report generated by Break Check

_{Last ran on 4b60067. Pushes that change no tracked declarations (no API surface change vs. base) are skipped and don't update this comment.}

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-06-04T00:20:41Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 4c15a1ce-b1ba-46a9-9a07-71c21db9b668

📥 Commits

Reviewing files that changed from the base of the PR and between a8c5f2c and 4b60067.

📒 Files selected for processing (1)

.changeset/stale-steaks-accept.md

✅ Files skipped from review due to trivial changes (1)

.changeset/stale-steaks-accept.md

📝 Walkthrough

Walkthrough

This PR updates TypeDoc plugin regex patterns in .typedoc/custom-plugin.mjs to standardize identifier linkification across multiple types. The changes introduce a generalized optional-backtick regex pattern with improved negative lookaround matching for ClerkAPIResponseError, LoadedClerk, SetActiveParams, SignInRedirectOptions, SignUpRedirectOptions, SignUpUnsafeMetadata, TasksRedirectOptions, and organization metadata types. The UserResource link text formatting is adjusted to remove backticks from the rendered link label. Two type definition files receive JSDoc updates: SessionResource.agent clarifies agent actor behavior, and SignUpFutureSSOParams.strategy references updated strategy type documentation anchors.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(shared): Fix Typedoc links' clearly and concisely summarizes the main objective of the PR—fixing documentation links in the `@clerk/shared` package and TypeDoc configuration.
Description check	✅ Passed	The description is highly detailed and directly related to the changeset, explaining the specific broken links fixed, the regex pattern improvements made, verification steps taken, and all checks passed.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

wobsoriano

looks good

alexisintech and others added 2 commits June 3, 2026 17:03

fix broken links

7d1e57a

alexisintech changed the title ~~fix(shared): Fix Typedoc links~~ docs(shared): Fix Typedoc links Jun 4, 2026

chore(repo): add empty changeset

4b60067

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview June 4, 2026 00:21 View deployment

alexisintech enabled auto-merge (squash) June 4, 2026 00:22

alexisintech mentioned this pull request Jun 4, 2026

Generate object reference docs clerk/clerk-docs#3286

Merged

wobsoriano approved these changes Jun 4, 2026

View reviewed changes

alexisintech merged commit 9c9960a into main Jun 4, 2026
45 checks passed

alexisintech deleted the aa/typedoc-link-updates branch June 4, 2026 00:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(shared): Fix Typedoc links#8746

docs(shared): Fix Typedoc links#8746
alexisintech merged 3 commits into
mainfrom
aa/typedoc-link-updates

alexisintech commented Jun 4, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 4, 2026 •

edited

Loading

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

wobsoriano left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

alexisintech commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

changeset-bot Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Changes Report

Summary

@clerk/astro

Subpath ./client

🟡 Non-breaking Changes (3)

Modified: $authStore

Modified: $organizationStore

Modified: $userStore

Uh oh!

coderabbitai Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alexisintech commented Jun 4, 2026 •

edited

Loading

changeset-bot Bot commented Jun 4, 2026 •

edited

Loading

vercel Bot commented Jun 4, 2026 •

edited

Loading

pkg-pr-new Bot commented Jun 4, 2026 •

edited

Loading

github-actions Bot commented Jun 4, 2026 •

edited

Loading

Subpath `./client`

Modified: `$authStore`

Modified: `$organizationStore`

Modified: `$userStore`

coderabbitai Bot commented Jun 4, 2026 •

edited

Loading