Snippet imports silently fail with 'Could not parse import/exports with acorn' when snippet has // or inline {/* */} comments in function body

[brianjohnson0123]

Summary

Mintlify's snippet import resolver silently fails with Could not parse import/exports with acorn for any snippet whose export const Component = (props) => <jsx> body contains JS line comments (// ...) or inline JSX comments ({/* ... */}) inside the JSX-returning function body. The consuming page renders without the component (no error visible to readers — the JSX tag just doesn't render), and a warning is logged on the dev server stdout.

The same snippet parses successfully with standalone acorn@8.15.0 extended with acorn-jsx@5.3.2.

Reproduction

snippets/Broken.mdx

{/*
  Broken — minimal repro for the snippet-resolver acorn parse failure.
*/}

export const COLORS = {
  blue: "#7a9ab8",
  red:  "#c46060",
};

export const Broken = ({ label, color = "blue" }) => {
  const hex = COLORS[color] ?? COLORS.blue;
  // this line comment makes the resolver fail
  return (
    <span style={{ color: hex, fontWeight: 700 }}>{label}</span>
  );
};

pages/uses-broken.mdx

---
title: "Repro"
---

import { Broken } from "/snippets/Broken.mdx";

<Broken label="Hello" color="red" />

Expected

Page renders the <Broken> component.

Actual

Dev server logs:

warning - Error resolving import "Broken" in /uses-broken.mdx: Could not parse import/exports with acorn

Page renders without the <Broken> component. No visible error in the rendered output — readers see a missing component.

Variant — inline JSX comments trigger the same failure

Replace the // this line comment with {/* this is an inline JSX comment */} placed inside the JSX body (e.g. between the opening <span> and {label}). Same warning, same silently-missing-component result.

What works

Removing all // and {/* */} comments from inside the arrow-function body resolves the warning and the component renders. The leading file-doc {/* ... */} block at the top of the snippet (above export const COLORS) is fine — only comments inside the JSX-returning arrow function trigger the failure.

Environment

• @mintlify/cli@4.0.1092 (via mintlify@^4.2.488)
• @mintlify/common@1.0.837
• micromark-extension-mdxjs-esm@3.0.0
• estree-util-to-js@2.0.0
• acorn@8.15.0 + acorn-jsx@5.3.2
• Node 22, macOS

Investigation notes

The error comes from micromark-extension-mdxjs-esm/lib/syntax.js:

const error = new VFileMessage('Could not parse import/exports with acorn', { ... });

Wrapped by @mintlify/common/dist/mdx/snippets/resolveAllImports.js:

const message = `Error resolving import "${specifier.name}" in ${fileWithImports.filename}: ${err.message}`;

Trace:

1. resolveAllImports calls resolveImport(specifier, ast, importedSnippet.tree, exportMap).
2. resolveImport/index.js calls findExport(name, importedFileContent, renamedName) — this walks the snippet AST and isolates the matching ExportNamedDeclaration node.
3. findExport calls toJs(isolatedExport.data.estree, { handlers: jsx }).value to convert the isolated AST back to JS source.
4. Caller passes that JS source into getAST(exportContent) (which dispatches to coreRemark() since no filePath is provided — see @mintlify/common/dist/mdx/remark.js).
5. coreRemark() runs remark-mdx → micromark-extension-mdxjs-esm → acorn parse — and this is where it fails.

The toJs step strips JS line comments from the output cleanly (verified). I've not pinned down what specifically about the resulting JS string trips mdxjs-esm's acorn pass, but the correlation is exact: snippets with // or inline {/* */} inside the JSX-returning arrow function body fail; snippets without such comments succeed. The resulting MDX-pipeline acorn invocation evidently uses options that diverge from the standalone acorn+jsx invocation we used to verify the snippets are syntactically valid.

Impact

This is silent — pages render without the imported component and most readers won't notice the warning. We hit it on 6 snippets across ~20 doc pages. Removing all comments from snippet function bodies is a workaround, but it forces choosing between code clarity and renderable docs, and the failure mode is impossible to debug without reading Mintlify's resolver source.

A fix that would help: have getAST(jsString) route through the JSX-aware parser path (getJsxEsmTree) when called from the snippet resolver, since by definition the input is JS produced by toJs(..., { handlers: jsx }) and may contain JSX. Even simpler: surface the underlying acorn error message and column location in the warning, rather than the generic "Could not parse import/exports with acorn" — that alone would cut hours of trial-and-error debugging.