Example file API fails in monorepos

[wise-king-sullyman]

Problem Summary

The example file API endpoint (/api/v6/components/{component}/{tab}/examples/{example}) fails in monorepo setups with the error:

ENOENT: no such file or directory, open '../react-core/src/components/Alert/examples/Alert.mdx'

This occurs when trying to retrieve example source code for components in monorepo configurations after integrating doc-core into the organization structure.

Context: Related Fixes

This is related to but NOT a duplicate of issue #118:

• Issue Monorepos are not properly supported #118 (Fixed in PR fix(cli): support monorepos #136, v1.13.1): Fixed monorepo support at the CLI level by implementing package discovery that walks up the directory tree to find node_modules in monorepo structures

• Commit 9fd87fb (PR fix(API): address issues with text API in monorepos #185): Fixed monorepo issues in the text API endpoint by adding fallback tab handling

• Current Issue Example file API fails in monorepos #213: The examples API endpoint still uses naive path resolution and needs the same monorepo-aware treatment

Steps to Reproduce

1. Set up a monorepo with doc-core
2. Configure content entries pointing to packages with example files
3. Access an example endpoint: /api/v6/components/alert/react/examples/AlertDynamicLiveRegion
4. Observe ENOENT error when the code tries to resolve the example file path

Completion Criteria

The issue is resolved when:

5. Example files are successfully resolved in monorepos: The API endpoint can locate and return example source code when running in a monorepo configuration
6. Package-aware path resolution: Import paths are resolved using the content configuration's package base paths rather than naive filesystem relative paths
7. Backward compatibility maintained: Non-monorepo setups continue to work without regression
8. Consistent with existing fixes: The solution follows the same monorepo-handling patterns established in PR fix(cli): support monorepos #136 and PR fix(API): address issues with text API in monorepos #185
9. Error handling: Clear error messages when example files genuinely don't exist vs. path resolution failures

Technical Notes

• The issue is in src/pages/api/[version]/[section]/[page]/[tab]/examples/[example].ts:114

• Current implementation uses resolve(contentEntryFilePath, '../', cleanFilePath) which doesn't understand monorepo package structure

• The content.ts file already contains absolute base paths to packages (generated by the CLI's monorepo-aware package discovery)

• Import paths in MDX files use relative paths that work in bundler context but not in raw filesystem resolution

Related Links

• Related issue: Monorepos are not properly supported #118 (Monorepos are not properly supported) - CLOSED

• Jira: PF-3601

• Fix for CLI monorepo support: PR fix(cli): support monorepos #136 (commit 33f76fb)

• Fix for text API monorepo issues: PR fix(API): address issues with text API in monorepos #185 (commit 9fd87fb)

Impact

This blocks the use of the examples API in monorepo configurations, preventing retrieval of example source code for documentation.

---

Jira Issue: PF-3601

[coderabbitai]

🔗 Related PRs

#190 - feat(api): add example API endpoints [merged]
#197 - fix(config): address bug preventing custom scope usage [merged]
#221 - feat(API): [PF-3167] Add component-index.json API endpoint for MCP [merged]
#225 - fix(api): resolve issue causing the example API to fail in monorepos [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

🎉 This issue has been resolved in version 1.21.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