Desmitificando npm: Qué Sucede Realmente Cuando Instalas y Publicas

Hola a todos, es genial verlos a todos aquí. Gracias por acompañarme en este lugar tan genial. Y también hola a aquellos de ustedes que están viendo esto en línea. Hoy voy a hablar sobre lo que realmente sucede cuando ejecutas npm install y npm publish. Y antes de comenzar, un poco sobre mí. CJ ha hablado bastante sobre ello. Actualmente soy ingeniero de software en el equipo de npm de GitHub. He estado con el equipo durante unos dos años. Tengo un total de cinco años de experiencia en desarrollo de software. Y el camino que tomé para convertirme en desarrollador es bastante poco convencional. Fui maestro de escuela primaria durante dos años donde enseñé todo a quinto grado. Y antes de eso, era pianista clásico. Antes de unirme al equipo de npm, mi comprensión de npm era bastante limitada. Lo único que tenía que hacer era npm install. Y lo ejecutaba y esperaba que funcionara. Y si no funcionaba, entonces eliminaba el archivo de registro, eliminaba los módulos de nodo, lo intentaba de nuevo, esperaba que funcionara. Si aún no funcionaba, entonces tal vez molestaría a algún ingeniero senior y esperaría que pudieran arreglarlo por mí. Bueno, ahora que me he unido al equipo, tengo una mejor comprensión de cómo funciona npm. Tuve la oportunidad de profundizar más en ello. Así que decidí crear esta presentación para compartir el funcionamiento interno de npm install y npm publish con todos ustedes para que puedan preocuparse menos por npm, pasar más tiempo construyendo cosas increíbles y ganando sus cuadrados verdes de GitHub. Dicho esto, comencemos con lo básico.

¿Qué es npm? La mayoría de las veces cuando hablamos de npm, la gente piensa en el npm CLI. Así es como la mayoría de los usuarios interactúan con npm. Pero en realidad, npm tiene tres partes, el CLI, el registro y el sitio web. Nos estamos enfocando en el CLI hoy, pero a medida que continuamos, puedes ver cómo el comando npm publish interactúa con el registro y el sitio web también.

La presentación de hoy se dividirá en dos partes. Voy a comenzar con npm install y luego pasaré a npm publish. Y pasaré más tiempo en npm install. Déjame mostrarte un error muy común que ocurre cuando ejecutas npm install. ¿Has visto esto antes? Este es el clásico no se pudo resolver la dependencia, específicamente la dependencia de pares en conflicto. Si has visto esto antes, entiendo tu dolor. Si no has visto esto antes, no te preocupes. A medida que pasamos por los pasos de lo que sucede cuando ejecutas npm install, explicaré por qué ocurre este problema y cómo puedes mitigarlo.

Entonces, ¿qué sucede cuando ejecutas npm install? Lo primero que sucede es que el npm CLI analizará el comando que ingresaste. npm install paquete específico, todo, cualquier bandera que puedas tener. Hará una verificación de motor para asegurarse de que tu versión de npm y tu versión de node sean compatibles y también cargará la instancia de npm y los archivos de configuración. Luego procederá a escanear el estado actual. Si tu proyecto tiene módulos de nodo, entonces el CLI escaneará todo el directorio de módulos de nodo y construirá el árbol existente. Si no lo tienes, entonces esta parte se omitirá.

Lo siguiente que sucederá es la parte crítica de npm CLI. Voy a dedicar más tiempo a esta parte. Es el CLI que intentará construir el árbol ideal. Primero necesita un punto de partida. Si tu proyecto tiene un archivo de bloqueo, usará el archivo de bloqueo como punto de partida para construir este árbol ideal. Si no tiene un archivo de bloqueo, entonces usará el package.json como punto de partida. Si tu proyecto tiene tanto shrinkwrap.json como package.json al mismo tiempo, entonces el npm shrinkwrap.json tiene prioridad. Una vez que se determina el punto de partida, mirará el punto de partida para construir el árbol ideal, pero también usará el package.json como la fuente de verdad para construir todo el árbol. Mirará las dependencias específicas en tu package.json, mirará la versión SEMVer para decidir qué necesita ir finalmente en el árbol ideal.

