How hashicorp/next-mdx-remote works
Project Type and Purpose
• Type: Open-source utility library (npm package) for Next.js.
• Purpose:
– Provide a serialize API to compile raw MDX into a serializable payload during Next.js data-fetching phase (getStaticProps / getServerSideProps).
– Provide an <MDXRemote /> React component to hydrate/ render that payload in the browser.
– Support RSC via next-mdx-remote/rsc with compileMdx and an async <MDXRemote />.
File Structure
• Entry points:
– index.js + serialize.js (CJS for Browser/Server)
– rsc.js (RSC entrypoint)
• Core source (in src/):
– serialize.ts – implements serialize() (server).
– rsc.tsx – implements RSC APIs (compileMdx, RSC <MDXRemote/>).
– index.tsx – re-exports main APIs.
– plugins/ – transforms (e.g., remove imports/exports).
– format-mdx-error.ts, idle-callback-polyfill.js, jsx-runtime.cjs – internal helpers.
• Tests live under __tests__/… to validate both classic and RSC flows.
• Config files define CI, TypeScript, linting, publishing.
Extract Architectural Insights from the README
• Two-phase separation:
– Server-side: serialize(source, options) → compiles MDX (using MDX core, remark/rehype plugins, optional frontmatter).
– Client-side: <MDXRemote {...serialized} components={…} lazy?> → hydrates and renders.
• RSC support:
– compileMdx({ source, options }) → returns { content, frontmatter }.
– RSC <MDXRemote source components?> → server-component rendering.
• Emphasized code-splitting safety in Next.js.
Main Components and Data Flows
A. Next.js Server (Build or Request Phase)
1. getStaticProps / getServerSideProps
2. Calls serialize(source, { mdxOptions, scope, parseFrontmatter })
3. Internally invokes MDX compiler + remark/rehype plugins + vfile-matter frontmatter parser
4. Outputs MDXRemoteSerializeResult (JSON-serializable)
5. Next.js sends this payload in page props to the client
B. Browser / Client Runtime
1. React application mounting
2. <MDXRemote {...serialized} components={…} />
3. Under the hood:
– Uses new Function(compiledSource) from jsx-runtime.cjs to reconstruct React elements
– Hydrates those elements in the DOM
4. Optional lazy hydration (lazy prop uses an idle-callback polyfill to defer hydration)
C. React Server Components Flow (Next.js 13+ App Directory)
1. Server Component calls compileMdx({ source, options }) from next-mdx-remote/rsc
2. Receives { content, frontmatter }
3. RSC <MDXRemote source content frontmatter components?>
4. Streams rendered React Server Component output to the client
D. Plugin Subsystem
– src/plugins/remove-imports-exports.ts hooks into MDX compilation pipeline to strip unsupported MDX imports/exports.
– Additional remark/rehype plugins can be passed via mdxOptions.
Architectural Patterns & Principles
• “Separation of Concerns”: server compile vs. client render vs. RSC render.
• Plugin pipeline: MDX compiler is extensible.
• Tree-shaking/code-splitting: Next.js removes server-only code from client bundle if entrypoint usage is localized.
• Dual entrypoints (CJS/ESM) for compatibility with Next.js bundlers (webpack, Turbopack).
Technologies / Frameworks
– Next.js (data-fetching API, RSC)
– MDX core (@mdx-js/mdx)
– remark & rehype plugin ecosystem
– React & React Server Components
– TypeScript (for types and safety)
– Babel/Webpack/Turbopack (affected via next.config.js)