Skip to content

chore(repo): Switch typedocs to being generated in clerk-docs directly #6267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 16, 2025
Merged

chore(repo): Switch typedocs to being generated in clerk-docs directly #6267

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
75db587
write to temp-docs then move over to docs folder
NWylynko Jul 4, 2025
8a8598e
Call typedoc.yml in the `clerk-docs` repo instead https://github.com/…
NWylynko Jul 7, 2025
b298d53
Merge branch 'main' into nick/typedoc-atomic-write
panteliselef Jul 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,8 @@ jobs:
github.rest.actions.createWorkflowDispatch({
owner: 'clerk',
repo: 'generated-typedoc',
workflow_id: 'update-docs.yml',
repo: 'clerk-docs',
workflow_id: 'typedoc.yml',
ref: 'main',
})
} else{
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@
"test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue",
"test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run",
"turbo:clean": "turbo daemon clean",
"typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json",
"typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs .typedoc/docs",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Don’t delete old docs before the new ones are verified

If TypeDoc fails, the rm -rf .typedoc/docs leaves you with no docs at all.
Guard that the temp folder exists first and replace atomically (mv -T or similar).

🤖 Prompt for AI Agents 
In package.json at line 55, the current script deletes the old docs folder
before verifying new docs, risking loss if TypeDoc fails. Modify the script to
first check if the temp docs folder exists after TypeDoc runs successfully, then
atomically replace the old docs folder with the new one using a command like 'mv
-T' to ensure the old docs are only removed if the new docs are ready.

"version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
"version-packages:canary": "./scripts/canary.mjs",
"version-packages:snapshot": "./scripts/snapshot.mjs",
Expand Down
2 changes: 1 addition & 1 deletion typedoc.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ const typedocPluginReplaceTextOptions = {

/** @type {import("typedoc").TypeDocOptions} */
const config = {
out: './.typedoc/docs',
out: './.typedoc/temp-docs',
entryPointStrategy: 'packages',
plugin: [
Comment on lines 80 to 83
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

❓ Verification inconclusive

Keep out path in sync with the build script

The path is now duplicated here and in package.json#typedoc:generate. A future edit could update one without the other and silently break the move step.

🏁 Script executed:

#!/usr/bin/env bash
# CI guard – fails if the two paths diverge
jq -r '.scripts["typedoc:generate"]' package.json | grep -q '.typedoc/temp-docs' || {
  echo "Mismatch between typedoc output path in package.json and typedoc.config.mjs"; exit 1;
}

Length of output: 80

Add CI guard to enforce TypeDoc output path consistency

The out path (./.typedoc/temp-docs) in typedoc.config.mjs currently matches the one in package.json#scripts["typedoc:generate"], but they’re duplicated and may drift apart over time. To prevent silent breakages, include the following check in your CI pipeline:

#!/usr/bin/env bash
# Fails if the TypeDoc output path in package.json and typedoc.config.mjs differ
jq -r '.scripts["typedoc:generate"]' package.json \
  | grep -q '\.typedoc\/temp-docs' \
  || {
      echo "Mismatch between typedoc output path in package.json and typedoc.config.mjs"
      exit 1
    }

• Add this as a script (e.g. scripts/check-typedoc-path.sh).
• Invoke it in your CI config (e.g. pretest or a dedicated lint step).

🤖 Prompt for AI Agents 
In typedoc.config.mjs around lines 80 to 83, the TypeDoc output path is
duplicated in package.json scripts and this file, risking inconsistencies. To
fix this, create a new shell script (e.g., scripts/check-typedoc-path.sh) that
uses jq to extract the typedoc:generate script from package.json and verifies
the output path matches './.typedoc/temp-docs'. Then, update the CI pipeline
configuration to run this script as a pretest or lint step to enforce path
consistency automatically.

'typedoc-plugin-replace-text',
Expand Down
Loading