docs: Migrate to Fumadocs#62
Conversation
✅ Deploy Preview for react-native-cloud-storage ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
WalkthroughThe ChangesDocusaurus → Fumadocs + Next.js migration
Sequence Diagram(s)sequenceDiagram
participant Browser
participant NextDocsPage as Next.js /docs/[[...slug]]
participant source as source loader
participant getMDXComponents
participant withHeadingBadgePills
Browser->>NextDocsPage: GET /docs/some-page
NextDocsPage->>source: getPage(slug)
source-->>NextDocsPage: page (data.badges, data.tocBadges, data.body)
NextDocsPage->>getMDXComponents: { tocBadges }
getMDXComponents->>withHeadingBadgePills: wrap h3 with badgesByHeading
withHeadingBadgePills-->>getMDXComponents: augmented h3 component
getMDXComponents-->>NextDocsPage: MDXComponents map
NextDocsPage->>Browser: DocsPage with MDX body + badge pills under headings
sequenceDiagram
participant pnpm as pnpm docs:api
participant TypeDoc
participant typedoc-frontmatter.mts
participant ContentDocs as content/docs/api/*.md
pnpm->>TypeDoc: run with typedoc.config.mts
TypeDoc->>typedoc-frontmatter.mts: MarkdownPageEvent.BEGIN per page
typedoc-frontmatter.mts->>typedoc-frontmatter.mts: extract `@platform/`@provider tags → badges/tocBadges
typedoc-frontmatter.mts->>TypeDoc: remove tags from rendered comment
typedoc-frontmatter.mts->>TypeDoc: write title/description/badges/tocBadges → page.frontmatter
TypeDoc->>ContentDocs: write markdown with frontmatter
Estimated code review effort🎯 5 (Critical) | ⏱️ ~120 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🧹 Nitpick comments (1)
apps/docs/lib/source/api-reference-tree-plugin.ts (1)
16-20: ⚡ Quick winScope API-folder detection to the actual
api/subtree.
isApiReferenceFoldercurrently matches by child-folder names only, androot()applies it to every top-level folder (Line 93). That can accidentally reshape non-API sections if they contain similarly named folders. Gate the transform with an explicit API-root check (folder name/ref) before applying flatten/rename logic.Proposed tightening
function isApiReferenceFolder(folder: Folder): boolean { - return folder.children.some( + const folderName = normalizeApiSectionKey(getNodeName(folder.name)); + if (folderName !== 'api') return false; + + return folder.children.some( (child) => child.type === 'folder' && API_SECTION_KEYS.has(normalizeApiSectionKey(getNodeName(child.name))) ); }Also applies to: 92-95
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@apps/docs/lib/source/api-reference-tree-plugin.ts` around lines 16 - 20, The isApiReferenceFolder function currently only checks if child folders match API section names, which can cause false positives in non-API sections that happen to contain similarly named folders. Add an explicit check to verify the parent folder itself is actually the API root folder (by checking its name or reference) before applying the isApiReferenceFolder logic in the root function around line 93. This ensures the flatten and rename transformations only apply to the actual api/ subtree and not to unrelated sections that might contain folders with similar names.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/docs/app/`(home)/layout.tsx:
- Line 4: The Layout function in this file uses the undefined type
LayoutProps<'/'> which is causing a TypeScript error. Define the LayoutProps
type in a centralized layout types file or global types configuration, then
import this type into all layout files including the Layout function in
apps/docs/app/layout.tsx, apps/docs/app/(home)/layout.tsx, and
apps/docs/app/docs/layout.tsx. Apply the LayoutProps type consistently across
all these Layout function component signatures to resolve the undefined type
error across all layout files.
In `@apps/docs/app/docs/layout.tsx`:
- Line 5: The `LayoutProps` type used in the Layout function export is undefined
and needs to be properly imported or defined. Identify where the `LayoutProps`
type should come from (check other layout files or type definition files in the
project), then add the correct import statement to
apps/docs/app/docs/layout.tsx. Once fixed in this file, apply the same
import/type definition solution consistently across all other layout files that
use `LayoutProps` to resolve the cross-file TypeScript error.
In `@apps/docs/app/layout.tsx`:
- Line 26: The Layout component function parameter is using the undefined type
LayoutProps<'/'>. Determine the correct source for this type by checking if it
should be imported from Fumadocs, a custom types file, or elsewhere in the
project. If LayoutProps is not available or not the right type for a Next.js
root layout, replace it with React.PropsWithChildren or another appropriate
layout props interface. Add the necessary import statement at the top of the
file if importing LayoutProps from an external library or internal types file.
In `@apps/docs/components/ai/page-actions.tsx`:
- Around line 27-35: The fetch call for markdownUrl in the ClipboardItem does
not validate the response status before caching and copying content. Add a check
after the fetch response is received (before calling res.text()) to verify that
the response status indicates success (check res.ok or res.status). If the
response is not successful, throw an error instead of proceeding to parse and
cache the response body. This prevents error HTML or error responses from being
cached and copied to the clipboard when the fetch fails with status codes like
404 or 500.
In `@apps/docs/content/docs/index.mdx`:
- Around line 11-13: The API documentation links in lines 11-13 of this mdx file
depend on the postinstall script (typedoc --options typedoc.config.mts &&
fumadocs-mdx) completing successfully to generate the API docs. These links to
CloudStorageProvider, useCloudFile, useIsCloudAvailable, and CloudStorageScope
enumerations and functions will return 404s if the postinstall script fails. Fix
any blocking issues in the postinstall script execution so that TypeDoc can
generate the API documentation files and make these links resolvable. Once the
postinstall script runs successfully, the documentation build can proceed and
these API doc links will be validated.
In `@apps/docs/lib/badges.ts`:
- Around line 21-23: The badge value de-duplication logic in the conditional
block (checking typeof value === 'string' && value.length > 0) does not trim
whitespace from the value before checking and storing it. This allows malformed
entries like ' Android ' or whitespace-only strings to be stored as-is. Call
the .trim() method on the value before checking its length and adding it to the
seen set, so that the trimmed version is evaluated and stored instead of the
original whitespace-padded value.
In `@apps/docs/lib/layout.shared.tsx`:
- Around line 3-7: The gitConfig object in the export statement has branch set
to 'main', but the repository's actual default branch is 'master'. Update the
branch property in the gitConfig object to use 'master' instead of 'main' to
ensure that any branch-aware links generated from this configuration point to
the correct repository branch.
In `@apps/docs/package.json`:
- Line 11: The postinstall hook in package.json is currently configured to run
TypeDoc and Fumadocs generation, which is blocking package installation when
these tools fail. Remove the postinstall script entry and instead create
separate build or docs scripts (e.g., build, docs, or generate-docs) that
contain the typedoc and fumadocs-mdx commands. This allows npm install to
complete successfully without being blocked by documentation generation
failures.
In `@apps/docs/typedoc.config.mts`:
- Around line 9-17: The typedoc configuration file uses the .mts extension which
requires an external loader and will fail at runtime. Rename typedoc.config.mts
to typedoc.config.mjs, and rename the referenced plugin file
scripts/typedoc-frontmatter.mts to scripts/typedoc-frontmatter.mjs. Update the
plugin array entry that points to the typedoc-frontmatter file to use the new
.mjs extension instead of .mts. Finally, update the postinstall script and any
other references in package.json that point to typedoc.config.mts to use
typedoc.config.mjs instead.
---
Nitpick comments:
In `@apps/docs/lib/source/api-reference-tree-plugin.ts`:
- Around line 16-20: The isApiReferenceFolder function currently only checks if
child folders match API section names, which can cause false positives in
non-API sections that happen to contain similarly named folders. Add an explicit
check to verify the parent folder itself is actually the API root folder (by
checking its name or reference) before applying the isApiReferenceFolder logic
in the root function around line 93. This ensures the flatten and rename
transformations only apply to the actual api/ subtree and not to unrelated
sections that might contain folders with similar names.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 905f6d38-1999-45f6-a756-d8acb68c83fb
⛔ Files ignored due to path filters (7)
apps/docs/app/favicon.icois excluded by!**/*.icoapps/docs/public/ios_installation.jpgis excluded by!**/*.jpgapps/docs/public/logo.pngis excluded by!**/*.pngapps/docs/static/img/undraw_dx.svgis excluded by!**/*.svgapps/docs/static/img/undraw_easy_to_use.svgis excluded by!**/*.svgapps/docs/static/img/undraw_expo.svgis excluded by!**/*.svgpnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (72)
apps/docs/.gitignoreapps/docs/README.mdapps/docs/app/(home)/layout.tsxapps/docs/app/(home)/page.tsxapps/docs/app/api/search/route.tsapps/docs/app/docs/[[...slug]]/page.tsxapps/docs/app/docs/layout.tsxapps/docs/app/global.cssapps/docs/app/layout.tsxapps/docs/app/llms-full.txt/route.tsapps/docs/app/llms.mdx/docs/[[...slug]]/route.tsapps/docs/app/llms.txt/route.tsapps/docs/app/og/docs/[...slug]/route.tsxapps/docs/app/robots.tsapps/docs/app/sitemap.tsapps/docs/components/ai/page-actions.tsxapps/docs/components/badges/pills.tsxapps/docs/config/api-reference.tsapps/docs/config/badges.tsapps/docs/content/docs/example.mdxapps/docs/content/docs/guides/google-drive-files-same-name.mdxapps/docs/content/docs/guides/migrating-icloud-documents.mdxapps/docs/content/docs/guides/using-multiple-providers.mdxapps/docs/content/docs/index.mdxapps/docs/content/docs/installation/configure-google-drive.mdxapps/docs/content/docs/installation/expo.mdxapps/docs/content/docs/installation/react-native.mdxapps/docs/content/docs/meta.jsonapps/docs/docs/api/CloudStorage.mdapps/docs/docs/api/CloudStorageError.mdapps/docs/docs/api/_category_.jsonapps/docs/docs/api/enums/CloudStorageErrorCode.mdapps/docs/docs/api/enums/CloudStorageProvider.mdapps/docs/docs/api/enums/CloudStorageScope.mdapps/docs/docs/api/enums/_category_.jsonapps/docs/docs/api/hooks/_category_.jsonapps/docs/docs/api/hooks/useCloudFile.mdapps/docs/docs/api/hooks/useIsCloudAvailable.mdapps/docs/docs/api/interfaces/CloudStorageFileStat.mdapps/docs/docs/api/interfaces/_category_.jsonapps/docs/docs/guides/_category_.jsonapps/docs/docs/installation/_category_.jsonapps/docs/docs/intro.mdapps/docs/docusaurus.config.tsapps/docs/lib/badges.tsapps/docs/lib/cn.tsapps/docs/lib/layout.shared.tsxapps/docs/lib/mdx/headings.tsxapps/docs/lib/site.tsapps/docs/lib/source.tsapps/docs/lib/source/api-reference-tree-plugin.tsapps/docs/lib/source/badge-label-plugin.tsapps/docs/lib/source/page-tree.tsapps/docs/mdx-components.tsxapps/docs/netlify.tomlapps/docs/next.config.mjsapps/docs/package.jsonapps/docs/postcss.config.mjsapps/docs/scripts/typedoc-frontmatter.mtsapps/docs/sidebars.tsapps/docs/source.config.tsapps/docs/src/components/HomepageFeatures/index.tsxapps/docs/src/components/HomepageFeatures/styles.module.cssapps/docs/src/css/custom.cssapps/docs/src/pages/index.module.cssapps/docs/src/pages/index.tsxapps/docs/src/pages/markdown-page.mdapps/docs/static/.nojekyllapps/docs/tsconfig.jsonapps/docs/typedoc.config.mtspackages/react-native-cloud-storage/src/cloud-storage.tspackages/react-native-cloud-storage/src/types/main.ts
💤 Files with no reviewable changes (23)
- apps/docs/docs/intro.md
- apps/docs/docs/api/interfaces/category.json
- apps/docs/docs/api/hooks/useCloudFile.md
- apps/docs/src/pages/markdown-page.md
- apps/docs/docs/api/CloudStorageError.md
- apps/docs/docs/api/enums/category.json
- apps/docs/docs/api/enums/CloudStorageProvider.md
- apps/docs/src/components/HomepageFeatures/index.tsx
- apps/docs/docs/guides/category.json
- apps/docs/docs/api/hooks/category.json
- apps/docs/sidebars.ts
- apps/docs/docs/installation/category.json
- apps/docs/docs/api/CloudStorage.md
- apps/docs/src/css/custom.css
- apps/docs/docs/api/enums/CloudStorageScope.md
- apps/docs/docs/api/interfaces/CloudStorageFileStat.md
- apps/docs/docs/api/hooks/useIsCloudAvailable.md
- apps/docs/docs/api/enums/CloudStorageErrorCode.md
- apps/docs/src/components/HomepageFeatures/styles.module.css
- apps/docs/src/pages/index.tsx
- apps/docs/src/pages/index.module.css
- apps/docs/docusaurus.config.ts
- apps/docs/docs/api/category.json
| import { HomeLayout } from 'fumadocs-ui/layouts/home'; | ||
| import { baseOptions } from '@/lib/layout.shared'; | ||
|
|
||
| export default function Layout({ children }: LayoutProps<'/'>) { |
There was a problem hiding this comment.
LayoutProps<'/'>undefined — same cross-file TypeScript error as root layout.
This file also uses the undefined LayoutProps<'/'> type. Once the type is defined and imported globally (or in a layout types file), apply it consistently across all layout files: apps/docs/app/layout.tsx, apps/docs/app/(home)/layout.tsx, and apps/docs/app/docs/layout.tsx.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/docs/app/`(home)/layout.tsx at line 4, The Layout function in this file
uses the undefined type LayoutProps<'/'> which is causing a TypeScript error.
Define the LayoutProps type in a centralized layout types file or global types
configuration, then import this type into all layout files including the Layout
function in apps/docs/app/layout.tsx, apps/docs/app/(home)/layout.tsx, and
apps/docs/app/docs/layout.tsx. Apply the LayoutProps type consistently across
all these Layout function component signatures to resolve the undefined type
error across all layout files.
| import { DocsLayout } from 'fumadocs-ui/layouts/docs'; | ||
| import { baseOptions } from '@/lib/layout.shared'; | ||
|
|
||
| export default function Layout({ children }: LayoutProps<'/docs'>) { |
There was a problem hiding this comment.
LayoutProps<'/docs'>undefined — same cross-file TypeScript error.
This file repeats the undefined LayoutProps type used in other layouts. Fix the type definition/import once and apply consistently across all layout files.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/docs/app/docs/layout.tsx` at line 5, The `LayoutProps` type used in the
Layout function export is undefined and needs to be properly imported or
defined. Identify where the `LayoutProps` type should come from (check other
layout files or type definition files in the project), then add the correct
import statement to apps/docs/app/docs/layout.tsx. Once fixed in this file,
apply the same import/type definition solution consistently across all other
layout files that use `LayoutProps` to resolve the cross-file TypeScript error.
| description: siteDescription, | ||
| }; | ||
|
|
||
| export default function Layout({ children }: LayoutProps<'/'>) { |
There was a problem hiding this comment.
LayoutProps<'/'>undefined TypeScript error — layout component parameter type not imported or defined.
Line 26 declares the layout component parameter as LayoutProps<'/'>, but this type is not imported or defined anywhere in the file. This will cause a TypeScript compilation failure.
Next.js root layouts typically use React.PropsWithChildren or a custom layout props interface. Verify whether LayoutProps should be imported from a library (e.g., Fumadocs, a custom types file) or replaced with the correct type.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/docs/app/layout.tsx` at line 26, The Layout component function parameter
is using the undefined type LayoutProps<'/'>. Determine the correct source for
this type by checking if it should be imported from Fumadocs, a custom types
file, or elsewhere in the project. If LayoutProps is not available or not the
right type for a Next.js root layout, replace it with React.PropsWithChildren or
another appropriate layout props interface. Add the necessary import statement
at the top of the file if importing LayoutProps from an external library or
internal types file.
| await navigator.clipboard.write([ | ||
| new ClipboardItem({ | ||
| 'text/plain': fetch(markdownUrl).then(async (res) => { | ||
| const content = await res.text(); | ||
| cache.set(markdownUrl, content); | ||
|
|
||
| return content; | ||
| }), | ||
| }), |
There was a problem hiding this comment.
Handle non-success fetch responses before caching clipboard content.
Line 29 currently caches/copies any response body. If the request returns 404/500, users can copy error HTML and poison the cache for that page URL.
Proposed fix
- await navigator.clipboard.write([
- new ClipboardItem({
- 'text/plain': fetch(markdownUrl).then(async (res) => {
- const content = await res.text();
- cache.set(markdownUrl, content);
-
- return content;
- }),
- }),
- ]);
+ await navigator.clipboard.write([
+ new ClipboardItem({
+ 'text/plain': fetch(markdownUrl).then(async (res) => {
+ if (!res.ok) {
+ throw new Error(`Failed to fetch markdown: ${res.status}`);
+ }
+ const content = await res.text();
+ cache.set(markdownUrl, content);
+ return content;
+ }),
+ }),
+ ]);📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| await navigator.clipboard.write([ | |
| new ClipboardItem({ | |
| 'text/plain': fetch(markdownUrl).then(async (res) => { | |
| const content = await res.text(); | |
| cache.set(markdownUrl, content); | |
| return content; | |
| }), | |
| }), | |
| await navigator.clipboard.write([ | |
| new ClipboardItem({ | |
| 'text/plain': fetch(markdownUrl).then(async (res) => { | |
| if (!res.ok) { | |
| throw new Error(`Failed to fetch markdown: ${res.status}`); | |
| } | |
| const content = await res.text(); | |
| cache.set(markdownUrl, content); | |
| return content; | |
| }), | |
| }), | |
| ]); |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/docs/components/ai/page-actions.tsx` around lines 27 - 35, The fetch
call for markdownUrl in the ClipboardItem does not validate the response status
before caching and copying content. Add a check after the fetch response is
received (before calling res.text()) to verify that the response status
indicates success (check res.ok or res.status). If the response is not
successful, throw an error instead of proceeding to parse and cache the response
body. This prevents error HTML or error responses from being cached and copied
to the clipboard when the fetch fails with status codes like 404 or 500.
| - **Two providers, one API** — [iCloud](/docs/api/enumerations/CloudStorageProvider) (via a native CloudKit module) and [Google Drive](/docs/installation/configure-google-drive) (via the REST API). Use the platform default or [switch between them at runtime](/docs/guides/using-multiple-providers). | ||
| - **React hooks** — [`useCloudFile`](/docs/api/functions/useCloudFile) and [`useIsCloudAvailable`](/docs/api/functions/useIsCloudAvailable) keep your components in sync with cloud state. | ||
| - **Scopes** — read and write in a hidden, app-private container ([`AppData`](/docs/api/enumerations/CloudStorageScope)) or the user-visible iCloud Drive / Google Drive [`Documents`](/docs/api/enumerations/CloudStorageScope) folder. |
There was a problem hiding this comment.
API doc links depend on TypeDoc generation from postinstall.
Lines 11–13 link to generated API docs:
/docs/api/enumerations/CloudStorageProvider/docs/api/functions/useCloudFile/docs/api/functions/useIsCloudAvailable/docs/api/enumerations/CloudStorageScope
These links will return 404s if the postinstall script (typedoc --options typedoc.config.mts && fumadocs-mdx) fails. Currently, the build is blocked by postinstall failures; unblock that to validate the API links.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/docs/content/docs/index.mdx` around lines 11 - 13, The API documentation
links in lines 11-13 of this mdx file depend on the postinstall script (typedoc
--options typedoc.config.mts && fumadocs-mdx) completing successfully to
generate the API docs. These links to CloudStorageProvider, useCloudFile,
useIsCloudAvailable, and CloudStorageScope enumerations and functions will
return 404s if the postinstall script fails. Fix any blocking issues in the
postinstall script execution so that TypeDoc can generate the API documentation
files and make these links resolvable. Once the postinstall script runs
successfully, the documentation build can proceed and these API doc links will
be validated.
| if (typeof value === 'string' && value.length > 0) { | ||
| seen.add(value); | ||
| } |
There was a problem hiding this comment.
Trim badge values before de-duplication.
Line 21 accepts strings like ' Android ' or whitespace-only entries as-is, which can leak malformed labels into rendering. Trim before checking length and storing.
Suggested change
for (const value of values) {
- if (typeof value === 'string' && value.length > 0) {
- seen.add(value);
+ if (typeof value === 'string') {
+ const normalized = value.trim();
+ if (normalized.length > 0) {
+ seen.add(normalized);
+ }
}
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| if (typeof value === 'string' && value.length > 0) { | |
| seen.add(value); | |
| } | |
| for (const value of values) { | |
| if (typeof value === 'string') { | |
| const normalized = value.trim(); | |
| if (normalized.length > 0) { | |
| seen.add(normalized); | |
| } | |
| } | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/docs/lib/badges.ts` around lines 21 - 23, The badge value de-duplication
logic in the conditional block (checking typeof value === 'string' &&
value.length > 0) does not trim whitespace from the value before checking and
storing it. This allows malformed entries like ' Android ' or whitespace-only
strings to be stored as-is. Call the .trim() method on the value before checking
its length and adding it to the seen set, so that the trimmed version is
evaluated and stored instead of the original whitespace-padded value.
| export const gitConfig = { | ||
| user: 'kuatsu', | ||
| repo: 'react-native-cloud-storage', | ||
| branch: 'main', | ||
| }; |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify repo default branch and compare with apps/docs/lib/layout.shared.tsx gitConfig.branch.
gh api repos/kuatsu/react-native-cloud-storage --jq '.default_branch'
rg -n "branch:\\s*'[^']+'" apps/docs/lib/layout.shared.tsxRepository: kuatsu/react-native-cloud-storage
Length of output: 104
Update gitConfig.branch from 'main' to 'main' to match the repository's default branch.
The repository's default branch is master, but line 6 sets branch: 'main'. This mismatch will cause branch-aware links generated from this config to point to non-existent refs.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/docs/lib/layout.shared.tsx` around lines 3 - 7, The gitConfig object in
the export statement has branch set to 'main', but the repository's actual
default branch is 'master'. Update the branch property in the gitConfig object
to use 'master' instead of 'main' to ensure that any branch-aware links
generated from this configuration point to the correct repository branch.
| "start": "next start", | ||
| "docs:api": "typedoc --options typedoc.config.mts", | ||
| "typecheck": "pnpm run docs:api && fumadocs-mdx && next typegen && tsc --noEmit", | ||
| "postinstall": "typedoc --options typedoc.config.mts && fumadocs-mdx", |
There was a problem hiding this comment.
Decouple docs generation from postinstall to unblock CI installs.
Line 11 currently makes package installation fail if TypeDoc/Fumadocs generation fails, and your pipeline logs show this is already happening. Move generation to explicit build/docs scripts (or make postinstall non-blocking) so dependency install remains reliable.
Suggested change
- "postinstall": "typedoc --options typedoc.config.mts && fumadocs-mdx",
+ "postinstall": "echo 'Skipping docs generation in postinstall'",
+ "docs:generate": "typedoc --options typedoc.config.mts && fumadocs-mdx",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "postinstall": "typedoc --options typedoc.config.mts && fumadocs-mdx", | |
| "postinstall": "echo 'Skipping docs generation in postinstall'", | |
| "docs:generate": "typedoc --options typedoc.config.mts && fumadocs-mdx", |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/docs/package.json` at line 11, The postinstall hook in package.json is
currently configured to run TypeDoc and Fumadocs generation, which is blocking
package installation when these tools fail. Remove the postinstall script entry
and instead create separate build or docs scripts (e.g., build, docs, or
generate-docs) that contain the typedoc and fumadocs-mdx commands. This allows
npm install to complete successfully without being blocked by documentation
generation failures.
Source: Pipeline failures
| const config = { | ||
| entryPoints: [path.join(packageRoot, 'src', 'index.ts')], | ||
| tsconfig: path.join(packageRoot, 'tsconfig.json'), | ||
| out: path.join(docsRoot, 'content', 'docs', 'api'), | ||
| plugin: [ | ||
| 'typedoc-plugin-markdown', | ||
| 'typedoc-plugin-frontmatter', | ||
| fileURLToPath(new URL('scripts/typedoc-frontmatter.mts', import.meta.url)), | ||
| ], |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== TypeDoc option usage =="
rg -n "typedoc --options" apps/docs/package.json
echo "== TypeDoc config files present =="
fd -a --full-path 'typedoc\.config\.(mts|mjs|js|cjs)$' apps/docs
echo "== Runtime-loaded plugin file extension references =="
rg -n "typedoc-frontmatter\.(mts|mjs|ts|js)" apps/docs/typedoc.config.*Repository: kuatsu/react-native-cloud-storage
Length of output: 460
🏁 Script executed:
# Check if the typedoc-frontmatter.mts file exists
fd -a 'typedoc-frontmatter' apps/docs/
# Check TypeDoc version and related deps
cat apps/docs/package.json | grep -A 5 '"typedoc"'
# Look for any CI configuration that might show actual failures
fd -a '.github|\.gitlab|\.circleci|\.travis|Jenkinsfile' --max-depth 3Repository: kuatsu/react-native-cloud-storage
Length of output: 281
🌐 Web query:
TypeDoc .mts module loading runtime support TypeScript executable
💡 Result:
TypeDoc supports.mts files as input for documentation generation [1][2][3]. Regarding runtime support for configuration files (e.g., typedoc.mts) and execution: 1. Input Handling: TypeDoc processes.mts files as TypeScript modules [4]. Recent updates have explicitly added support for.mts and.cts extensions for features like @includeCode [1][2][3]. 2. Configuration File Loading: TypeDoc does not natively execute.mts files as configuration files [5]. If you want to use a TypeScript-based configuration file (typedoc.mts), you must use a runtime loader to transpile or strip types before TypeDoc reads the config [5]. A common, recommended approach is to use the tsx package via the NODE_OPTIONS environment variable to enable this: NODE_OPTIONS="--import tsx" npx typedoc --options typedoc.mts [5] 3. Runtime Execution: If you are attempting to execute TypeScript code directly at runtime, Node.js now provides built-in support for type stripping (starting in newer versions) or you can use established third-party packages like tsx or ts-node [6][7][8]. For.mts files, which are treated as ES Modules by Node.js, ensure you are using a loader that supports the ESM resolution algorithm [6][7][9]. In summary, while TypeDoc natively understands.mts as a source file for documentation, it requires an external loader (like tsx) to process.mts configuration files at runtime [5].
Citations:
- 1: https://typedoc.org/documents/Changelog.html
- 2: Add mts and cts file extension aliases TypeStrong/typedoc#2936
- 3: @includeCode does not allow regions in typescript files with .mts file extension TypeStrong/typedoc#2935
- 4: https://www.typescriptlang.org/docs/handbook/modules/reference.html
- 5: Add support for
typedoc.ts,typedoc.ctsandtypedoc.mtsconfig files TypeStrong/typedoc#2913 - 6: https://nodejs.org/docs/latest/api/typescript.html
- 7: https://nodejs.org/api/typescript.html
- 8: https://github.com/TypeStrong/ts-node/blob/main/README.md
- 9: https://stackoverflow.com/questions/75819049/use-ts-node-to-run-mts
🏁 Script executed:
# Check if there's any CI configuration or environment setup
find . -type f \( -name "*.yml" -o -name "*.yaml" -o -name "*.json" \) -path "*/.github/*" -o -path "*/.gitlab*" -o -path "*/CI/*" 2>/dev/null | head -20
# Check package.json scripts more carefully for any NODE_OPTIONS or loader setup
cat apps/docs/package.json | grep -A 2 -B 2 "docs:api\|postinstall"
# Check if tsx or similar is available as a dependency
cat apps/docs/package.json | grep -i "tsx\|ts-node\|loader"Repository: kuatsu/react-native-cloud-storage
Length of output: 806
🏁 Script executed:
# Check if any CI workflow runs the docs commands
grep -r "pnpm run\|npm run\|yarn run\|pnpm install\|npm install" .github/workflows/ 2>/dev/null | grep -E "build|dev|docs|postinstall|typecheck"
# Look for postinstall context in CI
grep -r "postinstall\|node_modules" .github/workflows/ 2>/dev/null
# Check root package.json for workspace setup and if postinstall is defined there
grep -A 10 "postinstall\|scripts" package.json 2>/dev/null | head -30Repository: kuatsu/react-native-cloud-storage
Length of output: 873
TypeDoc .mts configuration files cannot load at runtime without external loaders.
typedoc --options typedoc.config.mts fails because TypeDoc 0.28.19 requires an external loader (e.g., tsx) to execute .mts configuration files, and no such loader is configured in the project. The same issue applies to the plugin entry at scripts/typedoc-frontmatter.mts. Both the config file and the runtime-loaded plugin must use .mjs, .cjs, or .js extensions instead.
The postinstall hook "typedoc --options typedoc.config.mts && fumadocs-mdx" will fail whenever dependencies are installed.
Suggested changes
Rename apps/docs/typedoc.config.mts to apps/docs/typedoc.config.mjs and apps/docs/scripts/typedoc-frontmatter.mts to apps/docs/scripts/typedoc-frontmatter.mjs, then update references in apps/docs/package.json scripts.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/docs/typedoc.config.mts` around lines 9 - 17, The typedoc configuration
file uses the .mts extension which requires an external loader and will fail at
runtime. Rename typedoc.config.mts to typedoc.config.mjs, and rename the
referenced plugin file scripts/typedoc-frontmatter.mts to
scripts/typedoc-frontmatter.mjs. Update the plugin array entry that points to
the typedoc-frontmatter file to use the new .mjs extension instead of .mts.
Finally, update the postinstall script and any other references in package.json
that point to typedoc.config.mts to use typedoc.config.mjs instead.
Source: Pipeline failures
1 participant
Summary by CodeRabbit
New Features
Documentation
Chores