Cuando se trata de tipos de dependencias en package.json, hay cuatro tipos en tu package.json que le importan al comando npm install. Están las dependencies, lo que tu aplicación necesita para ejecutarse, dev dependencies, lo que necesitarás cuando la estés construyendo, optional dependencies, las que son agradables de tener, y luego las peer dependencies, que esperan que la aplicación anfitriona proporcione el paquete en lugar de instalar él mismo. Este es también el tipo de dependencia que está relacionado con el error que vimos anteriormente.

Así que vamos a profundizar en esto. Cuando un paquete tiene una peer dependency, lo que significa es que requiere que otro paquete esté presente, pero no lo instalará por sí mismo. Espera que el usuario lo instale por separado. Así que, como ejemplo, React es una peer dependency de React Router. Pero si instalas React Router, no tendrá React como una dependencia directa. Como en el árbol aquí, el primer ejemplo tiene React como una dependencia directa de React Router. Eso no sucederá si es... Eso está mal.

Mientras que si tienes React instalado como una peer dependency, entonces, como puedes ver, npm parent, la aplicación anfitriona, tiene tanto React como React Router listados como dependencias directas. Aunque React está listado como una peer dependency para React Router. Ahora que tenemos una buena comprensión de lo que son las peer dependencies, podemos ver por qué ocurrió el error que vimos anteriormente. Y voy a mostrarlo construyendo un ejemplo juntos en este espacio.

Así que consideremos este paquete aquí. Tenemos una aplicación anfitriona llamada npm restaurants. En esta aplicación npm restaurant, tiene una dependencia, npm burger, y dos dev dependencies. Npm oil y npm salt. Echemos un vistazo al paquete burger también. Así que npm burger también tiene dos dependencias, npm beef y npm bread. Y tiene una peer dependency, npm utensils, y una optional dependency, npm cheese.

Si instalo npm burger en npm restaurant, el árbol de dependencias se verá algo así. A la derecha tenemos el árbol. Como puedes ver, npm restaurant está en la parte superior, es la aplicación anfitriona. Y npm burger, npm utensils, npm oil, y npm salt son las dependencias directas del anfitrión, npm restaurant. Y luego bajo npm burger, tenemos npm beef, npm bread, y npm cheese como dependencias directas. Observa que aunque npm utensils es una peer dependency para el paquete npm burger, no está listado como una dependencia directa bajo npm burger. En su lugar, está elevado al mismo nivel que npm burger. Parece que es una dependencia directa de npm restaurant.

Quiero comparar este ejemplo de restaurant y burger con tener un restaurante que vende burger en su menú. Ahora imagina que estás en este restaurante, tienes un artículo en el menú, solo tienes burgers. Y decidiste que quieres agregar un segundo artículo a tu menú. Digamos papas fritas. Intentas instalar papas fritas en npm restaurant. Pero luego te encuentras con el problema de no poder resolver la dependencia, conflicto de dependencias entre pares. ¿Por qué está sucediendo eso? Para entender esto, necesitamos mirar el archivo package.json tanto de npm burger como de npm fries lado a lado. Así que aquí a la izquierda tenemos el archivo package.json de npm burger, y a la derecha tenemos el archivo package.json de npm fries.

Observa que ambos paquetes tienen la peer dependency npm utensils. Pero la versión que necesitan es diferente. Para npm burger, se indica cuidado en 1.0.0, lo que significa que solo puede aceptar cualquier cosa que sea mayor o igual a 1.0.0, y menor que 2.0.0. Ahora para npm fries, acepta cualquier cosa que sea mayor o igual a 2.0.0, pero menor que 3.0.0. Esto es como si el burger quisiera este plato blanco y las fries quisieran este cubo. Anteriormente, cuando instalamos npm burger en npm restaurant, ya teníamos npm utensils 1.0.0, el plato blanco, instalado. Debido a que esta es una peer dependency, solo podemos tener una versión del paquete instalada. Cuando intentamos instalar npm fries, la peer dependency npm utensils 2.0.0 para fries en el paquete npm restaurant, vemos un conflicto. Y es por eso que verías este error en tu línea de comandos, que dice no se puede resolver la dependencia, conflicto de peer dependency.

