next-mdx-remote v6 blockJS Default Broke MDX Components

What Happened

Upgraded next-mdx-remote from v5 to v6 as part of a routine dependency update pass. The build compiled without errors. TypeScript passed. Vercel deployed the build successfully.

Then I opened a lesson page and saw that every <StepList> and <Checklist> component was rendering its wrapper shell but had no items inside. <LessonObjectives> showed the "What you'll build" header with an empty list below it. <ValidationPipeline> rendered the container div but nothing in it.

The symptom was visually obvious but the cause was completely non-obvious — because the build gave no indication anything was wrong.

The v6 Change

next-mdx-remote v6 added a blockJS option. In v6, it defaults to true.

When blockJS: true is active, the removeJavaScriptExpressions remark plugin runs during MDX serialization. This plugin strips all JavaScript expression nodes from the MDX AST before rendering, including:

• Array literals: items={['step one', 'step two', 'step three']}
• Object literals: config={{ theme: 'dark', compact: true }}
• Any JS expression: count={items.length}, active={index === selected}

The rationale in the v6 release notes: safety for platforms that process user-submitted MDX. If untrusted users can write MDX, you don't want arbitrary JavaScript executing. That's a legitimate security boundary for those use cases — a CMS or forum where users can write MDX content.

For a static site where the MDX is written by the developer and committed to a private repository, this restriction does nothing useful and silently breaks any component with structured props.

Debugging Path

The silent failure made this more expensive to diagnose than a build error would have been. The components rendered — they just rendered empty. No exception, no console warning, no TypeScript error. The serialized MDX output was syntactically valid; it just had the prop values removed.

Step 1 — Inspect the component. Traced through StepList.tsx. The items prop was undefined inside the component. Not an empty array — undefined. The component was being called but receiving nothing.

Step 2 — Inspect the serialized MDX. Added temporary logging to the compileMDX call in content-renderer.tsx to print the serialized output. The JSX component tags were present in the output but the prop values were gone. <StepList items={undefined}> instead of <StepList items={['a','b','c']}>.

Step 3 — Check the changelog. Found blockJS in the next-mdx-remote v6 release notes:

blockJS — Defaults to true for security. Set to false if your MDX content is trusted author-controlled content.

One option change, one default flip, no migration guide callout. 41 minutes of diagnostic work on what turned out to be a single-line fix.

const { content } = await compileMDX({
  source,
  components: allComponents,
  options: {
    parseFrontmatter: true,
    // next-mdx-remote v6 defaults blockJS: true, which runs
    // removeJavaScriptExpressions and strips all array/object
    // literal props from JSX. Our MDX is author-controlled
    // static content — opt out of this restriction explicitly.
    blockJS: false,
  },
})

Execution Evidence

Build Record

The following reconstructs the relevant Vercel build sequence. The initial deployment post-upgrade completed successfully — the failure only surfaces at render time, not compile time.

Deployment Recovery

The before/after shows the Vercel dashboard state: the build failure investigation on the left, all deployments restored to production-ready status on the right.

All Deployments ReadyBuild Failure

Screenshot Evidence

Full resolution screenshots from the incident. Click any image to expand. Use arrow keys to navigate.

01 — Vercel build output during next-mdx-remote v6 incident investigation

02 — Vercel dashboard: all production deployments restored to Ready after fix

03 — Live platform homepage: full operational recovery confirmed in production

Why Silent Failures Are Worse

A build error would have caught this at deploy time. Instead the failure path was:

1. Build compiled without errors
2. TypeScript type check passed
3. Deployment completed to production
4. All pages returned HTTP 200
5. Component content was simply missing

This class of failure — a default behavioral change that produces syntactically valid but semantically empty output — requires visual inspection to catch. Standard automated checks miss it entirely:

• Build status check — passes (build succeeded)
• HTTP smoke test — passes (pages return 200)
• TypeScript — passes (components accept undefined if not typed strictly)
• Lighthouse — passes (HTML structure present, no errors)

Only a human looking at a rendered page would notice that <StepList> has no steps. Or a test that asserts on rendered content rather than HTTP status. Visual regression testing would catch it; most CI pipelines don't run it.

Recovery Timeline

Lessons Learned

Prevention Pattern

After any MDX-related package upgrade:

1. Render a full test pass — open a page with every custom component type before considering the deploy complete
2. Verify array and object props — specifically check any component that uses items={[...]} or config objects
3. Read the full changelog — not just the headline version number; look for new options that default to restrictive behavior
4. Explicitly document opt-outs — when you set a security option to false, write the reason at the call site so future developers understand it was intentional

For next-mdx-remote specifically: if your MDX is author-controlled and committed to a private repository, always set blockJS: false explicitly. The behavior should be documented, not inherited from a default that can change across versions.