Importing Components in MDX

Imports are how you bring the React ecosystem into your MDX files. Want a chart library? Import it. Custom button component? Import it. Utility function for formatting dates? Import it. Standard ES module syntax, same as any JavaScript file.

Import Syntax in MDX

MDX uses standard JavaScript ES module imports. They go at the top of your file, before any content:

Import Rules in MDX

1. Imports must be at the top of the file (or after frontmatter)
2. Standard ES module syntax — nothing MDX-specific
3. Relative paths resolve from the MDX file's location
4. You can import .js, .jsx, .ts, .tsx, .json, and other supported file types

Importing from Local Files

Relative paths start with ./ (same directory) or ../ (parent directory):

Component Imports

Utility and Helper Imports

Data File Imports

Style Imports

Importing from npm Packages

Anything in your node_modules is fair game:

Popular UI Libraries

Utility Libraries

Syntax Highlighting and Code Libraries

Named vs Default Imports

You need to know which kind a module exports to import it correctly.

Default Imports

A module can have one default export. You can name it whatever you want when importing:

Named Imports

Named exports must be imported by their exact name (or aliased with as):

Combining Default and Named Imports

Namespace Imports

Import everything as a single object:

Dynamic Imports

Load components on demand instead of upfront. Great for heavy stuff like charts or editors that not every visitor needs.

React.lazy with Suspense

Conditional Dynamic Imports

Sometimes you only want to load something client-side (like a map library that needs window):

Next.js Dynamic Import Pattern

Import Organization Best Practices

Recommended Import Order

Keep imports consistent. Group them like this:

Grouping Related Imports

Path Aliases

Set up aliases to avoid ugly relative path chains:

Configure aliases in tsconfig.json or your bundler config:

Practical Tips

<div className="tips">

Tip 1: Only import what you use. Tree-shaking works better with named imports than import *.

Tip 2: Barrel files (index.ts) give you clean public APIs for component directories, but watch out for bundle size.

Tip 3: Prefer named imports over namespace imports (* as) for better tree-shaking.

Tip 4: Use dynamic imports for heavy components not needed on initial load (charts, editors, maps).

Tip 5: If you use the same components in many MDX files, configure them as global components in your MDX provider instead of importing everywhere.

</div>

Common Pitfalls

1. Circular imports — File A imports from File B which imports from File A. Restructure to break the cycle.
2. Missing file extensions — Some bundlers need explicit extensions (.js, .jsx). Check your config.
3. Wrong relative path — Relative paths resolve from the current file, not the project root. Use aliases to avoid confusion.
4. Import order causing issues — CSS import order matters for specificity. Side-effect imports run in the order they appear.
5. Importing server-only code in MDX — Components that use Node.js APIs (fs, path) will break in the browser.
6. Forgetting to install packages — import X from 'package' fails if the package isn't in node_modules. Run the install first.

Summary

Imports in MDX follow standard ES module patterns — nothing special to learn. You've got access to the entire npm ecosystem and your local components. Keep your imports organized, use path aliases for deep directories, and reach for dynamic imports when you've got heavy components that not everyone needs. That's it.