
Security News
Deno 2.2 Improves Dependency Management and Expands Node.js Compatibility
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
next-mdx-remote
Advanced tools
utilities for loading mdx from any remote source as data, rather than as a local import
The next-mdx-remote package allows you to use MDX (Markdown with JSX) in a Next.js application. It enables server-side rendering of MDX content, making it possible to dynamically load and render MDX files at runtime.
Server-side rendering of MDX
This feature allows you to serialize MDX content on the server side and then render it on the client side using the MDXRemote component.
const { serialize } = require('next-mdx-remote/serialize');
const { MDXRemote } = require('next-mdx-remote');
export async function getStaticProps() {
const source = 'Some **MDX** content';
const mdxSource = await serialize(source);
return { props: { mdxSource } };
}
export default function Page({ mdxSource }) {
return <MDXRemote {...mdxSource} />;
}
Dynamic MDX content
This feature allows you to read MDX content from a file and render it dynamically in your Next.js application.
import { serialize } from 'next-mdx-remote/serialize';
import { MDXRemote } from 'next-mdx-remote';
import fs from 'fs';
import path from 'path';
export async function getStaticProps() {
const filePath = path.join(process.cwd(), 'content', 'example.mdx');
const source = fs.readFileSync(filePath, 'utf8');
const mdxSource = await serialize(source);
return { props: { mdxSource } };
}
export default function Page({ mdxSource }) {
return <MDXRemote {...mdxSource} />;
}
Custom components in MDX
This feature allows you to define custom React components that can be used within your MDX content.
import { serialize } from 'next-mdx-remote/serialize';
import { MDXRemote } from 'next-mdx-remote';
const components = {
h1: (props) => <h1 style={{ color: 'tomato' }} {...props} />,
};
export async function getStaticProps() {
const source = '# Hello, world!';
const mdxSource = await serialize(source);
return { props: { mdxSource } };
}
export default function Page({ mdxSource }) {
return <MDXRemote {...mdxSource} components={components} />;
}
The react-markdown package allows you to render Markdown content as React components. It does not support JSX within Markdown like MDX does, making it less flexible for embedding React components directly in Markdown content.
The gatsby-plugin-mdx package is used in Gatsby.js to enable MDX support. It provides similar functionality to next-mdx-remote but is tailored for use with Gatsby's static site generation rather than Next.js.
npm install next-mdx-remote
If using with Turbopack, you'll need to add the following to your next.config.js
until this issue is resolved:
const nextConfig = {
+ transpilePackages: ['next-mdx-remote'],
}
import { serialize } from 'next-mdx-remote/serialize'
import { MDXRemote } from 'next-mdx-remote'
import Test from '../components/test'
const components = { Test }
export default function TestPage({ source }) {
return (
<div className="wrapper">
<MDXRemote {...source} components={components} />
</div>
)
}
export async function getStaticProps() {
// MDX text - can be from a local file, database, anywhere
const source = 'Some **mdx** text, with a component <Test />'
const mdxSource = await serialize(source)
return { props: { source: mdxSource } }
}
While it may seem strange to see these two in the same file, this is one of the cool things about Next.js -- getStaticProps
and TestPage
, while appearing in the same file, run in two different places. Ultimately your browser bundle will not include getStaticProps
at all, or any of the functions it uses only on the server, so serialize
will be removed from the browser bundle entirely.
IMPORTANT: Be very careful about putting any
next-mdx-remote
code into a separate "utilities" file. Doing so will likely cause issues with Next.js' code splitting abilities - it must be able to cleanly determine what is used only on the server side and what should be left in the client bundle. If you putnext-mdx-remote
code into an external utilities file and something is broken, remove it and start from the simple example above before filing an issue.
Markdown in general is often paired with frontmatter, and normally this means adding some extra custom processing to the way markdown is handled. To address this, next-mdx-remote
comes with optional parsing of frontmatter, which can be enabled by passing parseFrontmatter: true
to serialize
.
Here's what that looks like:
import { serialize } from 'next-mdx-remote/serialize'
import { MDXRemote } from 'next-mdx-remote'
import Test from '../components/test'
const components = { Test }
export default function TestPage({ mdxSource }) {
return (
<div className="wrapper">
<h1>{mdxSource.frontmatter.title}</h1>
<MDXRemote {...mdxSource} components={components} />
</div>
)
}
export async function getStaticProps() {
// MDX text - can be from a local file, database, anywhere
const source = `---
title: Test
---
Some **mdx** text, with a component <Test name={frontmatter.title}/>
`
const mdxSource = await serialize(source, { parseFrontmatter: true })
return { props: { mdxSource } }
}
vfile-matter
is used to parse the frontmatter.
<MDXRemote />
accepts a scope
prop, which makes all of the values available for use in your MDX.
Each key/value pair in the scope
argument will be exposed as a javascript variable. So, for example, you could imagine if you had a scope like { foo: 'bar' }
, it would be interpreted as const foo = 'bar'
.
This specifically means that you need to make sure that key names in your scope
argument are valid javascript variable names. For example, passing in { 'my-variable-name': 'bar' }
would generate an error, because the key name is not a valid javascript variable name.
It's also important to note that scope
variables must be consumed as arguments to a component, they cannot be rendered in the middle of text. This is shown in the example below.
import { serialize } from 'next-mdx-remote/serialize'
import { MDXRemote } from 'next-mdx-remote'
import Test from '../components/test'
const components = { Test }
const data = { product: 'next' }
export default function TestPage({ source }) {
return (
<div className="wrapper">
<MDXRemote {...source} components={components} scope={data} />
</div>
)
}
export async function getStaticProps() {
// MDX text - can be from a local file, database, anywhere
const source =
'Some **mdx** text, with a component using a scope variable <Test product={product} />'
const mdxSource = await serialize(source)
return { props: { source: mdxSource } }
}
You can also pass custom data into serialize
, which will then pass the value through and make it available from its result. By spreading the result from source
into <MDXRemote />
, the data will be made available.
Note that any scope values passed into serialize
need to be serializable, meaning passing functions or components is not possible. Additionally, any key named in the scope
argument must be valid javascript variable names. If you need to pass custom scope that is not serializable, you can pass scope
directly to <MDXRemote />
where it's rendered. There is an example of how to do this above this section.
import { serialize } from 'next-mdx-remote/serialize'
import { MDXRemote } from 'next-mdx-remote'
import Test from '../components/test'
const components = { Test }
const data = { product: 'next' }
export default function TestPage({ source }) {
return (
<div className="wrapper">
<MDXRemote {...source} components={components} />
</div>
)
}
export async function getStaticProps() {
// MDX text - can be from a local file, database, anywhere
const source =
'Some **mdx** text, with a component <Test product={product} />'
const mdxSource = await serialize(source, { scope: data })
return { props: { source: mdxSource } }
}
MDXProvider
If you want to make components available to any <MDXRemote />
being rendered in your application, you can use <MDXProvider />
from @mdx-js/react
.
// pages/_app.jsx
import { MDXProvider } from '@mdx-js/react'
import Test from '../components/test'
const components = { Test }
export default function MyApp({ Component, pageProps }) {
return (
<MDXProvider components={components}>
<Component {...pageProps} />
</MDXProvider>
)
}
// pages/test.jsx
import { serialize } from 'next-mdx-remote/serialize'
import { MDXRemote } from 'next-mdx-remote'
export default function TestPage({ source }) {
return (
<div className="wrapper">
<MDXRemote {...source} />
</div>
)
}
export async function getStaticProps() {
// MDX text - can be from a local file, database, anywhere
const source = 'Some **mdx** text, with a component <Test />'
const mdxSource = await serialize(source)
return { props: { source: mdxSource } }
}
motion.div
)
Component names that contain a dot (.
), such as those from framer-motion
, can be rendered the same way as other custom components, just pass motion
in your components object.
import { motion } from 'framer-motion'
import { MDXProvider } from '@mdx-js/react'
import { serialize } from 'next-mdx-remote/serialize'
import { MDXRemote } from 'next-mdx-remote'
export default function TestPage({ source }) {
return (
<div className="wrapper">
<MDXRemote {...source} components={{ motion }} />
</div>
)
}
export async function getStaticProps() {
// MDX text - can be from a local file, database, anywhere
const source = `Some **mdx** text, with a component:
<motion.div animate={{ x: 100 }} />`
const mdxSource = await serialize(source)
return { props: { source: mdxSource } }
}
Lazy hydration defers hydration of the components on the client. This is an optimization technique to improve the initial load of your application, but may introduce unexpected delays in interactivity for any dynamic content within your MDX content.
Note: this will add an additional wrapping div
around your rendered MDX, which is necessary to avoid hydration mismatches during render.
import { serialize } from 'next-mdx-remote/serialize'
import { MDXRemote } from 'next-mdx-remote'
import Test from '../components/test'
const components = { Test }
export default function TestPage({ source }) {
return (
<div className="wrapper">
<MDXRemote {...source} components={components} lazy />
</div>
)
}
export async function getStaticProps() {
// MDX text - can be from a local file, database, anywhere
const source = 'Some **mdx** text, with a component <Test />'
const mdxSource = await serialize(source)
return { props: { source: mdxSource } }
}
This library exposes a function and a component, serialize
and <MDXRemote />
. These two are purposefully isolated into their own files -- serialize
is intended to be run server-side, so within getStaticProps
, which runs on the server/at build time. <MDXRemote />
on the other hand is intended to be run on the client side, in the browser.
serialize(source: string, { mdxOptions?: object, scope?: object, parseFrontmatter?: boolean })
serialize
consumes a string of MDX. It can also optionally be passed options which are passed directly to MDX, and a scope object that can be included in the MDX scope. The function returns an object that is intended to be passed into <MDXRemote />
directly.
serialize(
// Raw MDX contents as a string
'# hello, world',
// Optional parameters
{
// made available to the arguments of any custom MDX component
scope: {},
// MDX's available options, see the MDX docs for more info.
// https://mdxjs.com/packages/mdx/#compilefile-options
mdxOptions: {
remarkPlugins: [],
rehypePlugins: [],
format: 'mdx',
},
// Indicates whether or not to parse the frontmatter from the MDX source
parseFrontmatter: false,
}
)
Visit https://mdxjs.com/packages/mdx/#compilefile-options for available mdxOptions
.
<MDXRemote compiledSource={string} components?={object} scope?={object} lazy?={boolean} />
<MDXRemote />
consumes the output of serialize
as well as an optional components argument. Its result can be rendered directly into your component. To defer hydration of the content and immediately serve the static markup, pass the lazy
prop.
<MDXRemote {...source} components={components} />
Rendering will use MDXProvider
under the hood. This means you can replace HTML tags by custom components. Those components are listed in MDXJS Table of components.
An example use case is rendering the content with your preferred styling library.
import { Typography } from "@material-ui/core";
const components = { Test, h2: (props) => <Typography variant="h2" {...props} /> }
...
If you prefer, you can also wrap your entire application in an <MDXProvider />
instead of passing your components directly to <MDXRemote />
. See the example above.
Note: th/td
won't work because of the "/" in the component name.
There isn't really a good default way to load MDX files in a Next.js app. Previously, we wrote next-mdx-enhanced
in order to be able to render your MDX files into layouts and import their front matter to create index pages.
This workflow from next-mdx-enhanced
was fine, but introduced a few limitations that we have removed with next-mdx-remote
:
exportPathMap
, which creates confusion for authors. Regardless, moving pages around in any way breaks things -- either the page's url or your exportPathMap
configuration.So, next-mdx-remote
changes the entire pattern so that you load your MDX content not through an import, but rather through getStaticProps
or getServerProps
-- you know, the same way you would load any other data. The library provides the tools to serialize and hydrate the MDX content in a manner that is performant. This removes all of the limitations listed above, and does so at a significantly lower cost -- next-mdx-enhanced
is a very heavy library with a lot of custom logic and some annoying limitations. Our informal testing has shown build times reduced by 50% or more.
Since this project was initially created, Kent C. Dodds has made a similar project, mdx-bundler
. This library supports imports and exports within a MDX file (as long as you manually read each imported file and pass its contents) and automatically processes frontmatter. If you have a lot of files that all import and use different components, you may benefit from using mdx-bundler
, as next-mdx-remote
currently only allows components to be imported and made available across all pages. It's important to note that this functionality comes with a cost though - mdx-bundler
's output is at least 400% larger than the output from next-mdx-remote
for basic markdown content.
Data has shown that 99% of use cases for all developer tooling are building unnecessarily complex personal blogs. Just kidding. But seriously, if you are trying to build a blog for personal or small business use, consider just using normal HTML and CSS. You definitely do not need to be using a heavy full-stack JavaScript framework to make a simple blog. You'll thank yourself later when you return to make an update in a couple years and there haven't been 10 breaking releases to all of your dependencies.
If you really insist though, check out our official Next.js example implementation. 💖
The code generated by next-mdx-remote
, which is used to actually render the MDX targets browsers with module support. If you need to support older browsers, consider transpiling the compiledSource
output from serialize
.
import
/ export
import
and export
statements cannot be used inside an MDX file. If you need to use components in your MDX files, they should be provided as a prop to <MDXRemote />
.
Hopefully this makes sense, since in order to work, imports must be relative to a file path, and this library allows content to be loaded from anywhere, rather than only loading local content from a set file path. As for exports, the MDX content is treated as data, not a module, so there is no way for us to access any value which may be exported from the MDX passed to next-mdx-remote
.
This library evaluates a string of JavaScript on the client side, which is how it MDXRemotes the MDX content. Evaluating a string into javascript can be a dangerous practice if not done carefully, as it can enable XSS attacks. It's important to make sure that you are only passing the mdxSource
input generated by the serialize
function to <MDXRemote />
, as instructed in the documentation. Do not pass user input into <MDXRemote />
.
If you have a CSP on your website that disallows code evaluation via eval
or new Function()
, you will need to loosen that restriction in order to utilize next-mdx-remote
, which can be done using unsafe-eval
.
This project does include native types for TypeScript use. Both serialize
and <MDXRemote />
have types normally as you'd expect, and the library also exports a type which you can use to type the result of getStaticProps
.
MDXRemoteSerializeResult<TScope = Record<string, unknown>>
: Represents the return value of serialize
. The TScope
generic type can be passed to represent the type of the scoped data you pass in.Below is an example of a simple implementation in TypeScript. You may not need to implement the types exactly in this way for every configuration of TypeScript - this example is just a demonstration of where the types could be applied if needed.
import type { GetStaticProps } from 'next'
import { serialize } from 'next-mdx-remote/serialize'
import { MDXRemote, type MDXRemoteSerializeResult } from 'next-mdx-remote'
import ExampleComponent from './example'
const components = { ExampleComponent }
interface Props {
mdxSource: MDXRemoteSerializeResult
}
export default function ExamplePage({ mdxSource }: Props) {
return (
<div>
<MDXRemote {...mdxSource} components={components} />
</div>
)
}
export const getStaticProps: GetStaticProps<{
mdxSource: MDXRemoteSerializeResult
}> = async () => {
const mdxSource = await serialize('some *mdx* content: <ExampleComponent />')
return { props: { mdxSource } }
}
app
Directory SupportUsage of next-mdx-remote
within server components, and specifically within Next.js's app
directory, is supported by importing from next-mdx-remote/rsc
. Previously, the serialization and render steps were separate, but going forward RSC makes this separation unnecessary.
Some noteworthy differences:
<MDXRemote />
now accepts a source
prop, instead of accepting the serialized output from next-mdx-remote/serialize
MDXProvider
context from @mdx-js/react
, as RSC does not support React ContextparseFrontmatter: true
, use the compileMdx
method exposed from next-mdx-remote/rsc
lazy
prop is no longer supported, as the rendering happens on the server<MDXRemote />
must be rendered on the server, as it is now an async component. Client components can be rendered as part of the MDX markupFor more information on RSC, check out the Next.js documentation.
Assuming usage in a Next.js 13+ application using the app
directory.
import { MDXRemote } from 'next-mdx-remote/rsc'
// app/page.js
export default function Home() {
return (
<MDXRemote
source={`# Hello World
This is from Server Components!
`}
/>
)
}
import { MDXRemote } from 'next-mdx-remote/rsc'
// app/page.js
export default function Home() {
return (
// Ideally this loading spinner would ensure there is no layout shift,
// this is an example for how to provide such a loading spinner.
// In Next.js you can also use `loading.js` for this.
<Suspense fallback={<>Loading...</>}>
<MDXRemote
source={`# Hello World
This is from Server Components!
`}
/>
</Suspense>
)
}
// components/mdx-remote.js
import { MDXRemote } from 'next-mdx-remote/rsc'
const components = {
h1: (props) => (
<h1 {...props} className="large-text">
{props.children}
</h1>
),
}
export function CustomMDX(props) {
return (
<MDXRemote
{...props}
components={{ ...components, ...(props.components || {}) }}
/>
)
}
// app/page.js
import { CustomMDX } from '../components/mdx-remote'
export default function Home() {
return (
<CustomMDX
// h1 now renders with `large-text` className
source={`# Hello World
This is from Server Components!
`}
/>
)
}
// app/page.js
import { compileMDX } from 'next-mdx-remote/rsc'
export default async function Home() {
// Optionally provide a type for your frontmatter object
const { content, frontmatter } = await compileMDX<{ title: string }>({
source: `---
title: RSC Frontmatter Example
---
# Hello World
This is from Server Components!
`,
options: { parseFrontmatter: true },
})
return (
<>
<h1>{frontmatter.title}</h1>
{content}
</>
)
}
next-mdx-remote
is opinionated in what features it supports. If you need additional features not provided by next-mdx-remote
, here are a few alternatives to consider:
next-mdx-remote
If you're using React Server Components and just trying to use basic MDX with custom components, you don't need anything other than the core MDX library.
import { compile, run } from '@mdx-js/mdx'
import * as runtime from 'react/jsx-runtime'
import ClientComponent from './components/client'
// MDX can be retrieved from anywhere, such as a file or a database.
const mdxSource = `# Hello, world!
<ClientComponent />
`
export default async function Page() {
// Compile the MDX source code to a function body
const code = String(
await compile(mdxSource, { outputFormat: 'function-body' })
)
// You can then either run the code on the server, generating a server
// component, or you can pass the string to a client component for
// final rendering.
// Run the compiled code with the runtime and get the default export
const { default: MDXContent } = await run(code, {
...runtime,
baseUrl: import.meta.url,
})
// Render the MDX content, supplying the ClientComponent as a component
return <MDXContent components={{ ClientComponent }} />
}
You can also simplify this approach with evaluate
, which compiles and runs code in a single call if you don't plan on passing the compiled string to a database or client component.
import { evaluate } from '@mdx-js/mdx'
import * as runtime from 'react/jsx-runtime'
import ClientComponent from './components/client'
// MDX can be retrieved from anywhere, such as a file or a database.
const mdxSource = `
export const title = "MDX Export Demo";
# Hello, world!
<ClientComponent />
export function MDXDefinedComponent() {
return <p>MDX-defined component</p>;
}
`
export default async function Page() {
// Run the compiled code
const {
default: MDXContent,
MDXDefinedComponent,
...rest
} = await evaluate(mdxSource, runtime)
console.log(rest) // logs { title: 'MDX Export Demo' }
// Render the MDX content, supplying the ClientComponent as a component, and
// the exported MDXDefinedComponent.
return (
<>
<MDXContent components={{ ClientComponent }} />
<MDXDefinedComponent />
</>
)
}
FAQs
utilities for loading mdx from any remote source as data, rather than as a local import
The npm package next-mdx-remote receives a total of 137,662 weekly downloads. As such, next-mdx-remote popularity was classified as popular.
We found that next-mdx-remote demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.