Entonces, si esto sucede, ¿qué puedes hacer? Para solucionar este problema de peer dependency, en general, querrás buscar una versión compatible. Eso podría significar buscar una versión más alta, más baja de npm burger, npm fries, o buscar una versión que acepte la misma versión de npm utensils. Podrías necesitar actualizar la dependencia de una dependencia, o incluso implementar overrides en package.json. La razón por la que no puedo darte una solución específica ahora mismo es porque este problema de peer dependency puede ocurrir en diferentes niveles en tu package.json. Así que realmente, dependiendo de la situación, necesitamos usar diferentes herramientas para solucionarlo.

Volviendo a este paso 3, construir el árbol IDEA, una cosa más que quería resaltar sobre este paso es que tu archivo package.json no solo existe en tu aplicación anfitriona. En realidad, existe en cada paquete que tienes que instalas. Así que cuando el CLI está tratando de construir el árbol IDEA, no solo está mirando el package.json de tu aplicación anfitriona. También está mirando cada package.json de los paquetes que estás instalando. Digamos que el árbol ha terminado de construirse, entonces el CLI procederá a comparar las diferencias del árbol y resolver cualquier conflicto. Tomará decisiones sobre lo que se necesita hacer a continuación, podría ser agregar, eliminar, cambiar, o simplemente no hacer nada. Luego el CLI procederá a descargar los paquetes necesarios del registro o desde la caché si está disponible. Este es un paso donde pueden ocurrir errores. Uno de ellos podría ser que apuntaste a un registro incorrecto, y por lo tanto obtienes un error. O podrías estar intentando instalar un paquete privado, pero no tienes autorización para hacerlo. Así que también obtienes un error. Después de que los paquetes sean descargados por el CLI a una ubicación temporal en una instancia, luego necesitan ser movidos a tus node modules. Si tu proyecto tiene scripts de ciclo de vida en él, esos scripts también se ejecutarán en consecuencia si les permites hacerlo. Y por scripts de ciclo de vida, me refiero a scripts como pre-install o post-install. Después de eso, tu archivo de registro se actualizará para capturar todos los cambios que han ocurrido.

El archivo de registro captura no solo las dependencias listadas en tu package.json, sino también la dependencia de la dependencia. Es por eso que tu archivo de registro puede ser tan masivo. Y finalmente, después de que el archivo de registro se actualiza, el CLI ejecutará npm audit para verificar cualquier vulnerabilidad de seguridad conocida. Y el CLI te devolverá un informe para que normalmente cuando ejecutes npm install, verás un informe similar a este que te dice si tus paquetes no tienen vulnerabilidades, críticas, altas, medias, bajas, y así sucesivamente. Y ese es todo el flujo de npm install.

Sé que acabo de compartir mucha información contigo, así que quiero celebrar un poco que hemos pasado esta parte. Yay, me gusta eso. Muy bien, ahora pasemos a publish. Antes de hablar sobre cómo funciona publish, déjame hacerte una pregunta. ¿Cuántos paquetes hay en el registro de npm hoy? ¿Tenemos alguna suposición? Escucho algunos, mil millones, está bien. Entonces la respuesta actual, a partir de esta mañana cuando verifiqué, es de aproximadamente 3.7 millones de paquetes. Cada uno de ellos fue publicado en el registro de npm, y está activo en este momento. Entonces, ¿qué sucede cuando ejecutas npm publish?

