In this guide, we\u2019ll walk through a step-by-step process of setting up MDX in Next.js, configuring your project to support Cloudinary images, and adding components so that images in your MDX files are optimized on the fly.<\/p>\n\n\n\n
Prerequisites<\/h2>\n\n\n\n
Before following along, you should have:<\/p>\n\n\n\n
- \n
- Basic knowledge of Next.js (and the new App Router).<\/li>\n\n\n\n
- A Next.js boilerplate project already set up, using the App Router (app\/ directory).<\/li>\n\n\n\n
- A free Cloudinary account<\/a>.<\/li>\n\n\n\n
- Familiarity with MDX<\/a> or Markdown<\/a>, including how MDX can incorporate React components.<\/li>\n\n\n\n
- A working knowledge of JavaScript\/TypeScript, Node.js, and installing `npm` packages.<\/li>\n<\/ol>\n\n\n\n
You\u2019ll also need:<\/p>\n\n\n\n
- \n
- Node.js<\/a> (16 or higher is recommended).<\/li>\n\n\n\n
- An IDE or text editor (VS Code, WebStorm, etc.).<\/li>\n\n\n\n
- Some existing images or placeholders to test with.<\/li>\n<\/ul>\n\n\n\n
If you don\u2019t have these set up yet, take a moment to install Node, initialize a Next.js<\/a> project, and create a Cloudinary account<\/a>. Then, you\u2019ll be ready to continue. Please see their respective linked documentation for reference. <\/p>\n\n\n\n
Key Project Setup<\/h2>\n\n\n\n
Throughout this post, we\u2019ll assume you have a Next.js project with the following structure:<\/p>\n\n\n
``<\/span>`\nmy-next-project\/\n\n\u00a0\u00a0\u251c\u2500 app\/\n\n\u00a0\u00a0\u2502 \u00a0 \u251c\u2500 layout.js\n\n\u00a0\u00a0\u2502 \u00a0 \u251c\u2500 page.js\n\n\u00a0\u00a0\u2502 \u00a0 \u2514\u2500 ...\n\n\u00a0\u00a0\u251c\u2500 components\/\n\n\u00a0\u00a0\u2502 \u00a0 \u251c\u2500 mdx-components.js\n\n\u00a0\u00a0\u2502 \u00a0 \u251c\u2500 ...\n\n\u00a0\u00a0\u251c\u2500 lib\/\n\n\u00a0\u00a0\u251c\u2500 public\/\n\n\u00a0\u00a0\u251c\u2500 next.config.mjs\n\n\u00a0\u00a0\u251c\u2500 package.json\n\n\u00a0\u00a0\u2514\u2500 ...\n\n`<\/span>``<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nWithin the app\/ folder, you have layout components and route files that Next.js uses to render pages. We\u2019ll add some new routes and MDX files to power a docs or blog section, along with Cloudinary-based images.<\/p>\n\n\n\n
Installing Dependencies<\/h2>\n\n\n\n
We\u2019ll need to install packages to handle MDX in Next.js, plus a few helpful transformations and highlight tools (if you want them). In your terminal project root, run:<\/p>\n\n\n
`npm install @next\/mdx rehype-mdx-import-media rehype-pretty-code rehype-slug next-secure-headers shikiji-transformers json5`<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nHere\u2019s what each package is used for:<\/p>\n\n\n\n
- \n
- @next\/mdx<\/strong><\/a>. Official MDX support for Next.js, letting you import and create
.mdx<\/code> files as pages.<\/li>\n\n\n\n- rehype-mdx-import-media<\/strong><\/a>. Allows MDX to handle media imports, like images or other files, within the MDX content.<\/li>\n\n\n\n
- rehype-pretty-code<\/strong><\/a>. A plugin to format and highlight code blocks in your MDX content (useful for developer documentation).<\/li>\n\n\n\n
- rehype-slug<\/strong><\/a>. Automatically adds IDs to headings in your MDX, so you can create anchor links to specific sections.<\/li>\n\n\n\n
- next-secure-headers<\/strong><\/a>. A utility to help secure your Next.js app by automatically adding best-practice HTTP headers.<\/li>\n\n\n\n
- shikiji-transformers<\/strong><\/a>. Additional transformations for code syntax highlighting.<\/li>\n\n\n\n
- json5<\/strong><\/a>. For parsing or handling JSON with some extended syntax features (like comments).<\/li>\n<\/ol>\n\n\n\n
If you do not plan to highlight code in your docs, you can remove the highlighting-related packages, but for many developer sites, they are quite handy.<\/p>\n\n\n\n
Configuring Next.js for MDX<\/h2>\n\n\n\n
Next.js supports an extended configuration file, which is called next.config.mjs in Next. Let\u2019s look at a sample of how you might configure MDX. You\u2019ll also set up your Next.js images object to allow Cloudinary images:<\/p>\n\n\n
```\n\n\/\/ next.config.mjs<\/span>\n\nimport { env } from 'node:process'<\/span>;\n\nimport createMDX from '@next\/mdx'<\/span>;\n\nimport { transformerNotationDiff } from '@shikijs\/transformers'<\/span>;\n\nimport { createSecureHeaders } from 'next-secure-headers'<\/span>;\n\nimport rehypeMdxImportMedia from 'rehype-mdx-import-media'<\/span>;\n\nimport { rehypePrettyCode } from 'rehype-pretty-code'<\/span>;\n\nimport rehypeSlug from 'rehype-slug'<\/span>;\n\n\/**\n\n\u00a0* @type<\/span> {import('next').NextConfig}\n\n\u00a0*\/<\/span>\n\nconst<\/span> nextConfig = {\n\n\u00a0\u00a0reactStrictMode: true<\/span>,\n\n\u00a0\u00a0pageExtensions: ['js'<\/span>, 'jsx'<\/span>, 'mdx'<\/span>, 'ts'<\/span>, 'tsx'<\/span>],\n\n\u00a0\u00a0images: {\n\n\u00a0\u00a0\u00a0\u00a0remotePatterns: [\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0protocol: 'https'<\/span>,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0hostname: 'res.cloudinary.com'<\/span>,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0pathname: '\/**'<\/span>,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0},\n\n\u00a0\u00a0\u00a0\u00a0],\n\n\u00a0\u00a0},\n\n\u00a0\u00a0webpack: (config, { isServer }) => {\n\n\u00a0\u00a0\u00a0\u00a0\/\/ Example: if you have custom server plugins, you can push them here<\/span>\n\n\u00a0\u00a0\u00a0\u00a0if<\/span> (isServer) {\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\/\/ Potential server-only code or plugins<\/span>\n\n\u00a0\u00a0\u00a0\u00a0}\n\n\u00a0\u00a0\u00a0\u00a0return<\/span> config;\n\n\u00a0\u00a0},\n\n\u00a0\u00a0async headers() {\n\n\u00a0\u00a0\u00a0\u00a0\/\/ Using next-secure-headers to add recommended security headers<\/span>\n\n\u00a0\u00a0\u00a0\u00a0return<\/span> [\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0source: '\/(.*)'<\/span>,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0headers: createSecureHeaders({\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0xFrameOptions: 'SAMEORIGIN'<\/span>,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0xContentTypeOptions: 'nosniff'<\/span>,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\/\/ ... other header settings<\/span>\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0}),\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0},\n\n\u00a0\u00a0\u00a0\u00a0];\n\n\u00a0\u00a0},\n\n};\n\nconst<\/span> withMDX = createMDX({\n\n\u00a0\u00a0extension: \/\\.mdx?$\/,\n\n\u00a0\u00a0options: {\n\n\u00a0\u00a0\u00a0\u00a0rehypePlugins: [\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0rehypeMdxImportMedia,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0rehypeSlug,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0[\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0rehypePrettyCode,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0transformers: [transformerNotationDiff()],\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0theme: 'github-dark-dimmed'<\/span>,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0defaultLang: 'plaintext'<\/span>,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0},\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0],\n\n\u00a0\u00a0\u00a0\u00a0],\n\n\u00a0\u00a0\u00a0\u00a0\/\/ add any remark plugins here if needed<\/span>\n\n\u00a0\u00a0},\n\n});\n\nexport default<\/span> withMDX(nextConfig);\n\n```<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\nIn the code block above, here are what the key sections are for:<\/p>\n\n\n\n
- \n
pageExtensions<\/code><\/strong>. Allows Next.js to process.mdx<\/code> files as pages.<\/li>\n\n\n\nimages<\/code><\/strong> object<\/strong>. We explicitly list Cloudinary as a remote pattern, so Next.js knows to optimize and host images from res.cloudinary.com. Adjust the hostname or pathname as needed.<\/li>\n\n\n\nwithMDX<\/code><\/strong>. The@next\/mdx<\/code> wrapper adds MDX-specific configuration. We specify the file extensions and pass rehype plugins for extra functionality, like syntax highlighting withrehypePrettyCode<\/code>.<\/li>\n<\/ul>\n\n\n\nCloudinary Setup and Environment Variables<\/h2>\n\n\n\n
Before you begin embedding images in .mdx files, make sure you have:<\/p>\n\n\n\n
- \n
- A Cloudinary account where your images or folders reside.<\/li>\n\n\n\n
- A Cloud name, API key, and API secret (if you plan to do programmatic uploads). For the simplest usage (just referencing existing images by URL), you only need your cloud name.<\/li>\n<\/ol>\n\n\n\n
You can store your keys in environment variables. To do so, create a
.env.local<\/code> file in your Next.js root then add these keys and values:<\/p>\n\n\nCLOUDINARY_CLOUD_NAME=your_cloud_name\n\nCLOUDINARY_API_KEY=123456789012345\n\nCLOUDINARY_API_SECRET=abcdefg-hijklmnop<\/code><\/span><\/pre>\n\n\nIf all you plan to do is embed images by static URL (e.g.,
https:\/\/res.cloudinary.com\/<cloud_name>\/image\/upload\/...)<\/code>, you don\u2019t need the API key or secret. However, including them can help if you want to use server-side transformations, automated image fetching, or advanced features.<\/p>\n\n\n\nCreating MDX Files and Embedding Images<\/h2>\n\n\n\n
With your Next.js App Router, you can place MDX files directly in subfolders under app\/ to define routes, or store them in a dedicated app\/docs\/ folder. For example:<\/p>\n\n\n\n
<\/figure>\n\n\n\n
Inside
page.mdx<\/code>, you can add your content in Markdown\/MDX format. Let\u2019s illustrate how to embed a Cloudinary image:<\/p>\n\n\n```markdow\/mdx file\n\n---\n\ntitle: 'Introduction'<\/span>\n\ndate: '2025-01-24'<\/span>\n\n---\n\n# Introduction to Our Docs<\/span>\n\nWelcome! This is a test **MDX** file for<\/span> verifying our Cloudinary image embedding.\n\nBelow is an example image, served directly from Cloudinary:\n\n<\/span>\n\nYou can also embed inlined images or<\/span> dynamic transformations using query parameters, for<\/span> example:\n\n<\/span>\n\n```<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\nHere, we are using standard Markdown syntax for images (
<\/code>), though you could also import them as modules or use a custom React component. As soon as you add these .mdx files and runnpm run dev<\/code> (or your build command), Next.js will treat them like any other page in the App Router structure.<\/p>\n\n\n\nA Closer Look at Next.js App Router<\/h2>\n\n\n\n
The Next.js 13 App Router organizes pages via nested folders inside app\/. Each folder can contain a page.js, page.tsx, or page.mdx (as we\u2019ve just done), which exports the UI for that route.<\/p>\n\n\n\n
- \n
- Layout Files<\/strong>. layout.js or layout.tsx can define shared layouts or wrappers for each segment of the route.<\/li>\n\n\n\n
- page.js<\/strong> or `
.mdx**<\/code>. The actual content or React components that define the UI for that path.<\/li>\n<\/ul>\n\n\n\nIf your docs hierarchy grows, you might nest subfolders like so:<\/p>\n\n\n\n
<\/figure>\n\n\n\n
Each directory with a
page.mdx<\/code> automatically becomes a route:<\/p>\n\n\n\n- \n
\/docs\/quickstart\/<\/code><\/li>\n\n\n\n\/docs\/introduction\/<\/code><\/li>\n<\/ul>\n\n\n\nThis approach is extremely powerful for a developer relations or documentation site, as you can keep all your MDX files in one place without complicated routing logic.<\/p>\n\n\n\n
Global MDX Components (Replacing <img> With Next.js <Image>)<\/h2>\n\n\n\n
One of the powerful features of MDX is the ability to override default HTML elements with React components. For instance, you can globally replace <img> with Next.js\u2019s native <Image> component to get automatic optimization, lazy loading, and more.<\/p>\n\n\n\n
Create a file called
mdx-components.js<\/code> (or.tsx<\/code>) in your components\/ folder:<\/p>\n\n\n```markdow\/mdx file\n\n---\n\ntitle: 'Introduction'<\/span>\n\ndate: '2025-01-24'<\/span>\n\n---\n\n# Introduction to Our Docs<\/span>\n\nWelcome! This is a test **MDX** file for<\/span> verifying our Cloudinary image embedding.\n\nBelow is an example image, served directly from Cloudinary:\n\n<\/span>\n\nYou can also embed inlined images or<\/span> dynamic transformations using query parameters, for<\/span> example:\n\n<\/span>\n\n```<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\nIn your root layout or a dedicated provider file, import this
useMDXComponents<\/code> function to let Next.js know how to interpret elements in your MDX:<\/p>\n\n\n```\n\/\/ app\/layout.js (or wherever you manage MDX context)<\/span>\n\nimport '.\/globals.css'<\/span>; \/\/ example CSS import<\/span>\n\nimport { useMDXComponents } from '@\/components\/mdx-components'<\/span>;\n\nimport { MDXProvider } from '@mdx-js\/react'<\/span>;\n\nexport default<\/span> function<\/span> RootLayout<\/span>({ children })<\/span> <\/span>{\n\n\u00a0\u00a0const<\/span> mdxComponents = useMDXComponents({});\n\n\u00a0\u00a0return<\/span> (\n\n\u00a0\u00a0\u00a0\u00a0<html lang=\"en\"<\/span>>\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<body>\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<MDXProvider components={mdxComponents}>\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{children}\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/MDXProvider>\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/body>\n\n\u00a0\u00a0\u00a0\u00a0<\/html>\n\n\u00a0\u00a0);\n\n}\n\n```<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\nNow, any <img> tags you place in
.mdx<\/code> files become Next.js <Image> components automatically, allowing you to serve Cloudinary images with built-in optimizations.<\/p>\n\n\n\nTesting the Functionality<\/h3>\n\n\n\n
With the configurations in place, run this command in your terminal:<\/p>\n\n\n
npm run dev<\/code><\/span><\/pre>\n\n\nVisit one of your MDX-defined routes, such as
\/docs\/introduction\/<\/code>.<\/p>\n\n\n\nObserve how the page loads your Cloudinary-hosted images. If you open your browser\u2019s network tab, you\u2019ll see that images load from res.cloudinary.com, potentially with additional query parameters if you set transformations.<\/p>\n\n\n\n
Production Build<\/h2>\n\n\n\n
If you want to see how everything runs in production mode:<\/p>\n\n\n
``<\/span>`\n\nnpm run build\n\nnpm run start\n\n`<\/span>``<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nNext.js will compile your MDX files, ensuring the pages function the same, but with production optimizations. Cloudinary images will be optimized, sized, and delivered in next-gen formats when possible (e.g., WebP<\/a>) to browsers that support them.<\/p>\n\n\n\n
Dynamic Transformations with Cloudinary<\/h2>\n\n\n\n
One of Cloudinary\u2019s biggest draws is the ability to transform images on the fly. For instance, specifying
w_300,h_200,c_fill<\/code> (width=300, height=200, crop=fill) will automatically resize and crop. If you want to use these transformations in your MDX images, simply append them to the URL:<\/p>\n\n\n`![Transformed Example](<a<\/span> href<\/span>=\"https:\/\/res.cloudinary.com\/\"<\/span>><\/span>https:\/\/res.cloudinary.com\/<\/a<\/span>><\/span><cloud_name<\/span>><\/span>\/image\/upload\/w_300,h_200,c_fill\/v1670000000\/sample.jpg)`<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\nOr if you want advanced usage, you can build a custom server-side route in Next.js to sign transformation requests using your Cloudinary API credentials. However, for many docs or blog scenarios, simply building the transformations into the URL is sufficient.<\/p>\n\n\n\n
Potential Advanced Patterns<\/h3>\n\n\n\n
- \n
- Custom route for images<\/strong>. If you need more fine-tuned control over transformations, you could create an API endpoint (e.g.,
app\/api\/images\/route.js<\/code>) to fetch images from Cloudinary with secret transformations or dynamic logic based on user input.<\/li>\n\n\n\n
- page.js<\/strong> or `
- Layout Files<\/strong>. layout.js or layout.tsx can define shared layouts or wrappers for each segment of the route.<\/li>\n\n\n\n
- rehype-mdx-import-media<\/strong><\/a>. Allows MDX to handle media imports, like images or other files, within the MDX content.<\/li>\n\n\n\n
- Familiarity with MDX<\/a> or Markdown<\/a>, including how MDX can incorporate React components.<\/li>\n\n\n\n