Resolviendo el error de Turbopack con MDX en NextJS 16

Si estas usando NextJS 16 con MDX para crear contenido (como documentacion o un blog), probablemente te hayas encontrado con el error de Turbopack con MDX cuando intentas correr tu proyecto:

Error: 'client-only' cannot be imported from a Server Component module.

Este articulo cubre que esta pasando, por que ocurre y como solucionarlo definitivamente.

El contexto: Turbopack es el default en NextJS 16

Turbopack es el bundler oficial de NextJS, disenado para ser mas rapido que Webpack. A partir de NextJS 16, Turbopack es el bundler por defecto tanto para desarrollo como para builds de produccion:

// package.json - Turbopack se usa automaticamente
{
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  }
}

El problema: @next/mdx + Turbopack = Error

Cuando intentas usar @next/mdx con Turbopack, ves este error:

Error: loader C:\...\node_modules\@next\mdx\mdx-js-loader.js
for match "#next-mdx" does not have serializable options.
Ensure that options passed are plain JavaScript objects and values.

O este otro:

Error: 'client-only' cannot be imported from a Server Component module.
It should only be used from a Client Component.

¿Por que pasa esto?

El problema es que Turbopack no es compatible con el loader de @next/mdx. El paquete @next/mdx usa un sistema de loaders de Webpack que Turbopack no puede procesar:

• MDX necesita transformar archivos .mdx a JavaScript
• El loader de @next/mdx usa configuraciones complejas con plugins de remark/rehype
• Turbopack no puede serializar estas configuraciones
• Resultado: el build falla

La solucion recomendada: Migrar a next-mdx-remote

La solucion definitiva es reemplazar @next/mdx con next-mdx-remote. Esta libreria no depende del loader de Webpack, procesa MDX en runtime y es totalmente compatible con Turbopack.

npm install next-mdx-remote gray-matter
npm uninstall @next/mdx @mdx-js/loader @mdx-js/react

// next.config.ts - Limpio, sin createMDX
import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  pageExtensions: ['js', 'jsx', 'ts', 'tsx'],
};
 
export default nextConfig;

content/
└── blog/
    ├── mi-primer-post.mdx
    └── segundo-post.mdx

---
title: "Mi primer post"
description: "Un post de ejemplo"
slug: "mi-primer-post"
---
 
# Mi primer post
 
Contenido del post con **Markdown** y componentes.

// lib/content.ts
import fs from "fs";
import path from "path";
import matter from "gray-matter";
 
const CONTENT_DIR = path.join(process.cwd(), "content", "blog");
 
export function getPostBySlug(slug: string) {
  const filePath = path.join(CONTENT_DIR, `${slug}.mdx`);
  const fileContent = fs.readFileSync(filePath, "utf-8");
  const { data, content } = matter(fileContent);
 
  return {
    frontmatter: data,
    content,
  };
}
 
export function getAllPosts() {
  const files = fs.readdirSync(CONTENT_DIR)
    .filter((f) => f.endsWith(".mdx"));
 
  return files.map((file) => {
    const slug = file.replace(".mdx", "");
    return getPostBySlug(slug);
  });
}

// app/blog/[slug]/page.tsx
import { MDXRemote } from "next-mdx-remote/rsc";
import { getPostBySlug, getAllPosts } from "@/lib/content";
 
export function generateStaticParams() {
  const posts = getAllPosts();
  return posts.map((post) => ({
    slug: post.frontmatter.slug,
  }));
}
 
export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const { frontmatter, content } = getPostBySlug(slug);
 
  return (
    <article>
      <h1>{frontmatter.title}</h1>
      <MDXRemote source={content} />
    </article>
  );
}

Solucion temporal: Forzar Webpack

Si no puedes migrar a next-mdx-remote de inmediato, puedes forzar el uso de Webpack:

// package.json
{
  "scripts": {
    "dev": "next dev --webpack",
    "build": "next build --webpack"
  }
}

Comparacion de enfoques

¿Cuales son las ventajas de migrar?

Ademas de resolver el error de Turbopack, migrar a next-mdx-remote te da:

1. Frontmatter YAML: Metadata del post en formato estandar, no como exports de JavaScript
2. Syntax highlighting avanzado: Integra rehype-pretty-code para bloques de codigo con colores reales
3. Builds mas rapidos: Turbopack es significativamente mas rapido que Webpack en proyectos grandes
4. Separacion de contenido y codigo: Tu contenido vive en content/, no mezclado con la app
5. generateStaticParams: SSG completo para todas tus paginas de contenido

Verificando que funciona

Despues de migrar, verifica que todo funciona correctamente:

rm -rf .next
npm run dev

npm run build

Conclusion

El error de Turbopack con MDX en NextJS 16 ocurre porque @next/mdx no es compatible con el nuevo bundler por defecto. La solucion definitiva:

1. Migra a next-mdx-remote para compatibilidad total con Turbopack
2. Mueve tu contenido a una carpeta content/ con frontmatter YAML
3. Usa rehype-pretty-code para syntax highlighting de calidad

Para la mayoria de proyectos, la migracion toma menos de una hora y el resultado es un pipeline de contenido mas robusto y rapido. Si quieres entender mejor como interactuan Server y Client Components con el ciclo de vida de React, eso te ayudara a diagnosticar errores similares.

Recursos adicionales

• NextJS MDX Documentation
• Turbopack Documentation
• next-mdx-remote en GitHub