fix: exclude MDX files with JSX comments from prettier

[GiladShoham]

Prettier corrupts JSX comment markers (`/* */` → `/* */`) when it reformats these two MDX files, breaking their comment syntax and any build depending on it. Excludes both files from prettier so their existing, correct content is left untouched.

Split out of the Node 24 branch (#10555), where it was an unrelated change picked up along the way.

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Fix MDX JSX comment escaping and exclude affected docs from Prettier

🐞 Bug fix ⚙️ Configuration changes 📝 Documentation 🕐 Less than 10 minutes

AI Description

• Fix broken JSX comment markers inside MDX code blocks (restore valid /* */ intent).
• Exclude two MDX docs from Prettier to prevent re-escaping regressions.
• Keep documentation rendering stable by avoiding formatter-induced syntax changes.

Diagram

graph TD
  A[Docs author] --> B[MDX docs]
  B --> C[Prettier formatting]
  C --> D{JSX comment in code block?}
  D -->|Yes| E[Escaped markers break comment]
  D -->|No| F[Format OK]
  G[.prettierignore] --> C
  G --> H[Skip formatting for 2 MDX files]
  H --> I[JSX comments preserved]

  subgraph Legend
    direction LR
    _doc[Document] ~~~ _cfg[Config file] ~~~ _dec{Decision}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Use targeted Prettier disables (`prettier-ignore`) around the blocks

• ➕ Keeps the files formatted by Prettier elsewhere
• ➕ Limits the blast radius to only the problematic snippet(s)
• ➖ MDX/JSX comment parsing can still be fragile depending on plugin behavior
• ➖ Requires maintaining ignore directives inline in docs content

2. Adjust Prettier/MDX plugin configuration or upgrade to a fixed version

• ➕ Fixes root cause for all MDX files, not just these two
• ➕ Avoids accumulating file-specific ignores
• ➖ May not be feasible if the escaping is a known upstream limitation
• ➖ Upgrades/config changes can have broad formatting diffs across the repo

3. Rewrite the commented sections to avoid JSX comments (MDX/markdown alternatives)

• ➕ Avoids the formatter edge case entirely
• ➕ Keeps files eligible for formatting
• ➖ May reduce clarity if the content is intentionally shown as JSX comment syntax
• ➖ Could change how examples are presented to readers

Recommendation: Given the narrow scope and that this is a formatter-induced doc break, excluding the two known-problem MDX files is a pragmatic, low-risk fix. If this pattern appears in more places over time, prefer either a Prettier/MDX plugin fix (version/config) or localized prettier-ignore directives to avoid growing the ignore list.

Files changed (3) +7 / -4

Bug fix (2) +3 / -3

react.mdxFix escaped JSX comment markers in React aspect docs +2/-2

Fix escaped JSX comment markers in React aspect docs

• Replaces incorrectly escaped JSX comment delimiters in a code block so the intended comment syntax is preserved. This aligns the snippet with valid JSX comment notation and avoids rendering/confusion in the docs.

scopes/react/aspect-docs/react/react.mdx

loader-fallback.docs.mdxFix escaped JSX comment marker in loader fallback docs snippet +1/-1

Fix escaped JSX comment marker in loader fallback docs snippet

• Corrects an escaped JSX comment opener in the MDX content so the example/comment block remains syntactically correct. Pairs with the ignore rule to prevent future formatter re-escaping.

scopes/react/ui/loader-fallback/loader-fallback.docs.mdx

Other (1) +4 / -1

.prettierignoreIgnore two MDX docs that Prettier corrupts +4/-1

Ignore two MDX docs that Prettier corrupts

• Adds the two specific MDX documentation paths to '.prettierignore' with a clarifying comment. This prevents Prettier from re-introducing invalid escaping in JSX comment markers within their code blocks.

.prettierignore

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Invalid MDX comment ✓ Resolved 🐞 Bug ≡ Correctness

Description

The MDX docs files scopes/react/aspect-docs/react/react.mdx and
scopes/react/ui/loader-fallback/loader-fallback.docs.mdx changed JSX comment blocks from the valid
{/* ... */} form to an escaped {\/\* ... \*\/}/{\/\* form, which is not JSX comment syntax and
is parsed as a JavaScript expression (starting like a regex literal) that can’t span newlines. This
can break MDX compilation and therefore loading/building the docs, including ReactAspect docs
since scopes/react/aspect-docs/react/index.ts exports the problematic MDX module.

Code

scopes/react/aspect-docs/react/react.mdx[172]

+{/\* ## Composition Providers

Evidence

Both MDX files now contain the escaped comment opener {\/\* (and in react.mdx the escaped closer
\*\/}) across multi-line blocks, which is not the JSX comment delimiter {/* ... */}; in
loader-fallback.docs.mdx this is further evidenced by the mix of an escaped opener (`{\/\* Try it
out:), a standard JSX comment elsewhere ({/* ... */}), and a closer written as */}`. Since the
repo compiles MDX via @mdx-js/mdx using compileSync, these invalid MDX/JSX constructs can cause
compilation failures when docs are processed, and react.mdx is explicitly exported as an MDX
module via scopes/react/aspect-docs/react/index.ts, amplifying the impact.

scopes/react/aspect-docs/react/react.mdx[170-231]
scopes/react/aspect-docs/react/index.ts[1-1]
scopes/mdx/mdx/mdx.doc-reader.ts[1-15]
scopes/react/ui/loader-fallback/loader-fallback.docs.mdx[17-45]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Two MDX documentation files (`scopes/react/aspect-docs/react/react.mdx` and `scopes/react/ui/loader-fallback/loader-fallback.docs.mdx`) contain invalid “escaped” JSX comment delimiters such as `{\/\* ... \*\/}` / `{\/\*` instead of the valid JSX comment syntax `{/* ... */}`. Because MDX/JSX parses `{\/\*` as the start of a JavaScript expression (it begins like a regex literal) rather than a comment, multi-line blocks using this form can fail MDX compilation and break docs builds/loads.
## Issue Context
- The repository’s MDX pipeline compiles MDX using `@mdx-js/mdx` (`compileSync`), so syntax-invalid MDX/JSX will fail during docs processing.
- `scopes/react/aspect-docs/react/index.ts` exports `react.mdx` as an MDX module for docs, so a compilation error in that file can break `ReactAspect` docs.
- `loader-fallback.docs.mdx` currently mixes an escaped opener (`{\/\* Try it out:`) with a standard JSX comment (`{/* ... */}`) and closes the block with `*/}`, making the comment delimiters inconsistent/invalid.
## Fix Focus Areas
- scopes/react/aspect-docs/react/react.mdx[172-229]
- scopes/react/ui/loader-fallback/loader-fallback.docs.mdx[24-45]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[qodo-free-for-open-source-projects]

Code review by qodo was updated up to the latest commit 235f6d7