Lo primero que sucede es que el CLI analizará el comando, similar a install. Realizará una verificación del motor, cargará la instancia. Luego limpiará el archivo package.json, normalizará los datos, validará los puntos de entrada, y si hay algún override que necesite aplicarse, este es el momento en que se aplicarán. La mayoría de los overrides serán cosas que configures mediante flags de CLI o en publish config. Luego preparará el tarball. El tarball es el contenido que los usuarios instalarán. Antes de preparar el tarball, si tienes scripts de ciclo de vida como prepublish o prepack, el CLI ejecutará esos, y luego preparará el tarball, y también considerará si tienes un archivo gitignore, archivo npm ignore, qué debería excluirse.

Luego empaquetará todo lo necesario, y una vez que esté listo, si tienes un script postpack, también podría ejecutarse. Y después de que el tarball esté listo, el CLI hará lo que obtendrá todas las versiones existentes de tu paquete para asegurarse de que no estás publicando una versión duplicada. Si lo haces, verás un error como este.

Después de eso, también validará cualquier texto que puedas usar. Después de que los textos sean validados, el CLI hará una verificación de credenciales. Dependiendo de cómo publiques, la verificación podría ser un poco diferente. Si estás usando trusted publishing, OIDC, este es el momento en que se realizará el intercambio de tokens. Si estás publicando con tokens de acceso, entonces en este paso, el CLI validará tu token para asegurarse de que el formato sea correcto.

Algo que quería destacar sobre los tokens, porque npm ha hecho algunos cambios sobre los tokens recientemente, es que en primer lugar, hemos retirado los tokens clásicos heredados. Y en segundo lugar, hemos añadido una fecha de expiración máxima de 90 días a los tokens de acceso granular, específicamente a los tokens de acceso de lectura-escritura. Por lo tanto, si necesitas publicar, recomendamos encarecidamente usar trusted publishing, OIDC, tanto como sea posible. Pero si no puedes y necesitas usar tokens de acceso, entonces aplica el principio de menor privilegio al generar los tokens. Una vez que tus credenciales sean verificadas, el CLI procederá a construir el pacument.

El pacument es básicamente el documento del paquete, que contiene los metadatos del paquete. Los metadatos del paquete están agrupados por versiones. Y en cada versión, tendrá nombre, descripción, palabras clave, URL del tarball, esa información sobre el paquete. Una vez que el pacument está listo, tu paquete está oficialmente listo para ser publicado.

Entonces, el CLI hará una solicitud POST con el pacument, el tarball y la procedencia, si la tienes, al registro para publicar el paquete. En este paso, a veces podrías encontrarte con errores si estás apuntando al registro incorrecto, si no estás autorizado para publicar. Podrías no estar autorizado para publicar por muchas razones diferentes. Tu token no funciona, no eres un mantenedor. Hay varias razones.

Pero suponiendo que tu publicación sea exitosa, entonces si tienes algún script post-publicado, esos se ejecutarán. Y el CLI registrará el mensaje de éxito, y el CLI habrá terminado con la publicación en este punto. En el lado del registro, hará que el paquete sea posible de instalar para otros. También lo hará disponible en npmjs.com, para que si eres el mantenedor del paquete, puedas ir a npmjs.com para gestionar la configuración de tu paquete. Si el paquete es público, entonces el paquete también será buscable y visible en npmjs.com. Y también admitirá un evento de cambio en el feed de replicación. Y ese es todo el flujo de trabajo de npm publish.

Espero haber arrojado algo de luz sobre el proceso de npm install y npm publish. Si tienes alguna pregunta, inquietud, comentario, por favor visita la comunidad de GitHub para unirte a las discusiones allí. Sé que mi equipo las revisa y trata de ver en qué estás interesado, así que por favor únete a esa comunidad. También responderé algunas preguntas aquí, o si tienes algún comentario, por favor encuéntrame después de esto. Me encantaría escucharlos. Ese es el final de mi presentación. Muchas gracias por acompañarme hoy.

