Understanding Package Resolution in Node.js

Hola, hoy voy a hablar sobre la comprensión de la resolución de paquetes en Node.js. Soy Yalcin Zipli. Soy un ingeniero de software senior en Sentry. Soy miembro del Comité Técnico de Node.js y miembro del Consejo de Proyectos Cruzados de la OpenJS Foundation. Puedes contactarme desde mi cuenta de GitHub, github.com, y desde Twitter, axe.com.

En resumen, hoy vamos a hablar sobre CommonJS, ES modules, ESM, la estructura de package.json, y el cargador de package.json en Node.js.

Comencemos con CommonJS. CommonJS es la primera y la estrategia de resolución de módulos más conocida en Node.js. Incluye archivos con require, implementaciones de exportación con module.export o exports. Puede tener una extensión de .cgs o .js. Las llamadas a require no tienen que incluir la extensión del archivo, y cargar un archivo es sincrónico.

Básicamente, si deseas realizar una carga condicional, digamos que tienes una función llamada read file, y justo cuando se ejecuta esta función, deseas cargar un archivo y usar esa implementación en tu función, entonces necesitas usar require dentro de esta función.

La advertencia de esta implementación es que en la primera línea de read file, el módulo cargado perezosamente es ?igual require.reader, eso va a bloquear la ejecución de este archivo porque es una llamada sincrónica.

Y va a bloquear el IOU dependiendo del tamaño del archivo en sí. Como puedes ver, la extensión no es necesaria, .reader. Esto significa que primero el cargador va a verificar la extensión .gs, luego .json y así sucesivamente.

Y luego devolverá un valor y podremos ejecutar esta función. Así que para cargar este archivo sin una extensión, esta implementación realiza una llamada sincrónica al sistema de archivos para entender si el archivo reader.js existe. Si no, verifica automáticamente si reader.

json existe y así sucesivamente, y luego devolverá un error si no se encuentra.

Así que a pesar de la implementación de CommonJS, como dije, CommonJS, para incluir módulos adicionales con CommonJS, necesitas llamarlo con requires. Dentro de la función que deseas requerir, necesitas exportar la implementación con module.express y así sucesivamente. Así que puede tener una extensión de .cgs, que es CommonJS, y .jsimplementation. Pero en los módulos ES, es muy diferente, la idea detrás de esto. Se introdujo en Node.js 8.5.0 con una bandera experimental. Para incluir archivos, necesitas llamarlo con import. Si esta declaración de import está en la parte superior de la implementación, como si no está dentro de la función, entonces puedes usar import blah blah. Pero si está dentro de una función, necesitas evitar la declaración de import porque import devuelve una promesa. Exporta implementaciones con export y export default, y puede tener una extensión de .mgs o .gs y carga asíncrona de un archivo de módulo.

Así que en la base, es una estructura de carga asíncrona. Entonces, para cargar el módulo condicionalmente, al igual que la implementación anterior, necesitas llamarlo con lazyLoadedModule?equal, evita import, y esto hace que esta función particular sea una llamada asíncrona, independientemente de si lazyLoadedModule.do something es asíncrono o no. Esta es la razón principal de esto, que cuando evitas un módulo importante, no bloquea la E/S. Además de eso, hablamos sobre las extensiones de archivo CommonJS y las extensiones de archivo MGS, así que ¿cómo sabemos realmente qué está pasando?

Así que tenemos este archivo package.json en todos nuestros proyectos. Contiene metadatos sobre un proyecto, pero a Node.js solo le importan 5 de esos campos. Name, main, imports, exports, y type. Para el propósito de esta presentación, solo me voy a centrar en el atributo type. Type puede ser un módulo o un CommonJS. Así que creo que entiendes a dónde voy con esto.

Así que en este ejemplo, tenemos un nombre node-congress-2024, tenemos un atributo main, y tenemos un type, que corresponde a módulos. Entonces, ¿cómo sabe Node.js si estás usando ESM o CommonJS? Primero, verifica las extensiones de archivo, Node.js verifica las extensiones de archivo. Si es MGS, entonces es ESM. Si es CGS o JS, entonces es CommonJS. Así que encontrar el package.json, primero verificamos las extensiones.

Si la extensión es básicamente un archivo .js, entonces no sabemos qué es, entonces necesitamos buscar el package.json en el que estamos ejecutando este archivo. Así que necesitamos conocer el contexto. Así que Node.js intenta encontrar el package.json más cercano en el directorio hasta la raíz. Así que verifica para app, my, project, package.json, y así sucesivamente, hasta la raíz. Si no se encuentra, entonces va a asumir otra cosa.

Node.js lo verifica, y siempre que se encuentra el valor de package.json, Node.js verifica el campo type en el package.json. Y si es module, utiliza cargadores ESM, la implementación del cargador en Node.js. Y si no lo es, entonces es CommonJS. Así que si el tipo no está presente, no pudimos encontrar el package.json, ¿qué sucede? Si el tipo no está presente, verificamos una bandera experimental, experimental detect module. Esto es bastante nuevo en Node 20 o 21. Automáticamente verifica si el archivo que estás ejecutando es un archivo CommonJS o un archivo ESM. Esto es particularmente nuevo porque es una bandera experimental, y hay problemas conocidos con ella, pero estamos trabajando en ello.

Así que si tenemos experimental detect module, entonces detectamos si el archivo es un requerido, si es un ESM o un CommonJS. Si no, entonces volvemos a CommonJS. Así que entonces sabemos cómo comienza nuestra aplicación, porque sabemos que el script inicial está escrito en ESM o CommonJS. Pero el problema es, ¿qué sucede si quieres requerir un archivo desde ESM que está implementado en CommonJS? ¿O quieres llamar a una función que es CommonJS o un ESM desde un módulo CommonJS? ¿Qué pasa con la resolución de profundidad de módulo de Node.js? Como si tuvieras módulos de Node implementados, un paquete dentro de tu lista de dependencias, y está implementado en CommonJS o ESM. Así que Node.js verifica el campo type en el package.json de la dependencia. Si es module, utiliza ESM, de lo contrario CommonJS. Si el tipo no está presente, utiliza el tipo del paquete padre, que es el paquete raíz que contiene el package.json de nuestro proyecto.

Así que continuemos con algunos consejos para mejorar el tiempo de carga. Porque hablamos de todos estos cargadores de package.json, llamadas al sistema, hablamos sobre la detección, las extensiones, y así sucesivamente. Así que si quieres evitar todas esas cosas, y si quieres iniciar Node.js lo antes posible, lo que podrías hacer es que, si tienes una aplicación ESM, puedes usar una bandera experimental default type, CLI, que eliminará automáticamente todas esas verificaciones, y siempre devolverá ESM. No verificará la extensión, no verificará nada más, solo cargará el cargador ESM.