fix: resolve TypeScript error and static export compatibility

[Kamilbenkirane]

Changes

• Fix TypeScript error in MDX components by separating components and options parameters
• Remove llms.mdx API route (incompatible with static export)
• Add postbuild script to generate static .mdx files for LLM consumption
• Update getLLMText to fallback to raw text if processed unavailable

Problem

The build was failing with a TypeScript error and the llms.mdx API route was incompatible with Next.js static export (output: export).

Solution

• Refactored getMDXComponents to accept components and options as separate parameters
• Removed the API route and replaced it with a postbuild script that generates static .mdx files
• These static files are now available at /docs/*.mdx paths for LLM consumption

Testing

• Build completes successfully
• Static MDX files are generated in out/docs/
• TypeScript compilation passes

[claude]

Pull Request Review

Summary

This PR successfully resolves TypeScript errors and static export compatibility issues by refactoring the MDX components API and replacing the dynamic API route with a postbuild script that generates static MDX files. The approach is sound and aligns well with Next.js static export constraints.

---

✅ Strengths

1. Clear Problem-Solution Alignment: The changes directly address the stated issues:

   • TypeScript error fixed by properly separating components and options parameters
   • Static export compatibility achieved by replacing API route with postbuild generation

2. Good Error Handling: The fallback mechanism in getLLMText (src/lib/source.ts:72-78) is a solid defensive programming practice:

   try {
     text = await page.data.getText("processed");
   } catch {
     text = await page.data.getText("raw");
   }

3. Proper TypeScript Refactoring: The getMDXComponents signature change (src/mdx-components.tsx:6-9) correctly separates concerns:

   • components for MDX component overrides
   • options for metadata/configuration

   This is cleaner and more maintainable than mixing them in a single object.

4. Documentation: Good inline comments explaining the reasoning (e.g., next.config.ts:13-14).

---

🔍 Code Quality Observations

1. Obsolete Rewrite Configuration (next.config.ts:15-22)

   • The rewrites() function is now dead code since it doesn't work with output: "export"
   • Recommendation: Remove this function entirely to avoid confusion. The comment explains why it doesn't work, but keeping non-functional code in the config is misleading.

   - // Note: rewrites don't work with static export
   - // Static .mdx files are generated via postbuild script instead
   - async rewrites() {
   -   return [
   -     {
   -       source: "/docs/:path*.mdx",
   -       destination: "/llms.mdx/docs/:path*",
   -     },
   -   ];
   - },

2. Silent Error Handling (src/lib/source.ts:76)

   • The empty catch block silently swallows errors, which could hide real issues (e.g., permission errors, file corruption)
   • Recommendation: Log the error or at least add a comment explaining why it's safe to ignore:

   try {
     text = await page.data.getText("processed");
   } catch (error) {
     // Fallback to raw text if processed version is not available
     text = await page.data.getText("raw");
   }

3. No Error Handling in Build Script (scripts/generate-static-mdx.ts:19-30)

   • The for loop doesn't handle individual page failures
   • If one page fails, the entire script exits (due to top-level catch)
   • Recommendation: Add error handling per page to make the build more resilient:

   for (const page of pages) {
     try {
       const markdown = await getLLMText(page);
       // ... rest of the code
       console.log(`  ✓ ${page.url}.mdx`);
     } catch (error) {
       console.error(`  ✗ ${page.url}.mdx - ${error.message}`);
       // Continue processing other pages or fail based on severity
     }
   }

---

⚠️ Potential Issues

1. Sequential File Generation Performance (scripts/generate-static-mdx.ts:19)

   • The script processes pages sequentially with await in a for loop
   • For large documentation sites, this could be slow
   • Recommendation: Consider using Promise.all() or Promise.allSettled() for parallel processing:

   const results = await Promise.allSettled(
     pages.map(async (page) => {
       const markdown = await getLLMText(page);
       const filePath = join(outDir, `${page.url}.mdx`);
       const fileDir = dirname(filePath);
       await mkdir(fileDir, { recursive: true });
       await writeFile(filePath, markdown, "utf-8");
       return page.url;
     })
   );
   
   results.forEach((result, i) => {
     if (result.status === 'fulfilled') {
       console.log(`  ✓ ${result.value}.mdx`);
     } else {
       console.error(`  ✗ ${pages[i].url}.mdx - ${result.reason}`);
     }
   });

2. Breaking Change Consideration (src/mdx-components.tsx)

   • The function signature change is a breaking change if getMDXComponents is used elsewhere
   • Recommendation: Verify that all call sites have been updated. Based on the diff, only src/app/[[...slug]]/page.tsx was updated, which appears to be the only usage.

---

🧪 Test Coverage

Observation: No test files were added or modified in this PR.

Recommendations:

• Add tests for getLLMText to verify the fallback behavior works correctly
• Add tests for the build script or at least manual verification steps in the PR description
• Consider adding integration tests to verify that static MDX files are accessible after build

---

🔒 Security Considerations

No security concerns identified. The changes:

• Don't introduce user input handling
• Use safe file system operations with validated paths
• Don't expose sensitive information

---

📊 Performance Considerations

1. Build Time: The postbuild script adds time to the build process, but this is acceptable for static generation
2. Sequential Processing: As mentioned above, consider parallelizing for better performance
3. Runtime: No negative runtime performance impact since files are pre-generated

---

🎯 Recommendations Summary

Must Fix:

• None (the code is functional as-is)

Should Fix:

1. Remove the dead rewrites() configuration (next.config.ts:15-22)
2. Add basic error logging in the getLLMText fallback catch block

Nice to Have:

1. Parallelize page processing in the build script for better performance
2. Add error handling per page in the build script
3. Add basic test coverage for the new functionality

---

✅ Approval

The core changes are solid and achieve the stated goals. The suggestions above are for further improvement but don't block merging. The refactoring improves type safety and correctly handles the static export constraints.

Overall Assessment: ✅ Approved with minor suggestions for improvement.