Mi primera pregunta para ti es, ¿cómo aprendiste todo esto? ¿Estabas explorando el código fuente del CLI? ¿Hay documentación que podamos encontrar que describa esto? ¿Cuál es tu proceso de aprendizaje para profundizar en algo como esto? Yo uso Copilot para iterar a través del código base. Básicamente, seguí hablando con él y haciendo preguntas, verificando mi comprensión. Porque en nuestro equipo usamos GitHub code spaces, así que no solo puedo ver cómo es el código base del CLI, sino que también puedo ver en el backend cómo están conectadas las cosas. Uso GitHub Copilot para guiarme a través del proceso y así es como lo hice.

Eso es genial. Lo he hecho antes cuando estoy en un nuevo código base o un código base que estoy tratando de entender. Uno de los buenos casos de uso para la IA es tratar de resumir y también señalarte lugares en el código base que quizás no hayas visto antes. Te recordaré, a cualquiera en la sala si quieres hacer preguntas asegúrate de usar ese código allí. Tenemos una pregunta de Pablo que pregunta, ¿qué sucede cuando usas dash dash legacy peer depths para resolver dependencias de pares? ¿Cuáles son algunas de las implicaciones o consecuencias a largo plazo de esto? Esa es una gran pregunta. La bandera tiene múltiples comportamientos y creo que dependiendo de la versión de NPM CLI también será diferente. No quiero darte la información incorrecta aquí sobre lo que exactamente sucederá porque depende de la versión.

Creo que en términos de consecuencias e implicaciones a largo plazo, lo complicado de la dependencia de pares es que incluso si tienes una muy buena gestión a nivel de la aplicación anfitriona, realmente no puedes controlar lo que se usa aguas abajo. Es un consejo muy genérico, pero ten mucho cuidado con lo que estás instalando porque hoy en día muchos de estos paquetes, especialmente con algunos de los eventos recientes, tenemos que ser muy vigilantes sobre lo que estamos instalando. En esa nota, hay una pregunta de Song sobre cómo podemos luchar efectivamente contra la presentación de paquetes maliciosos en la era de la IA.

¿Hay alguna herramienta que podamos usar? ¿Alguna idea sobre eso? Este es un problema realmente urgente en este momento.

Dentro del equipo de NPM estamos preocupados por ello y estamos tratando de hacer lo que podemos, pero yo diría que ciertamente hay herramientas por ahí que podrías usar, pero no puedo realmente sugerir una específicamente ahora mismo porque cada situación es diferente. Pero al menos en el lado de NPM, estamos mirando los typosquats y estamos tratando de – una de las cosas que hemos hecho recientemente es que la gestión de tokens es también una de las estrategias que estamos tratando de usar para asegurar el ecosistema de NPM.

Eso es algo que definitivamente debes tener en cuenta. No tenemos más preguntas por el momento, pero – bueno, aquí hay otra. Veamos. ¿El equipo de NPM – no, no, acabamos de hablar de eso. Lo siento. Genial. Hablemos de esta. Algunos de los otros gestores de paquetes de terceros han pasado a un enfoque basado en symlink para módulos conocidos. ¿Hay alguna razón por la que NPM no ha seguido ese camino? Supongo que para aclarar eso, sé esto de PNPM. PNPM, en lugar de copiar esos archivos en cada instalación que haces, los enlaza simbólicamente a una ubicación única, generalmente hace que las instalaciones sean un poco más rápidas. ¿El CLI hace algún tipo de symlinking o hay planes para hacer las instalaciones más rápidas de alguna manera así? Creo que existe algún symlinking, pero podría no ser de la misma manera que lo hacen los gestores de paquetes de terceros. Claro. Digo esto porque recuerdo haberlo visto cuando estaba investigando y buscando a través de Copilot. Pero dicho esto, no tengo mucha información específicamente sobre el lado del CLI en cuanto a lo que está en la hoja de ruta y si lo vamos a hacer o no. Pero si esto es algo que realmente quieren, por favor exprésenlo en la comunidad de GitHub porque el equipo lo revisa. Sé que los gerentes de producto, algunos de los ingenieros definitivamente lo revisan. Así que si lo quieren, por favor compartan sus comentarios con nosotros.

