Resolviendo el error de Turbopack con MDX en NextJS 15

Si estás usando NextJS 15 con MDX para crear contenido (como documentación o un blog), probablemente te hayas encontrado con este frustrante error cuando intentas usar Turbopack:

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

En este artículo te explico qué está pasando, por qué ocurre y cómo solucionarlo definitivamente.

El contexto: ¿Qué es Turbopack?

Turbopack es el nuevo bundler de NextJS, diseñado para ser más rápido que Webpack. Cuando creas un proyecto nuevo con create-next-app, NextJS 15 lo configura por defecto:

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

El problema: Turbopack + MDX = Error

Cuando intentas usar 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 qué pasa esto?

El problema es que Turbopack aún no tiene soporte completo para el loader de MDX. MDX usa un sistema de loaders personalizado que Webpack maneja bien, pero Turbopack todavía no puede procesar correctamente.

Específicamente:

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

La solución: Usar Webpack (temporalmente)

La solución más simple y efectiva es desactivar Turbopack y volver a usar Webpack hasta que Turbopack tenga soporte completo para MDX.

// Antes
{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build --turbopack"
  }
}

// Después
{
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  }
}

# Detén el servidor (Ctrl+C)
# Limpia el cache
rm -rf .next
# Reinicia
npm run dev

¡Eso es todo! Tu aplicación ahora usará Webpack en lugar de Turbopack, y MDX funcionará perfectamente.

¿Cuál es el impacto?

Probablemente te preguntes: "¿Perderé velocidad al usar Webpack?"

La respuesta corta es: depende del tamaño de tu proyecto.

Comparación de rendimiento

Para proyectos pequeños a medianos (como la mayoría de blogs y documentación), la diferencia en velocidad es mínima y no afectará tu experiencia de desarrollo.

Impacto por tamaño de proyecto:

• Proyectos pequeños (menos de 50 páginas): La diferencia es casi imperceptible
• Proyectos medianos (50-200 páginas): Diferencia perceptible pero manejable
• Proyectos grandes (más de 200 páginas): Diferencia significativa

Alternativas avanzadas

Si realmente necesitas Turbopack (proyectos muy grandes), tienes estas opciones:

Opción 1: Usar .tsx en lugar de .mdx

Puedes escribir tu contenido en archivos .tsx normales importando componentes manualmente:

// app/blog/mi-post/page.tsx
import Callout from '@/components/Callout'

export default function BlogPost() {
  return (
    <article>
      <h1>Mi Post</h1>
      <p>Contenido del post...</p>
      <Callout type="info">
        Una nota importante
      </Callout>
    </article>
  )
}

Pros:

• Funciona con Turbopack
• Type safety completo
• Más control sobre el código

Contras:

• Más verboso que MDX
• Tienes que importar cada componente manualmente
• No tienes la comodidad de escribir en Markdown

Opción 2: Usar un CMS headless

Puedes mover tu contenido a un CMS como:

• Sanity
• Contentful
• Strapi

Obtienes el contenido vía API y lo renderizas en componentes .tsx.

Pros:

• Funciona con Turbopack
• Editor visual para contenido
• Colaboración más fácil

Contras:

• Configuración inicial compleja
• Posible costo adicional
• Dependencia externa

Opción 3: Esperar a soporte oficial

NextJS está trabajando activamente en mejorar el soporte de Turbopack. Puedes:

1. Seguir el progreso en el repositorio oficial
2. Subscribirte a las release notes
3. Probar en futuras versiones

Verificando que funciona

Después de hacer el cambio, verifica que todo funciona correctamente:

# Test Post

Este es un post de prueba para verificar que MDX funciona.

## Características

- Markdown normal ✅
- Componentes React ✅
- Imports ✅

¿Cuándo volver a Turbopack?

Deberías considerar volver a Turbopack cuando:

1. NextJS anuncie soporte oficial completo para MDX
2. Tu proyecto crezca significativamente (200+ páginas)
3. Los builds con Webpack se vuelvan notablemente lentos
4. Hayas actualizado a una versión que lo soporte

Mientras tanto, Webpack es la opción más confiable y estable.

Conclusión

El error de Turbopack con MDX en NextJS 15 es un problema conocido causado por soporte incompleto del bundler. La solución es simple:

1. Quita --turbopack de tus scripts
2. Usa Webpack (el default de NextJS)
3. Espera a que Turbopack tenga soporte completo

Para la mayoría de proyectos, esta solución no tendrá impacto perceptible en velocidad de desarrollo. Prioriza código que funcione sobre velocidad de compilación marginal.

Recursos adicionales

• NextJS MDX Documentation
• Turbopack Documentation
• GitHub Issues sobre Turbopack

¿Te ayudó este artículo? Compártelo con otros desarrolladores que puedan estar enfrentando el mismo problema.

Sobre el autor: Rod Alexanderson es desarrollador web especializado en NextJS y React. Crea documentación técnica en español para ayudar a la comunidad de desarrolladores en Latinoamérica.