From 8f5d7f4ddbe1cc3c8bb254c213d435a4e78502fc Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Tue, 29 Sep 2026 15:15:57 -0600 Subject: [PATCH 1/8] ci(repo): dispatch TypeDoc sync to clerk/clerk --- .changeset/fix-typedoc-workflow.md | 2 ++ .github/workflows/release.yml | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 .changeset/fix-typedoc-workflow.md diff --git a/.changeset/fix-typedoc-workflow.md b/.changeset/fix-typedoc-workflow.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/fix-typedoc-workflow.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d4b4a3615b3..d58214d624f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -148,7 +148,7 @@ jobs: const targets = [ { repo: 'sdk-infra-workers', workflow_id: 'update-pkg-versions.yml', inputs: { clerkjsVersion, clerkUiVersion } }, { repo: 'dashboard', workflow_id: 'prepare-nextjs-sdk-update.yml', inputs: { version: nextjsVersion } }, - { repo: 'clerk-docs', workflow_id: 'typedoc.yml' }, + { repo: 'clerk', workflow_id: 'docs-typedoc.yml' }, ]; const results = await Promise.allSettled( targets.map(t => github.rest.actions.createWorkflowDispatch({ owner: 'clerk', ref: 'main', ...t })) @@ -230,7 +230,7 @@ jobs: const targets = [ { repo: 'sdk-infra-workers', workflow_id: 'update-pkg-versions.yml', inputs: { clerkjsVersion, clerkUiVersion } }, { repo: 'dashboard', workflow_id: 'prepare-nextjs-sdk-update.yml', inputs: { version: nextjsVersion } }, - { repo: 'clerk-docs', workflow_id: 'typedoc.yml' }, + { repo: 'clerk', workflow_id: 'docs-typedoc.yml' }, ]; const results = await Promise.allSettled( targets.map(t => github.rest.actions.createWorkflowDispatch({ owner: 'clerk', ref: 'main', ...t })) From b0643624f55380d99eede9901cf39cb7c3a58a73 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Tue, 29 Sep 2026 15:43:16 -0600 Subject: [PATCH 2/8] ci(repo): pin TypeDoc sync to released commit --- .github/workflows/release.yml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d58214d624f..074fe0c8a95 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -130,7 +130,6 @@ jobs: - name: Trigger workflows on related repos if: steps.changesets.outputs.published == 'true' - continue-on-error: true uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 with: result-encoding: string @@ -148,7 +147,7 @@ jobs: const targets = [ { repo: 'sdk-infra-workers', workflow_id: 'update-pkg-versions.yml', inputs: { clerkjsVersion, clerkUiVersion } }, { repo: 'dashboard', workflow_id: 'prepare-nextjs-sdk-update.yml', inputs: { version: nextjsVersion } }, - { repo: 'clerk', workflow_id: 'docs-typedoc.yml' }, + { repo: 'clerk', workflow_id: 'docs-typedoc.yml', inputs: { javascript_ref: context.sha } }, ]; const results = await Promise.allSettled( targets.map(t => github.rest.actions.createWorkflowDispatch({ owner: 'clerk', ref: 'main', ...t })) @@ -171,7 +170,6 @@ jobs: # if the packages are already live. - name: Recover downstream notifications if: always() && steps.changesets.conclusion == 'failure' - continue-on-error: true uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7 with: result-encoding: string @@ -230,7 +228,7 @@ jobs: const targets = [ { repo: 'sdk-infra-workers', workflow_id: 'update-pkg-versions.yml', inputs: { clerkjsVersion, clerkUiVersion } }, { repo: 'dashboard', workflow_id: 'prepare-nextjs-sdk-update.yml', inputs: { version: nextjsVersion } }, - { repo: 'clerk', workflow_id: 'docs-typedoc.yml' }, + { repo: 'clerk', workflow_id: 'docs-typedoc.yml', inputs: { javascript_ref: context.sha } }, ]; const results = await Promise.allSettled( targets.map(t => github.rest.actions.createWorkflowDispatch({ owner: 'clerk', ref: 'main', ...t })) From 256372541544bbaecfafc75688aa73297f01b58c Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Tue, 29 Sep 2026 20:09:33 -0600 Subject: [PATCH 3/8] ci(repo): limit release failure to TypeDoc dispatch --- .github/workflows/release.yml | 36 +++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 074fe0c8a95..a428e4c1de0 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -147,17 +147,25 @@ jobs: const targets = [ { repo: 'sdk-infra-workers', workflow_id: 'update-pkg-versions.yml', inputs: { clerkjsVersion, clerkUiVersion } }, { repo: 'dashboard', workflow_id: 'prepare-nextjs-sdk-update.yml', inputs: { version: nextjsVersion } }, - { repo: 'clerk', workflow_id: 'docs-typedoc.yml', inputs: { javascript_ref: context.sha } }, + { repo: 'clerk', workflow_id: 'docs-typedoc.yml', inputs: { javascript_ref: context.sha }, critical: true }, ]; const results = await Promise.allSettled( - targets.map(t => github.rest.actions.createWorkflowDispatch({ owner: 'clerk', ref: 'main', ...t })) + targets.map(({ repo, workflow_id, inputs }) => + github.rest.actions.createWorkflowDispatch({ owner: 'clerk', repo, workflow_id, ref: 'main', inputs }) + ) ); const failures = results .map((r, i) => r.status === 'rejected' ? { target: targets[i], reason: r.reason } : null) .filter(Boolean); if (failures.length) { - failures.forEach(f => core.error(`Dispatch to ${f.target.repo}/${f.target.workflow_id} failed: ${f.reason?.message ?? f.reason}`)); - core.setFailed(`${failures.length} downstream dispatch(es) failed`); + failures.forEach(f => { + const message = `Dispatch to ${f.target.repo}/${f.target.workflow_id} failed: ${f.reason?.message ?? f.reason}`; + if (f.target.critical) { + core.setFailed(message); + } else { + core.warning(message); + } + }); } } else{ core.warning("Changeset in pre-mode should not prepare a ClerkJS production release") @@ -228,24 +236,32 @@ jobs: const targets = [ { repo: 'sdk-infra-workers', workflow_id: 'update-pkg-versions.yml', inputs: { clerkjsVersion, clerkUiVersion } }, { repo: 'dashboard', workflow_id: 'prepare-nextjs-sdk-update.yml', inputs: { version: nextjsVersion } }, - { repo: 'clerk', workflow_id: 'docs-typedoc.yml', inputs: { javascript_ref: context.sha } }, + { repo: 'clerk', workflow_id: 'docs-typedoc.yml', inputs: { javascript_ref: context.sha }, critical: true }, ]; const results = await Promise.allSettled( - targets.map(t => github.rest.actions.createWorkflowDispatch({ owner: 'clerk', ref: 'main', ...t })) + targets.map(({ repo, workflow_id, inputs }) => + github.rest.actions.createWorkflowDispatch({ owner: 'clerk', repo, workflow_id, ref: 'main', inputs }) + ) ); const failures = results .map((r, i) => r.status === 'rejected' ? { target: targets[i], reason: r.reason } : null) .filter(Boolean); if (failures.length) { - failures.forEach(f => core.error(`Recovery dispatch to ${f.target.repo}/${f.target.workflow_id} failed: ${f.reason?.message ?? f.reason}`)); - core.setFailed(`${failures.length} recovery dispatch(es) failed`); + failures.forEach(f => { + const message = `Recovery dispatch to ${f.target.repo}/${f.target.workflow_id} failed: ${f.reason?.message ?? f.reason}`; + if (f.target.critical) { + core.setFailed(message); + } else { + core.warning(message); + } + }); } else { core.notice('Recovery dispatch completed successfully'); } - name: Generate notification payload id: notification - if: steps.changesets.outputs.published == 'true' + if: always() && steps.changesets.outputs.published == 'true' env: PUBLISHED_PACKAGES: ${{ steps.changesets.outputs.publishedPackages }} GH_ACTOR: ${{ github.actor }} @@ -259,7 +275,7 @@ jobs: - name: Send commit log to Slack id: slack - if: steps.changesets.outputs.published == 'true' + if: always() && steps.changesets.outputs.published == 'true' && steps.notification.outcome == 'success' uses: slackapi/slack-github-action@fcfb566f8b0aab22203f066d80ca1d7e4b5d05b3 # v1.27.1 with: payload: ${{ steps.notification.outputs.payload }} From 9fe7ab0499fd3c374cb900d28173b254a80d8f81 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Wed, 30 Sep 2026 08:02:49 -0600 Subject: [PATCH 4/8] ci(repo): respect cancellation in release announcement --- .github/workflows/release.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a428e4c1de0..2dad4a14cfb 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -261,7 +261,7 @@ jobs: - name: Generate notification payload id: notification - if: always() && steps.changesets.outputs.published == 'true' + if: ${{ !cancelled() && steps.changesets.outputs.published == 'true' }} env: PUBLISHED_PACKAGES: ${{ steps.changesets.outputs.publishedPackages }} GH_ACTOR: ${{ github.actor }} @@ -275,7 +275,7 @@ jobs: - name: Send commit log to Slack id: slack - if: always() && steps.changesets.outputs.published == 'true' && steps.notification.outcome == 'success' + if: ${{ !cancelled() && steps.changesets.outputs.published == 'true' && steps.notification.outcome == 'success' }} uses: slackapi/slack-github-action@fcfb566f8b0aab22203f066d80ca1d7e4b5d05b3 # v1.27.1 with: payload: ${{ steps.notification.outputs.payload }} From 1e842c2e363fa1e7663680995ec23638f0d33aa8 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Wed, 30 Sep 2026 08:23:50 -0600 Subject: [PATCH 5/8] ci(repo): drop unused title-lint dependency --- .github/workflows/pr-title-linter.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pr-title-linter.yml b/.github/workflows/pr-title-linter.yml index e67aeb124f1..0d3f26f9a0c 100644 --- a/.github/workflows/pr-title-linter.yml +++ b/.github/workflows/pr-title-linter.yml @@ -34,5 +34,5 @@ jobs: PR_TITLE: ${{ github.event.pull_request.title }} run: | npm init --scope=clerk --yes - npm i --save-dev @commitlint/config-conventional @commitlint/cli globby --audit=false --fund=false + npm i --save-dev @commitlint/config-conventional @commitlint/cli --audit=false --fund=false echo "$PR_TITLE" | npm exec @commitlint/cli -- --config commitlint.config.ts From e22a3e982682af14710c9b8a5a119d2afe84fabc Mon Sep 17 00:00:00 2001 From: Michael Novotny Date: Wed, 30 Sep 2026 10:41:17 -0500 Subject: [PATCH 6/8] docs(repo): drop retired clerk-docs TypeDoc workflow link Co-Authored-By: Claude Opus 5.5 --- docs/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 2da2b4d61b1..d8f464bc0d5 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -192,7 +192,7 @@ For a comprehensive guide on **authoring** JSDoc/Typedoc comments, see [this gui To review your changes locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterwards, you can inspect the MDX files inside `.typedoc/docs`. But if you want to preview how the Typedoc output will look in Clerk Docs, there's a few things you need to do first: -Create a PR that includes your changes to any Typedoc comments. Once the PR has been merged and a release is published, a PR will [automatically](https://github.com/clerk/clerk-docs/blob/main/.github/workflows/typedoc.yml) be opened in `clerk-docs` to merge in the Typedoc changes. +Create a PR that includes your changes to any Typedoc comments. Once the PR has been merged and a release is published, the release workflow automatically opens a PR in Clerk's docs repository with the Typedoc changes. Typedoc output is embedded in `clerk-docs` files with the `` component. For example, if you updated Typedoc comments for the `useAuth()` hook in `clerk/javascript`, you'll need to make sure that in `clerk-docs`, in the `/hooks/use-auth.mdx` file, there's a `` component linked to the `./clerk-typedoc/react/use-auth.mdx` file, like: @@ -202,7 +202,7 @@ Typedoc output is embedded in `clerk-docs` files with the `` componen Read more about this in the [`clerk-docs` CONTRIBUTING.md](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#typedoc-). -Then, to preview how the `` component renders, the `clerk-docs` PR will have a Vercel preview. Or to get local previews set up, see the [section in `clerk/clerk` about setting up local docs](https://github.com/clerk/clerk?tab=readme-ov-file#5-optional-set-up-local-docs). +Then, to preview how the `` component renders, that docs PR will have a Vercel preview. Or to get local previews set up, see the [section in `clerk/clerk` about setting up local docs](https://github.com/clerk/clerk?tab=readme-ov-file#5-optional-set-up-local-docs). ### Experimental and internal APIs From 12bcd6da4bcfd76ac06f7882272a1a58d979c622 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Wed, 30 Sep 2026 13:55:25 -0600 Subject: [PATCH 7/8] docs: clarify TypeDoc sync destination and guide link --- docs/CICD.md | 2 +- docs/CONTRIBUTING.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/CICD.md b/docs/CICD.md index 8e474a8458b..30a63181c98 100644 --- a/docs/CICD.md +++ b/docs/CICD.md @@ -14,7 +14,7 @@ A stable release will be triggered every time the "ci(repo): Version packages" P - All SDKs will be published to `npm`, except for those found in the excluded packages list in `.changeset/config.json`, or any packages with `private: true` set in their `package.json` file. - A workflow dispatch will be triggered to update the `clerkjs-proxy` worker in `clerk/sdk-infra-workers`. - A workflow dispatch will be triggered to update the `@clerk/nextjs` version in `clerk/dashboard`. -- A workflow dispatch will be triggered to update the typedoc generated docs in `clerk/clerk-docs`. +- A workflow dispatch will be triggered to update the generated TypeDoc files in `clerk/clerk` under `clerk-docs/clerk-typedoc/`. For details regarding the package versioning/publishing process, refer to the [Publishing docs](https://github.com/clerk/javascript/blob/main/docs/PUBLISH.md). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index d8f464bc0d5..42b2ef80bc4 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -192,7 +192,7 @@ For a comprehensive guide on **authoring** JSDoc/Typedoc comments, see [this gui To review your changes locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterwards, you can inspect the MDX files inside `.typedoc/docs`. But if you want to preview how the Typedoc output will look in Clerk Docs, there's a few things you need to do first: -Create a PR that includes your changes to any Typedoc comments. Once the PR has been merged and a release is published, the release workflow automatically opens a PR in Clerk's docs repository with the Typedoc changes. +Create a PR that includes your changes to any Typedoc comments. Once the PR has been merged and a release is published, the release workflow automatically opens a PR in `clerk/clerk` with the Typedoc changes. Typedoc output is embedded in `clerk-docs` files with the `` component. For example, if you updated Typedoc comments for the `useAuth()` hook in `clerk/javascript`, you'll need to make sure that in `clerk-docs`, in the `/hooks/use-auth.mdx` file, there's a `` component linked to the `./clerk-typedoc/react/use-auth.mdx` file, like: @@ -200,7 +200,7 @@ Typedoc output is embedded in `clerk-docs` files with the `` componen ``` -Read more about this in the [`clerk-docs` CONTRIBUTING.md](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#typedoc-). +Read more about this in the [`clerk-docs` CONTRIBUTING.md](https://github.com/clerk/clerk-docs/blob/main/contributing/CONTRIBUTING.md#typedoc-). Then, to preview how the `` component renders, that docs PR will have a Vercel preview. Or to get local previews set up, see the [section in `clerk/clerk` about setting up local docs](https://github.com/clerk/clerk?tab=readme-ov-file#5-optional-set-up-local-docs). From 275f1b78ddb52b9d4af4eb671bdc17e3e65acc23 Mon Sep 17 00:00:00 2001 From: Sarah Soutoul Date: Wed, 30 Sep 2026 13:59:55 -0600 Subject: [PATCH 8/8] docs: restore TypeDoc PR wording --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 42b2ef80bc4..9fae4c95a29 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -192,7 +192,7 @@ For a comprehensive guide on **authoring** JSDoc/Typedoc comments, see [this gui To review your changes locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterwards, you can inspect the MDX files inside `.typedoc/docs`. But if you want to preview how the Typedoc output will look in Clerk Docs, there's a few things you need to do first: -Create a PR that includes your changes to any Typedoc comments. Once the PR has been merged and a release is published, the release workflow automatically opens a PR in `clerk/clerk` with the Typedoc changes. +Create a PR that includes your changes to any Typedoc comments. Once the PR has been merged and a release is published, the release workflow automatically opens a PR in Clerk's docs repository with the Typedoc changes. Typedoc output is embedded in `clerk-docs` files with the `` component. For example, if you updated Typedoc comments for the `useAuth()` hook in `clerk/javascript`, you'll need to make sure that in `clerk-docs`, in the `/hooks/use-auth.mdx` file, there's a `` component linked to the `./clerk-typedoc/react/use-auth.mdx` file, like: