{"id":13469675,"url":"https://github.com/hashicorp/next-mdx-remote","last_synced_at":"2025-05-13T22:02:22.779Z","repository":{"id":38444109,"uuid":"258049460","full_name":"hashicorp/next-mdx-remote","owner":"hashicorp","description":"Load MDX content from anywhere","archived":false,"fork":false,"pushed_at":"2024-06-19T23:53:43.000Z","size":2033,"stargazers_count":2918,"open_issues_count":60,"forks_count":146,"subscribers_count":27,"default_branch":"main","last_synced_at":"2025-04-28T14:13:00.023Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hashicorp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-23T00:07:26.000Z","updated_at":"2025-04-28T08:46:31.000Z","dependencies_parsed_at":"2023-02-12T05:00:42.394Z","dependency_job_id":"5a086c5c-9758-4b6e-b266-3ef56e371f64","html_url":"https://github.com/hashicorp/next-mdx-remote","commit_stats":{"total_commits":158,"total_committers":37,"mean_commits":4.27027027027027,"dds":0.5443037974683544,"last_synced_commit":"103dc251c975431bff6f0b2c0c5545756a5021c8"},"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fnext-mdx-remote","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fnext-mdx-remote/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fnext-mdx-remote/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hashicorp%2Fnext-mdx-remote/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hashicorp","download_url":"https://codeload.github.com/hashicorp/next-mdx-remote/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251326850,"owners_count":21571636,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T15:01:50.262Z","updated_at":"2025-04-28T14:13:07.409Z","avatar_url":"https://github.com/hashicorp.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Nextjs Plugins","others","📦 Legacy \u0026 Inactive Projects"],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable-file MD033 MD041 --\u003e\n\n\u003c!--\n\n# next-mdx-remote\n\nA set of light utilities allowing MDX to be loaded within `getStaticProps` or `getServerSideProps` and hydrated correctly on the client.\n\n--\u003e\n\n[![next-mdx-remote](./header.png)](.)\n\n---\n\n## Installation\n\n```sh\nnpm install next-mdx-remote\n```\n\nIf using with Turbopack, you'll need to add the following to your `next.config.js` until [this issue](https://github.com/vercel/next.js/issues/64525) is resolved:\n\n```diff\nconst nextConfig = {\n+  transpilePackages: ['next-mdx-remote'],\n}\n```\n\n## Examples\n\n```jsx\nimport { serialize } from 'next-mdx-remote/serialize'\nimport { MDXRemote } from 'next-mdx-remote'\n\nimport Test from '../components/test'\n\nconst components = { Test }\n\nexport default function TestPage({ source }) {\n  return (\n    \u003cdiv className=\"wrapper\"\u003e\n      \u003cMDXRemote {...source} components={components} /\u003e\n    \u003c/div\u003e\n  )\n}\n\nexport async function getStaticProps() {\n  // MDX text - can be from a local file, database, anywhere\n  const source = 'Some **mdx** text, with a component \u003cTest /\u003e'\n  const mdxSource = await serialize(source)\n  return { props: { source: mdxSource } }\n}\n```\n\nWhile 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.\n\n\u003e **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 put `next-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.\n\n### Additional Examples\n\n\u003cdetails\u003e\n  \u003csummary\u003eParsing Frontmatter\u003c/summary\u003e\n\nMarkdown 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`.\n\nHere's what that looks like:\n\n```jsx\nimport { serialize } from 'next-mdx-remote/serialize'\nimport { MDXRemote } from 'next-mdx-remote'\n\nimport Test from '../components/test'\n\nconst components = { Test }\n\nexport default function TestPage({ mdxSource }) {\n  return (\n    \u003cdiv className=\"wrapper\"\u003e\n      \u003ch1\u003e{mdxSource.frontmatter.title}\u003c/h1\u003e\n      \u003cMDXRemote {...mdxSource} components={components} /\u003e\n    \u003c/div\u003e\n  )\n}\n\nexport async function getStaticProps() {\n  // MDX text - can be from a local file, database, anywhere\n  const source = `---\ntitle: Test\n---\n\nSome **mdx** text, with a component \u003cTest name={frontmatter.title}/\u003e\n  `\n\n  const mdxSource = await serialize(source, { parseFrontmatter: true })\n  return { props: { mdxSource } }\n}\n```\n\n_[`vfile-matter`](https://github.com/vfile/vfile-matter) is used to parse the frontmatter._\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003ePassing custom data to a component with `scope`\u003c/summary\u003e\n\n`\u003cMDXRemote /\u003e` accepts a `scope` prop, which makes all of the values available for use in your MDX.\n\nEach 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'`.\n\nThis 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.\n\nIt'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.\n\n```jsx\nimport { serialize } from 'next-mdx-remote/serialize'\nimport { MDXRemote } from 'next-mdx-remote'\n\nimport Test from '../components/test'\n\nconst components = { Test }\nconst data = { product: 'next' }\n\nexport default function TestPage({ source }) {\n  return (\n    \u003cdiv className=\"wrapper\"\u003e\n      \u003cMDXRemote {...source} components={components} scope={data} /\u003e\n    \u003c/div\u003e\n  )\n}\n\nexport async function getStaticProps() {\n  // MDX text - can be from a local file, database, anywhere\n  const source =\n    'Some **mdx** text, with a component using a scope variable \u003cTest product={product} /\u003e'\n  const mdxSource = await serialize(source)\n  return { props: { source: mdxSource } }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003ePassing `scope` into the `serialize` function instead\u003c/summary\u003e\n\nYou 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 `\u003cMDXRemote /\u003e`, the data will be made available.\n\nNote 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 `\u003cMDXRemote /\u003e` where it's rendered. There is an example of how to do this above this section.\n\n```jsx\nimport { serialize } from 'next-mdx-remote/serialize'\nimport { MDXRemote } from 'next-mdx-remote'\n\nimport Test from '../components/test'\n\nconst components = { Test }\nconst data = { product: 'next' }\n\nexport default function TestPage({ source }) {\n  return (\n    \u003cdiv className=\"wrapper\"\u003e\n      \u003cMDXRemote {...source} components={components} /\u003e\n    \u003c/div\u003e\n  )\n}\n\nexport async function getStaticProps() {\n  // MDX text - can be from a local file, database, anywhere\n  const source =\n    'Some **mdx** text, with a component \u003cTest product={product} /\u003e'\n  const mdxSource = await serialize(source, { scope: data })\n  return { props: { source: mdxSource } }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    Custom components from \u003ccode\u003eMDXProvider\u003c/code\u003e\u003ca id=\"mdx-provider\"\u003e\u003c/a\u003e\n  \u003c/summary\u003e\n\nIf you want to make components available to any `\u003cMDXRemote /\u003e` being rendered in your application, you can use [`\u003cMDXProvider /\u003e`](https://mdxjs.com/docs/using-mdx/#mdx-provider) from `@mdx-js/react`.\n\n```jsx\n// pages/_app.jsx\nimport { MDXProvider } from '@mdx-js/react'\n\nimport Test from '../components/test'\n\nconst components = { Test }\n\nexport default function MyApp({ Component, pageProps }) {\n  return (\n    \u003cMDXProvider components={components}\u003e\n      \u003cComponent {...pageProps} /\u003e\n    \u003c/MDXProvider\u003e\n  )\n}\n```\n\n```jsx\n// pages/test.jsx\nimport { serialize } from 'next-mdx-remote/serialize'\nimport { MDXRemote } from 'next-mdx-remote'\n\nexport default function TestPage({ source }) {\n  return (\n    \u003cdiv className=\"wrapper\"\u003e\n      \u003cMDXRemote {...source} /\u003e\n    \u003c/div\u003e\n  )\n}\n\nexport async function getStaticProps() {\n  // MDX text - can be from a local file, database, anywhere\n  const source = 'Some **mdx** text, with a component \u003cTest /\u003e'\n  const mdxSource = await serialize(source)\n  return { props: { source: mdxSource } }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    Component names with dot (e.g. \u003ccode\u003emotion.div\u003c/code\u003e)\n  \u003c/summary\u003e\n\nComponent 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.\n\n```js\nimport { motion } from 'framer-motion'\n\nimport { MDXProvider } from '@mdx-js/react'\nimport { serialize } from 'next-mdx-remote/serialize'\nimport { MDXRemote } from 'next-mdx-remote'\n\nexport default function TestPage({ source }) {\n  return (\n    \u003cdiv className=\"wrapper\"\u003e\n      \u003cMDXRemote {...source} components={{ motion }} /\u003e\n    \u003c/div\u003e\n  )\n}\n\nexport async function getStaticProps() {\n  // MDX text - can be from a local file, database, anywhere\n  const source = `Some **mdx** text, with a component:\n\n\u003cmotion.div animate={{ x: 100 }} /\u003e`\n  const mdxSource = await serialize(source)\n  return { props: { source: mdxSource } }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eLazy hydration\u003c/summary\u003e\n\nLazy 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.\n\n_Note: this will add an additional wrapping `div` around your rendered MDX, which is necessary to avoid [hydration mismatches during render](https://reactjs.org/docs/react-dom.html#hydrate)._\n\n```jsx\nimport { serialize } from 'next-mdx-remote/serialize'\nimport { MDXRemote } from 'next-mdx-remote'\n\nimport Test from '../components/test'\n\nconst components = { Test }\n\nexport default function TestPage({ source }) {\n  return (\n    \u003cdiv className=\"wrapper\"\u003e\n      \u003cMDXRemote {...source} components={components} lazy /\u003e\n    \u003c/div\u003e\n  )\n}\n\nexport async function getStaticProps() {\n  // MDX text - can be from a local file, database, anywhere\n  const source = 'Some **mdx** text, with a component \u003cTest /\u003e'\n  const mdxSource = await serialize(source)\n  return { props: { source: mdxSource } }\n}\n```\n\n\u003c/details\u003e\n\n## APIs\n\nThis library exposes a function and a component, `serialize` and `\u003cMDXRemote /\u003e`. 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. `\u003cMDXRemote /\u003e` on the other hand is intended to be run on the client side, in the browser.\n\n- **`serialize(source: string, { mdxOptions?: object, scope?: object, parseFrontmatter?: boolean })`**\n\n  **`serialize`** consumes a string of MDX. It can also optionally be passed options which are [passed directly to MDX](https://mdxjs.com/docs/extending-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 `\u003cMDXRemote /\u003e` directly.\n\n  ```ts\n  serialize(\n    // Raw MDX contents as a string\n    '# hello, world',\n    // Optional parameters\n    {\n      // made available to the arguments of any custom MDX component\n      scope: {},\n      // MDX's available options, see the MDX docs for more info.\n      // https://mdxjs.com/packages/mdx/#compilefile-options\n      mdxOptions: {\n        remarkPlugins: [],\n        rehypePlugins: [],\n        format: 'mdx',\n      },\n      // Indicates whether or not to parse the frontmatter from the MDX source\n      parseFrontmatter: false,\n    }\n  )\n  ```\n\n  Visit \u003chttps://mdxjs.com/packages/mdx/#compilefile-options\u003e for available `mdxOptions`.\n\n- **`\u003cMDXRemote compiledSource={string} components?={object} scope?={object} lazy?={boolean} /\u003e`**\n\n  **`\u003cMDXRemote /\u003e`** 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.\n\n  ```ts\n  \u003cMDXRemote {...source} components={components} /\u003e\n  ```\n\n### Replacing default components\n\nRendering will use [`MDXProvider`](https://mdxjs.com/docs/using-mdx/#mdx-provider) under the hood. This means you can replace HTML tags by custom components. Those components are listed in MDXJS [Table of components](https://mdxjs.com/table-of-components/).\n\nAn example use case is rendering the content with your preferred styling library.\n\n```jsx\nimport { Typography } from \"@material-ui/core\";\n\nconst components = { Test, h2: (props) =\u003e \u003cTypography variant=\"h2\" {...props} /\u003e }\n...\n```\n\nIf you prefer, you can also wrap your entire application in an `\u003cMDXProvider /\u003e` instead of passing your components directly to `\u003cMDXRemote /\u003e`. See the [example](#mdx-provider) above.\n\nNote: `th/td` won't work because of the \"/\" in the component name.\n\n## Background \u0026 Theory\n\nThere isn't really a good default way to load MDX files in a Next.js app. Previously, we wrote [`next-mdx-enhanced`](https://github.com/hashicorp/next-mdx-enhanced) in order to be able to render your MDX files into layouts and import their front matter to create index pages.\n\nThis workflow from `next-mdx-enhanced` was fine, but introduced a few limitations that we have removed with `next-mdx-remote`:\n\n- **The file content must be local.** You cannot store MDX files in another repo, a database, etc. For a large enough operation, there will end up being a split between those authoring content and those working on presentation of the content. Overlapping these two concerns in the same repo makes a more difficult workflow for everyone.\n- **You are bound to filesystem-based routing.** Your pages are generated with urls according to their locations. Or maybe you remap them using `exportPathMap`, which creates confusion for authors. Regardless, moving pages around in any way breaks things -- either the page's url or your `exportPathMap` configuration.\n- **You will end up running into performance issues.** Webpack is a JavaScript bundler, forcing it to load hundreds/thousands of pages of text content will blow out your memory requirements. Webpack stores each page as a distinct object with a large amount of metadata. One of our implementations with a couple hundred pages hit more than 8GB of memory required to compile the site. Builds took more than 25 minutes.\n- **You will be limited in the ways you are able to structure relational data.** Organizing content into dynamic, related categories is difficult when your entire data structure is front matter parsed into javascript objects and held in memory.\n\nSo, `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](https://github.com/hashicorp/next-mdx-enhanced/issues/17). Our informal testing has shown build times reduced by 50% or more.\n\nSince this project was initially created, Kent C. Dodds has made a similar project, [`mdx-bundler`](https://github.com/kentcdodds/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.\n\n### How Can I Build A Blog With This?\n\nData 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.\n\nIf you really insist though, check out [our official Next.js example implementation](https://github.com/vercel/next.js/tree/canary/examples/with-mdx-remote). 💖\n\n## Caveats\n\n### Environment Targets\n\nThe 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`.\n\n### `import` / `export`\n\n`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 `\u003cMDXRemote /\u003e`.\n\nHopefully 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`.\n\n## Security\n\nThis 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 `\u003cMDXRemote /\u003e`, as instructed in the documentation. **Do not pass user input into `\u003cMDXRemote /\u003e`.**\n\nIf 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`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#common_sources).\n\n## TypeScript\n\nThis project does include native types for TypeScript use. Both `serialize` and `\u003cMDXRemote /\u003e` have types normally as you'd expect, and the library also exports a type which you can use to type the result of `getStaticProps`.\n\n- `MDXRemoteSerializeResult\u003cTScope = Record\u003cstring, unknown\u003e\u003e`: Represents the return value of `serialize`. The `TScope` generic type can be passed to represent the type of the scoped data you pass in.\n\nBelow 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.\n\n```tsx\nimport type { GetStaticProps } from 'next'\nimport { serialize } from 'next-mdx-remote/serialize'\nimport { MDXRemote, type MDXRemoteSerializeResult } from 'next-mdx-remote'\nimport ExampleComponent from './example'\n\nconst components = { ExampleComponent }\n\ninterface Props {\n  mdxSource: MDXRemoteSerializeResult\n}\n\nexport default function ExamplePage({ mdxSource }: Props) {\n  return (\n    \u003cdiv\u003e\n      \u003cMDXRemote {...mdxSource} components={components} /\u003e\n    \u003c/div\u003e\n  )\n}\n\nexport const getStaticProps: GetStaticProps\u003c{\n  mdxSource: MDXRemoteSerializeResult\n}\u003e = async () =\u003e {\n  const mdxSource = await serialize('some *mdx* content: \u003cExampleComponent /\u003e')\n  return { props: { mdxSource } }\n}\n```\n\n## React Server Components (RSC) \u0026 Next.js `app` Directory Support\n\nUsage 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.\n\nSome noteworthy differences:\n\n- `\u003cMDXRemote /\u003e` now accepts a `source` prop, instead of accepting the serialized output from `next-mdx-remote/serialize`\n- Custom components can no longer be provided by using the `MDXProvider` context from `@mdx-js/react`, as RSC does not support React Context\n- To access frontmatter outside of your MDX when passing `parseFrontmatter: true`, use the `compileMdx` method exposed from `next-mdx-remote/rsc`\n- The `lazy` prop is no longer supported, as the rendering happens on the server\n- `\u003cMDXRemote /\u003e` must be rendered on the server, as it is now an async component. Client components can be rendered as part of the MDX markup\n\nFor more information on RSC, check out the [Next.js documentation](https://nextjs.org/docs/app/building-your-application/rendering/server-components).\n\n### Examples\n\n_Assuming usage in a Next.js 13+ application using the `app` directory._\n\n#### Basic\n\n```tsx\nimport { MDXRemote } from 'next-mdx-remote/rsc'\n\n// app/page.js\nexport default function Home() {\n  return (\n    \u003cMDXRemote\n      source={`# Hello World\n\n      This is from Server Components!\n      `}\n    /\u003e\n  )\n}\n```\n\n#### Loading state\n\n```tsx\nimport { MDXRemote } from 'next-mdx-remote/rsc'\n\n// app/page.js\nexport default function Home() {\n  return (\n    // Ideally this loading spinner would ensure there is no layout shift,\n    // this is an example for how to provide such a loading spinner.\n    // In Next.js you can also use `loading.js` for this.\n    \u003cSuspense fallback={\u003c\u003eLoading...\u003c/\u003e}\u003e\n      \u003cMDXRemote\n        source={`# Hello World\n\n        This is from Server Components!\n        `}\n      /\u003e\n    \u003c/Suspense\u003e\n  )\n}\n```\n\n#### Custom Components\n\n```tsx\n// components/mdx-remote.js\nimport { MDXRemote } from 'next-mdx-remote/rsc'\n\nconst components = {\n  h1: (props) =\u003e (\n    \u003ch1 {...props} className=\"large-text\"\u003e\n      {props.children}\n    \u003c/h1\u003e\n  ),\n}\n\nexport function CustomMDX(props) {\n  return (\n    \u003cMDXRemote\n      {...props}\n      components={{ ...components, ...(props.components || {}) }}\n    /\u003e\n  )\n}\n```\n\n```tsx\n// app/page.js\nimport { CustomMDX } from '../components/mdx-remote'\n\nexport default function Home() {\n  return (\n    \u003cCustomMDX\n      // h1 now renders with `large-text` className\n      source={`# Hello World\n      This is from Server Components!\n    `}\n    /\u003e\n  )\n}\n```\n\n#### Access Frontmatter outside of MDX\n\n```tsx\n// app/page.js\nimport { compileMDX } from 'next-mdx-remote/rsc'\n\nexport default async function Home() {\n  // Optionally provide a type for your frontmatter object\n  const { content, frontmatter } = await compileMDX\u003c{ title: string }\u003e({\n    source: `---\ntitle: RSC Frontmatter Example\n---\n# Hello World\nThis is from Server Components!\n`,\n    options: { parseFrontmatter: true },\n  })\n  return (\n    \u003c\u003e\n      \u003ch1\u003e{frontmatter.title}\u003c/h1\u003e\n      {content}\n    \u003c/\u003e\n  )\n}\n```\n\n## Alternatives\n\n`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:\n\n- [`mdx-bundler`](https://github.com/kentcdodds/mdx-bundler)\n- [`next-mdx-remote-client`](https://github.com/ipikuka/next-mdx-remote-client)\n- [`remote-mdx`](https://github.com/devjiwonchoi/remote-mdx)\n\n### You Might Not Need `next-mdx-remote`\n\nIf 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.\n\n```js\nimport { compile, run } from '@mdx-js/mdx'\nimport * as runtime from 'react/jsx-runtime'\nimport ClientComponent from './components/client'\n\n// MDX can be retrieved from anywhere, such as a file or a database.\nconst mdxSource = `# Hello, world!\n\u003cClientComponent /\u003e\n`\n\nexport default async function Page() {\n  // Compile the MDX source code to a function body\n  const code = String(\n    await compile(mdxSource, { outputFormat: 'function-body' })\n  )\n  // You can then either run the code on the server, generating a server\n  // component, or you can pass the string to a client component for\n  // final rendering.\n\n  // Run the compiled code with the runtime and get the default export\n  const { default: MDXContent } = await run(code, {\n    ...runtime,\n    baseUrl: import.meta.url,\n  })\n\n  // Render the MDX content, supplying the ClientComponent as a component\n  return \u003cMDXContent components={{ ClientComponent }} /\u003e\n}\n```\n\nYou 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.\n\n```js\nimport { evaluate } from '@mdx-js/mdx'\nimport * as runtime from 'react/jsx-runtime'\nimport ClientComponent from './components/client'\n\n// MDX can be retrieved from anywhere, such as a file or a database.\nconst mdxSource = `\nexport const title = \"MDX Export Demo\";\n\n# Hello, world!\n\u003cClientComponent /\u003e\n\nexport function MDXDefinedComponent() {\n  return \u003cp\u003eMDX-defined component\u003c/p\u003e;\n}\n`\n\nexport default async function Page() {\n  // Run the compiled code\n  const {\n    default: MDXContent,\n    MDXDefinedComponent,\n    ...rest\n  } = await evaluate(mdxSource, runtime)\n\n  console.log(rest) // logs { title: 'MDX Export Demo' }\n\n  // Render the MDX content, supplying the ClientComponent as a component, and\n  // the exported MDXDefinedComponent.\n  return (\n    \u003c\u003e\n      \u003cMDXContent components={{ ClientComponent }} /\u003e\n      \u003cMDXDefinedComponent /\u003e\n    \u003c/\u003e\n  )\n}\n```\n\n## License\n\n[Mozilla Public License Version 2.0](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhashicorp%2Fnext-mdx-remote","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhashicorp%2Fnext-mdx-remote","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhashicorp%2Fnext-mdx-remote/lists"}