fix(theme): vendor theme-common/internal usages ahead of Docusaurus v4 (#1140)#1502
Open
sserrata wants to merge 2 commits into
Open
fix(theme): vendor theme-common/internal usages ahead of Docusaurus v4 (#1140)#1502sserrata wants to merge 2 commits into
sserrata wants to merge 2 commits into
Conversation
#1140) Docusaurus v4 will remove the `@docusaurus/theme-common/internal` entry point and the back-compat shim added in facebook/docusaurus#11153. This package imported 13 symbols across 10 files from that path (CodeBlock utilities and Tabs primitives), each of which already started emitting ESModulesLinkingWarning in v3.8 user builds. Vendor the leaf utilities into `src/utils/` (codeBlockUtils, useCodeWordWrap, useMutationObserver, reactUtils, tabsUtils, scrollUtils) with MIT attribution to Meta, repoint the 10 source files at the local copies, and delete the `declare module "@docusaurus/theme-common/internal"` ambient shim so the compiler enforces no future regressions. Swizzle `@theme/Tabs` and `@theme/TabItem` so user-authored `<Tabs>`/`<TabItem>` in MDX share the same React context as our six OpenAPI tab variants (ApiTabs, MimeTabs, SchemaTabs, OperationTabs, DiscriminatorTabs, CodeTabs). Without the swizzles, our vendored TabsContext is a different object than Docusaurus's, so stock TabItem children would fail to find a provider at SSR. ScrollControllerProvider is auto-mounted inside our vendored TabsProvider so every tab consumer is self-sufficient. The peer-dep range on `@docusaurus/*` is unchanged; vendoring removes our coupling to the unstable entry point without affecting public API compatibility. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
Size Change: +262 B (+0.01%) Total Size: 2.32 MB 📦 View Changed
ℹ️ View Unchanged
|
|
Visit the preview URL for this PR (updated for commit ebdafdd): https://docusaurus-openapi-36b86--pr1502-jfzzdf47.web.app (expires Tue, 23 Jun 2026 13:13:27 GMT) 🔥 via Firebase Hosting GitHub Action 🌎 Sign: bf293780ee827f578864d92193b8c2866acd459f |
…alias Avoid `../../../utils/...` relative paths by relocating the vendored utilities into `src/theme/utils/` so they can be imported via the existing `@theme/*` alias (`@theme/utils/codeBlockUtils`, `@theme/utils/tabsUtils`, etc.). The `@theme/*` alias is dual-purpose: tsconfig path mapping for type-checking within this package, and a Docusaurus webpack runtime alias resolved by the consuming site. Existing codebase precedent: `@theme/translationIds`, `@theme/ApiItem/store`, `@theme/ApiItem/hooks` — non-component utility files already live under `src/theme/` and are consumed via `@theme/...` at both compile and runtime. No functional changes; pure file move + import rewrite. Cross-references inside the utils directory remain as sibling `./` paths. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Member
Author
|
Hi @slorber, interested to get your feedback on this approach. Do you foresee any issues with drift/maintenance of the vendored utils? |
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
Closes #1140. Migrates
docusaurus-theme-openapi-docsoff of@docusaurus/theme-common/internalahead of Docusaurus v4, which will remove that entry point. The back-compat shim (facebook/docusaurus#11153) is no longer load-bearing for this package.Approach
Vendored the leaf utilities into
src/theme/utils/(with MIT attribution to Meta — Docusaurus is MIT-licensed):codeBlockUtils.tsparseCodeBlockTitle,parseLanguage,parseLines,containsLineNumbers,getPrismCssVariablesuseCodeWordWrap.tsuseCodeWordWrapuseMutationObserver.tsuseCodeWordWrapreactUtils.tsuseEvent,useShallowMemoObject,ReactContextErrortabsUtils.tsxsanitizeTabsChildren,useTabsContextValue,useTabs,TabsProvider(+ inlineduseQueryStringValueto avoid pullinghistoryUtils)scrollUtils.tsxScrollControllerProvider,useScrollPositionBlockerFiles live under
src/theme/utils/so they're consumed via the existing@theme/*alias (e.g.@theme/utils/codeBlockUtils) at both compile time (tsconfig path mapping) and runtime (Docusaurus webpack). Follows existing precedent in this codebase:@theme/translationIds,@theme/ApiItem/store,@theme/ApiItem/hooks.Repointed 10 source files (4 CodeBlock + 6 Tabs variants) at the local copies.
Swizzled
@theme/Tabsand@theme/TabItem. Reason: our vendoredTabsContextis a different React context object than Docusaurus's, so user-authored<Tabs>/<TabItem>in MDX would fail to find a provider at SSR. The swizzles route stock markdown tabs through our context so the whole package stays internally consistent.Auto-mounted
ScrollControllerProviderinside our vendoredTabsProviderso every tab consumer (the six OpenAPI variants + swizzled@theme/Tabs) is self-sufficient — no root-level swizzle required.Removed the ambient
declare module "@docusaurus/theme-common/internal"block fromsrc/theme-classic.d.ts. The compiler now enforces no regressions.Verification
tsc --noEmitcleanyarn workspace docusaurus-theme-openapi-docs buildpassesyarn workspace demo run docusaurus buildpassesgrep "@docusaurus/theme-common/internal" src/returns zero hits in source; zerorequire()hits in compiledlib/outputTest plan
oneOf/anyOf— SchemaTabs render, switching firesonChange<Tabs>/<TabItem>still renders (swizzle regression check)Notes on long-term maintenance
Vendored utilities are leaf functions (regex/string parsers + a couple of small hooks + a context). Upstream changes have historically been rare and additive; worst-case drift = "we don't pick up a new magic-comment syntax," not a bug. When Docusaurus v4 lands with new public extension points (per @slorber's hint on #1140), we can revisit and potentially retire vendored copies in favor of the new public APIs.
🤖 Generated with Claude Code