Como desarrolladores de JavaScript y TypeScript, a menudo nos encontramos con errores inesperados al trabajar con diferentes sistemas de módulos. Un problema común es el error "No se puede utilizar la declaración de importación fuera de un módulo". Por lo general, surge cuando se trabaja con módulos ES modernos (ESM) o cuando se trata de configuraciones que involucran paquetes como entornos Webpack, Babel o Node.js. En este blog, exploraremos las causas de este error, por qué ocurre y soluciones prácticas para resolverlo.

¿Qué significa este error?

El error “No se puede usar una declaración de importación fuera de un módulo" se explica por sí mismo: ocurre cuando JavaScript encuentra una declaración de importación fuera de un módulo ES válido. En JavaScript, los sistemas de módulos determinan cómo se divide el código en múltiples archivos y cómo interactúan entre sí. Los módulos ES (importación/exportación) y CommonJS (require/module.exports) son los dos sistemas de módulos principales.

Si JavaScript no reconoce su código como un módulo ES, arroja este error.

¿Qué causa el error "No se puede utilizar la declaración de importación fuera de un módulo"?

Esto generalmente ocurre cuando JavaScript/TypeScript encuentra una declaración de importación fuera del contexto de un módulo. Lo que significa que el archivo desde el que estás intentando importar no se reconoce como un módulo ES.

Estas son algunas de las razones más comunes por las que puede ocurrir este error:

• Node.js usa CommonJS de forma predeterminada: de forma predeterminada, Node.js usa módulos CommonJS (CJS), no módulos ES. Esto significa que la sintaxis de importación/exportación no es compatible de forma nativa a menos que se especifique.

• Babel/Webpack mal configurado: al agrupar su código, es posible que herramientas como Babel o Webpack no estén configuradas para manejar módulos ES correctamente, especialmente si el entorno de destino no los admite de forma nativa.

• Falta "tipo": "módulo" en paquete.json: si estás usando módulos ES en un proyecto Node.js, debes especificarlo explícitamente agregando "tipo" : "módulo" en su paquete.json.

• La extensión del archivo no coincide: a veces, usar .js en lugar de .mjs para módulos ES o viceversa puede generar este error.

Soluciones paso a paso

Aquí hay algunas soluciones para corregir el error "No se puede usar la declaración de importación fuera de un módulo":

• Habilitar módulos ES en Node.js:

El caso más común es cuando se trabaja con Node.js, que de forma predeterminada utiliza módulos CommonJS. Para habilitar los módulos ES, haga lo siguiente:

Método 1: Modificar paquete.json:

{
  "type": "module"
}

Al agregar "type": "module" a tu paquete.json, le estás diciendo a Node.js que trate todos los archivos .js como módulos ES.

Método 2: cambiar el nombre de los archivos a .mjs:

Si no desea modificar su paquete.json, puede cambiar el nombre de sus archivos a .mjs (por ejemplo, index.mjs) para indicar explícitamente que son módulos ES.

• Actualizar configuración de Babel/Webpack:

Si está utilizando Babel o Webpack, asegúrese de que estén configurados para manejar los módulos ES correctamente. Para Babel, puede utilizar el complemento @babel/preset-modules. Para Webpack, establezca el módulo en falso en su configuración.

Para Babel: actualice el archivo .babelrc o babel.config.json:

{
  "presets": ["@babel/preset-modules"]
}

Para Webpack: actualice el archivo webpack.config.js:

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env']
          }
        }
      }
    ]
  }
};

• Verificar ruta de importación y sintaxis:

Asegúrese de que las rutas de importación sean correctas y de que esté utilizando la sintaxis correcta. Por ejemplo, las rutas relativas deben comenzar con ./ o ../.

Si estás importando un módulo desde node_modules, asegúrate de que el paquete admita módulos ES. De lo contrario, es posible que necesites usar un paquete como Webpack para manejarlo.

• Verifique dos veces las extensiones de archivo:

Si estás usando módulos ES, asegúrate de que las extensiones de tus archivos coincidan con el tipo de módulo. Utilice .mjs para módulos ES y .js para módulos CommonJS.

• .mjs: módulos ES
• .cjs: módulos CommonJS

¿Cuál es la diferencia entre los módulos ES y los módulos CommonJS?

Entonces, una cosa que me viene a la mente es ¿cuál es la diferencia entre los módulos ES y los módulos CommonJS? ¿Y por qué hay dos sistemas de módulos diferentes en JavaScript?

Módulos ES

Los módulos ES son el sistema de módulos JavaScript oficial introducido en ES6 (ES2015). Utilizan las palabras clave import y export para definir dependencias entre módulos. Los módulos ES son analizables estáticamente, lo que significa que las dependencias se resuelven en el momento de la compilación, lo que facilita la optimización del código.

Los módulos ES se cargan de forma asincrónica, lo que permite un mejor rendimiento y la carga paralela de los módulos. También admiten exportaciones con nombre, exportaciones predeterminadas y dependencias cíclicas. Los módulos ES son ampliamente compatibles con los navegadores modernos y Node.js (con el indicador "tipo": "módulo").

Módulos JS comunes

CommonJS es un sistema de módulos utilizado en Node.js y otros entornos antes de que se introdujeran los módulos ES. Los módulos CommonJS utilizan la función require para importar módulos y module.exports o exportaciones para exportar valores. Los módulos de CommonJS se cargan sincrónicamente, lo que puede provocar problemas de rendimiento.

Los módulos CommonJS no son compatibles de forma nativa con los navegadores, pero se pueden transpilar a módulos ES utilizando herramientas como Babel o Webpack. Los módulos CommonJS todavía se utilizan ampliamente en proyectos Node.js, pero los módulos ES se están volviendo más populares debido a su mejor rendimiento y capacidad de análisis estático.

La razón por la que existen estos dos sistemas de módulos se debe a la evolución de JavaScript y la necesidad de un sistema de módulos estandarizado más moderno. Los módulos ES son el futuro de los módulos JavaScript, pero los módulos CommonJS todavía se utilizan ampliamente en proyectos y entornos existentes.

Consejos de depuración

Si probaste todas las soluciones anteriores y aún enfrentas el error, aquí tienes algunos consejos de depuración adicionales:

• Verifique la versión de Node.js: asegúrese de estar ejecutando Node.js versión 12.x o superior, ya que la compatibilidad con los módulos ES se introdujo de forma nativa en Node.js 12. Si está en una versión anterior, los módulos ES no funcionarán. Actualice su versión visitando el sitio web de Node.js.

• Verifique la compatibilidad del navegador: si está trabajando en un entorno de navegador, asegúrese de que su navegador admita módulos ES. La mayoría de los navegadores modernos lo hacen, pero es posible que las versiones anteriores no.

• Compruebe si hay errores tipográficos: A veces, un simple error tipográfico en su código puede causar este error. Vuelva a verificar su código para detectar errores ortográficos o sintaxis incorrecta.

• Usa npx tsc para TypeScript: si estás usando TypeScript y encuentras este error, ejecuta npx tsc para compilar tu código TypeScript en JavaScript, lo que podría ayudarte a detectar problemas.

Conclusión

El error "No se puede usar la declaración de importación fuera de un módulo" es un problema común que enfrentan los desarrolladores de JavaScript/TypeScript cuando trabajan con módulos ES. Si comprende por qué ocurre este error y sigue las soluciones paso a paso proporcionadas en este blog, podrá resolverlo rápidamente y continuar creando código modular y mantenible.