fix(ui): resolve "CodeBlock is not defined" crash on docs pages#7614
Merged
Conversation
content/docs/maintainer-workflow.mdx used <CodeBlock> inside a top-level `export const steps = [...]` block instead of the markdown body. fumadocs-mdx only resolves capitalized JSX tags against the components prop inside the compiled body function; a top-level export const runs eagerly at module-evaluation time, before any components prop exists, so the unimported name threw a raw ReferenceError instead of fumadocs' friendly missing-reference message. Because docs-source.ts (used by every docs.*.tsx route's server loader) globs all content/docs/*.mdx files with eager: true, that one file's module-evaluation crash took down every docs route's SSR loader, not just its own page -- matching the "affects most/all docs pages" scope from the original report. Fixed by importing CodeBlock directly into the .mdx file, the same way it already imports MAINTAINER_COMMAND_LIST/PUBLIC_COMMAND_LIST -- MDX treats an explicit import as a normal JS binding rather than routing it through the components prop. Added a regression test that scans every content/docs/*.mdx file's top-level export const blocks for JSX tags that are only supplied via the MDX components prop and not also directly imported, guarding the whole bug class rather than just this file. Closes #7578
Contributor
|
Superagent didn't find any vulnerabilities or security issues in this PR. |
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
loopover-ui | 301466f | Commit Preview URL Branch Preview URL |
Jul 21 2026, 01:48 AM |
Bundle ReportChanges will decrease total bundle size by 37.47kB (-0.49%) ⬇️. This is within the configured threshold ✅ Detailed changes
Affected Assets, Files, and Routes:view changes for bundle: loopover-uiAssets Changed:
|
loopover-orb
Bot
added
the
gittensor:bug
|
Tip ✅ LoopOver review result - approve/merge recommendedReview updated: 2026-07-21 01:53:34 UTC
Review summary Nits — 3 non-blocking
Decision drivers
Context & advisory signals — never blocks the verdict
Linked issue satisfactionAddressed Review context
Contributor next steps
Signal definitions
🧪 Chat with LoopOverAsk LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.
Full command reference: https://loopover.ai/docs/loopover-commands 🧪 Experimental — new and may change. Visual preview
Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy. Scroll preview
A short scroll-through clip (desktop) — click either thumbnail to open the full animation. Evidence for scroll-linked behavior a single screenshot can't show. 🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed 💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →. Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.
|
![loopover-orb[bot]](https://avatars.githubusercontent.com/in/4139483?s=60&v=4){kind=small}
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
content/docs/maintainer-workflow.mdxpulls its<WorkflowMirror>stepsprop out into a top-levelexport const steps = [...]ESM block that embeds<CodeBlock>JSX. fumadocs-mdx only resolves capitalized JSX tags against thecomponentsprop (with a friendly "missing reference" guard) inside the markdown body, compiled into_createMdxContent. A top-levelexport construns eagerly at module-evaluation time, before anycomponentsprop exists, so an unimported provided-component name there is a bare, unresolved identifier — a rawReferenceError: CodeBlock is not defined, not fumadocs' friendly message.docs-source.ts(used by everydocs.*.tsxroute's server loader) imports fumadocs-mdx's generatedcollections/servermodule, which globs allcontent/docs/*.mdxfiles witheager: true. One file throwing during module evaluation takes down every docs route's SSR loader, not just/docs/maintainer-workflow.CodeBlockdirectly into the.mdxfile (import { CodeBlock } from "@/components/site/primitives";), the same way it already importsMAINTAINER_COMMAND_LIST/PUBLIC_COMMAND_LIST. MDX treats an explicitly-imported identifier as a normal JS binding rather than routing it through thecomponentsprop, so it resolves correctly regardless of eager vs. lazy evaluation.apps/loopover-ui/src/routes/docs-mdx-eager-scope.test.ts) that scans everycontent/docs/*.mdxfile's top-levelexport constblocks for JSX tags that are only supplied via the MDX components prop (cross-checked against the realdocsMdxComponentsmap) and not also directly imported — guarding the whole bug class, not just this one file.Closes #7578
Root cause detail (for reviewers)
The original issue's read-only investigation correctly ruled out dep-cache staleness, HMR, missing imports, and circular imports, and confirmed the compiled MDX output looked structurally correct — because it was. The actual failure never went through the rendering path it inspected. Instrumenting
docs-client-loader.tsx'scomponent()callback showed it was never called before the crash. Capturing the real (unformatted) error stack — the React-proxied console log truncates it — showed the true origin:...thrown while
docs-source.ts's eager glob (apps/loopover-ui/.source/server.ts,import.meta.glob([...], { eager: true })) evaluatedmaintainer-workflow.mdx's compiled module — triggered by literally any docs route's server loader (including/docs/quickstart, the page from the original report).Scope
type(scope): short summaryConventional Commit format.CONTRIBUTING.mdand does not reintroduce GitHub Pages, VitePress,site/, orCNAME.Closes #7578).Validation
git diff --checknpm run actionlintnpm run typechecknpm run test:coveragelocally — this change touches onlyapps/loopover-ui/**, which Codecov'scodecov/patchdoes not measure (onlysrc/**counts); the new regression test lives inapps/loopover-ui/src/routes/and is exercised byui:test.npm run test:workersnpm run build:mcpnpm run test:mcp-packnpm run ui:openapi:checknpm run ui:lintnpm run ui:typechecknpm run ui:buildnpm audit --audit-level=moderate— pre-existing findings (adm-zipviagithub-actionlint,body-parser) already tracked in fix(deps): clear adm-zip and body-parser npm audit findings #7607; unrelated to this diff (nopackage.json/lockfile changes here).docs-mdx-eager-scope.test.ts; verified it fails on the pre-fix content (reverted the import locally, confirmed the test catches it) and passes on the fix.npm run test:ci(full local gate)Additional manual verification (this bug is an SSR-loader-time crash, so it needed real requests, not just unit tests):
docs.*.tsxroutes returned HTTP 500 before the fix and HTTP 200 after, invite dev(curl + browser).wrangler dev --config dist/server/wrangler.json(this repo's nitro build targets thecloudflare-modulepreset;vite previewdoes not understand that output layout and 500s on an unrelated pre-existingdist/server/server.jsmodule-resolution mismatch — not something this PR touches).vite devand the wrangler-served production build) that/docs/quickstart(the original repro) and/docs/maintainer-workflow(the actual broken file) render fully, including the previously-crashing<CodeBlock>elements insidemaintainer-workflow.mdx'sstepsarray.If any required check was skipped, explain why:
Safety
UI Evidencesection below with screenshots — skipped: this is an availability fix (every docs page 500ing vs. loading), which reproducible HTTP-status checks across all 47 routes evidence more rigorously than static before/after screenshots would. See the manual verification list above for exactly what was checked, in which environments.Notes
docs-source.ts(server-only collection) means any futurecontent/docs/*.mdxfile that references a provided-only component (Callout,CodeBlock,FeatureRow,AmsObservabilityCallout,CommandTable,WorkflowMirror) inside a top-levelexport const— instead of within the markdown body — would reproduce this exact class of bug and take down every docs page again. The newdocs-mdx-eager-scope.test.tstest guards against that going forward.