Definitivamente. Genial. Esta siguiente pregunta es, ¿hay algún beneficio en actualizar las versiones de lockfile? Creo que te refieres a la versión de lockfile 1, 2 y 3. Eso es, creo que inicialmente, la razón por la que hay diferentes versiones de lockfile tiene que ver con las versiones del CLI de NPM. Porque hay versiones muy antiguas del CLI de NPM que pueden hacer ciertas cosas, y luego salieron los lockfiles. Así que no estoy completamente seguro, aparte de eso, si hay funcionalidades adicionales por sí mismas. Eso es algo que desafortunadamente no podré responder en este momento. Genial. Está bien. Y creo que hay diferentes maneras de abordar esta pregunta. Si fueras a, digamos, eliminar un lockfile y luego ejecutar NPM install de nuevo, vas a obtener un nuevo lockfile porque está revisando las últimas versiones instaladas. Eso podría ser de lo que también están hablando.

Creo que en general, es una buena práctica mantener tus dependencias actualizadas en ese aspecto en esa línea. Sí, esta siguiente pregunta, de nuevo, siéntete libre de omitirla si no puedes entrar en ella, pero 3 millones de paquetes es mucho.

¿Cómo se eliminan y auditan los paquetes? Bien. Así que asumiría que cuando dices eliminados y auditados, te refieres tal vez a paquetes maliciosos en lugar de eliminación por parte del usuario. Porque obviamente un usuario puede despublicar su paquete si su paquete no es dependiente por alguien más. Pero si estás hablando de paquetes maliciosos, sé que cuando se publica un paquete, los escaneamos. Y si los identificamos como paquetes maliciosos, serán eliminados. Así que hay un proceso establecido para eso. Genial.

Sí, y eso nos lleva a la siguiente pregunta que se hizo. ¿Se marca como malicioso por automatización? Parece que hay un proceso para eso. Supongo que si se marca, ¿puede haber alguna intervención humana para prevenirlo? Tal vez fue como una falsa alarma o algo así. Supongo, ¿cuál es el proceso cuando un paquete se marca como malicioso? Así que cuando un paquete está siendo marcado como malicioso, tenemos un equipo de confianza y seguridad que lo revisa. Y el equipo de confianza y seguridad realizará la eliminación. Y tienen su conjunto interno de procesos que desafortunadamente no tengo conocimiento. Pero es, según mi entendimiento, el equipo sí interviene. Eso es bueno.

Supongo que lo mantendremos ligero. Aún no hay preguntas. Pero fui a ver cuál fue mi primer paquete publicado en NPM, y fue hace nueve años. Publiqué una biblioteca de CSS materializada. Solo recuerdo que descubrir que podías publicar paquetes NPM fue realmente genial. Literalmente, un comando, y cualquiera en el mundo puede usarlo. ¿Has publicado algún paquete? ¿O recuerdas tu primero o hace cuánto fue?

Así que nunca he publicado ningún paquete NPM antes de unirme a NPM. Oh, wow. Está bien. Lo cual es... Y después de unirme al equipo, tuve que publicar muchos paquetes de prueba. Pero no tengo mi propio paquete publicado. Entiendo. Sí. Para mí, siempre es divertido. También, si se me ocurre una idea de nombre para un paquete, lo publico de inmediato. Solo para que alguien no robe el nombre, similar a intentar comprar un dominio o algo así. Genial.

No tenemos más preguntas, pero ¿hay algo que tal vez no hayas mencionado, que te gustaría que todos supieran? ¿O algo más de lo que te gustaría hablar? Creo que una cosa que quería destacar es que mencioné en la parte de verificación de credenciales anteriormente para el flujo de publicación de NPM, que hay algunos cambios relacionados con tokens que están sucediendo en NPM. Hay algunos cambios de arquitectura segura que están sucediendo que ya se han implementado algunas partes de ellos, pero habrá más de ellos implementándose en las próximas semanas. Y algunos de estos cambios tendrán cambios bastante disruptivos.