Fix: MDX Integration Missing in Astro

What Causes This Error?

This error occurs when you have .mdx files in your project but haven’t installed the @astrojs/mdx integration. MDX files require special processing to handle JSX components in Markdown.

The Problem

src/content/blog/
└── my-post.mdx    # ❌ MDX file without integration

---
title: My Post
---

import Button from '../../components/Button.astro'

# Hello

<Button>Click me</Button>

The Fix

Install MDX Integration

npx astro add mdx

This automatically:

1. Installs @astrojs/mdx
2. Adds it to your astro.config.mjs

Manual Installation

npm install @astrojs/mdx

// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
});

Common Scenarios

Basic MDX Usage

---
// src/content/blog/post.mdx
title: Interactive Post
---

import Counter from '../../components/Counter.jsx'

# Welcome

Here's an interactive counter:

<Counter client:load />

Regular markdown still works **with bold** and *italics*.

Components in MDX

---
title: Component Demo
---

import { Image } from 'astro:assets'
import Card from '../../components/Card.astro'
import heroImage from '../../assets/hero.jpg'

<Card>
  <Image src={heroImage} alt="Hero" />
  <p>This is inside a card component!</p>
</Card>

MDX with Client Components

---
title: Interactive Post
---

import Tabs from '../../components/Tabs.jsx'

<Tabs client:load items={['Tab 1', 'Tab 2', 'Tab 3']}>
  Content for tabs
</Tabs>

Exporting from MDX

---
title: Export Example
---

export const metadata = {
  author: 'John Doe',
  readingTime: '5 min'
}

# Article

Content here...

MDX Configuration

// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [
    mdx({
      // Syntax highlighting
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },

      // Remark plugins
      remarkPlugins: [],

      // Rehype plugins
      rehypePlugins: [],

      // Global MDX components
      // extendMarkdownConfig: false,
    }),
  ],
});

Regular Markdown Still Works

src/content/blog/
├── regular-post.md    # ✅ Works without MDX integration
└── interactive.mdx    # Requires MDX integration

Converting MD to MDX

<!-- Before: post.md -->
---
title: My Post
---

# Hello World

<!-- After: post.mdx -->
---
title: My Post
---

import Note from '../../components/Note.astro'

# Hello World

<Note>Now with components!</Note>

When to Use MDX

Use MDX when you need:

• Components in your content
• Interactive elements
• Custom layouts per post
• Exporting data from content

Use regular Markdown when:

• Static content only
• No components needed
• Better performance
• Simpler setup

Quick Checklist

• Run npx astro add mdx
• Or install manually and configure
• Import components at top of MDX file
• Use client directives for interactive components
• Regular .md files don’t need MDX integration