Publicación de bibliotecas de TS para diversión y beneficio

♪ Hola, mi nombre es Mark Erickson, y hoy estoy muy emocionado de hablarles sobre la publicación de bibliotecas TypeScript para divertirse y obtener ganancias. ¿Mayormente emocionado? ¿Algo emocionado? Bueno, miren, ha sido un año realmente difícil. No ha habido mucha diversión. Y en realidad, créanme, no ha habido ninguna ganancia en absoluto. Vamos a repasar los detalles.

Un par de cosas rápidas sobre mí. Soy un ingeniero senior de front-end en Replay, donde estamos construyendo un depurador de viaje en el tiempo para JavaScript. Por favor, échenle un vistazo. Responderé preguntas prácticamente en cualquier lugar donde haya un cuadro de texto en Internet. Recolecto todo tipo de enlaces interesantes. Escribo publicaciones de blog extremadamente largas. Soy un mantenedor de Redux, pero la mayoría de la gente me conoce como ese tipo con el avatar de los Simpsons.

Entonces, ¿publicar paquetes es realmente simple, verdad? Simplemente ejecutas TSC y npm publish, y listo. Gracias. Oh chico, wow, ojalá fuera tan fácil. Esta charla sería mucho más corta si lo fuera. A principios de este año me molesté un poco y publiqué un tweet donde enumeré algunas de las cosas que debes tener en cuenta al publicar paquetes. Formatos de archivo de los artefactos de compilación, si debes empaquetar o mantener archivos JavaScript individuales, exportaciones de paquetes, WebPack 4, resolución de módulos de TypeScript, diferentes entornos de usuario, diferencias de comportamiento del empaquetador, Node ESM versus CGS, si debes empaquetar tus tipos de TypeScript y el uso del cliente de React. No hay guías. Todos están tomando prestado de todos los demás, y es un milagro que este ecosistema funcione en absoluto.

Entonces, ¿cómo me involucré en este proceso? Bueno, he estado manteniendo Redux durante los últimos años, y desde principios de este año, he mantenido cinco bibliotecas diferentes. Redux core, React Redux, Redux Slunk, Reselect y Redux Toolkit. Cada una de estas tenía una configuración de compilación algo diferente, pero en general, había una mezcla de artefactos de compilación ESM, CommonJS y UMD. Todo usaba la extensión .js. Todo se compilaba a ES5 para ser compatible con IE11. La mayoría de los paquetes usaban rollup más babble, excepto Redux Toolkit, que usaba es-build. Ninguno de los paquetes definía el campo de exportaciones en package.json, y se usaban una variedad de carpetas diferentes para la salida de compilación.

Entonces, ¿qué significa realmente el soporte de ESM? El problema aquí es que la especificación del lenguaje ES2015 definió la sintaxis para importar y exportar, y algunos de los comportamientos esperados, pero no definió cómo los entornos de ejecución, como el navegador o Node, deben manejar la carga de estos, o cómo deben interoperar con otros formatos de módulo como CommonJS. La mayoría de nosotros hemos estado escribiendo sintaxis de ESM durante años, pero cuando publicas una biblioteca, normalmente la conviertes a CommonJS antes de publicarla. Y también sueles compilar tu sintaxis a ES5, para que funcione en IE11, desafortunadamente.

Entonces, el JSON empaquetado tiene varios campos diferentes que diferentes herramientas buscan para encontrar el archivo correcto. Node busca en el campo principal para archivos CommonJS, los empaquetadores a menudo buscan en el campo de módulo para ESM, las CDNs y herramientas como unpackage buscan diferentes claves, TypeScript busca sus tipos de TypeScript, y todas estas diferentes herramientas tienen diferentes expectativas. Además, a Node le llevó años agregar un soporte decente para módulos ES porque estaban tratando de averiguar cómo funcionaría con CommonJS.

Entonces, hay un campo relativamente nuevo llamado exports, y se supone que es el único lugar definitivo donde le dices a las herramientas cómo encontrar tus diferentes puntos de entrada y diferentes formatos de archivo. Entonces puedes encontrar una gran cantidad de puntos de entrada diferentes, puedes tener condiciones anidadas, como aquí es donde encontrar un archivo ESM versus un archivo CommonJS, puedes definir condiciones como desarrollo y producción. Pero el problema es que agregar exports es realmente un cambio rompedor para tu paquete, lo que significa que solo puedes hacerlo en una versión principal.

Entonces, ¿cómo entiende Node si un archivo dado es ESM o CommonJS? Hay dos formas diferentes. Una es que ahora te permite usar una extensión de archivo .mjs o .cjs para declarar qué tipo de módulo es, o puedes agregar el campo de tipo de módulo en el nivel superior, o tipo CommonJS, y cada archivo con una extensión .js se tratará como si fuera ese tipo de módulo. Entonces, a principios de año, decidimos modernizar todos los paquetes de Redux. Habíamos recibido algunos informes de errores de que no se podían importar correctamente en un entorno Node-ESM. En realidad, habíamos migrado el núcleo de Redux a TypeScript en 2019 y luego nunca lo lanzamos. La versión 4 funcionaba bien y teníamos preocupaciones sobre lanzar una nueva versión principal. Y queríamos modernizar toda la salida de compilación y enviar sintaxis JS moderna para tamaños de paquete más pequeños.

Entonces, basado en mi investigación, pensé que todo lo que tenía que hacer era agregar type module y un campo de exports y todo funcionaría perfectamente. ¿Verdad? ¿Verdad? No. No, en absoluto. Presenté una solicitud de extracción que intentaba modernizar Redux toolkit como mi primer intento. Agregué type module y exports, modernicé toda la salida de compilación. También tuve que hacer cambios en un montón de scripts que teníamos que eran archivos Common JS, porque con type module ahora se tratan como archivos ESM. Pero lo intenté y luego todo explotó. Bueno, está bien. Principalmente las cosas explotaron bajo Jest. Redux Thunk y Emmer tienen exportaciones predeterminadas. Jest se estaba confundiendo mucho sobre cómo interpretar las exportaciones predeterminadas versus las exportaciones con nombre. Terminé intentando publicar una versión alfa de Redux Thunk para solucionar esto, pero eso no ayudó mucho. Pude cambiar a las exportaciones con nombre de Emmer y eso ayudó un poco. En realidad, me cansé y cambié todas nuestras pruebas de usar Jest a VTest porque se suponía que tenía un mejor soporte de ESM. Y eso fue bastante bien.

La mayor parte fue simplemente una búsqueda en el lugar más un archivo de configuración diferente. Así que publiqué las primeras versiones alfa del núcleo de Redux y Redux Toolkit en enero, y probablemente la gente comenzó a decirme que lo estaba haciendo mal. Matusz Brzezinski, que es un experto en este tipo de cosas, tenía un montón de sugerencias diferentes. La gente presentó problemas diciendo que no funcionaba cuando la resolución de módulos se establecía en node 16 para TypeScript. Y alguien más señaló que, bueno, en realidad, la cosa del ESM de Node que estás tratando de arreglar en realidad ni siquiera funciona realmente. Y yo no estaba contento. Sentía que estaba recibiendo consejos contradictorios de todos. Así que era hora de hacer una investigación.

Tuve una llamada con Matusz Brzezinski, donde dio su opinión sobre lo que debería intentar. Incluso sugirió, como, ¿realmente vale la pena enviar el ESM? Tal vez deberías hacer solo CommonJS. También tuve una llamada con Andrew Branch del equipo de TypeScript, quien ha estado trabajando mucho en el soporte de módulos de TypeScript. Y me dio muchos detalles sobre cómo TypeScript interpreta los archivos de módulo y todas las diferentes instrucciones, así como información clave sobre cómo TypeScript y Node saben si un archivo dado es CommonJS o ESM. Y realmente se trata de usar la extensión de archivo correcta, como .mjs, o tener ese tipo de módulo. Y aunque no me gusta mucho la extensión de archivo .mjs, resulta que su uso realmente simplifica varias cosas dentro del proyecto.

Así que estaba muy claro que estaba en aprietos con todo esto y simplemente intentar mirar una definición de paquete para averiguar si iba a funcionar, no iba a ser escalable. Así que necesitaba configurar verificaciones de CI para ver cómo diferentes herramientas interpretaban las cosas. El problema es que hay al menos media docena de empaquetadores diferentes y herramientas de compilación, cada uno con sus peculiaridades. Así que terminé escribiendo una pequeña aplicación de ejemplo y luego construyéndola con create React app 4 y 5 y V y Next y un par de configuraciones de nodo diferentes y ejecutando todo eso en cada solicitud de extracción solo para ver cómo iba a interpretar la configuración de empaquetado. Resulta que React Aria está haciendo algo bastante similar. También descubrí que Andrew Branch había estado construyendo una herramienta llamada Are The Types Wrong? como un resultado de su trabajo en la definición de módulo y la documentación de TypeScript. Ahora, originalmente, esto era solo un sitio web. Así que podías escribir un nombre de módulo o podías subir un archivo empaquetado, y lo escanearía e intentaría decirte, aquí está cómo TypeScript lo interpretará todos los diferentes puntos de entrada y definiciones de tipo. En ese momento, no había una CLI para esta herramienta, así que terminé escribiendo la mía propia y tratando de usarla en nuestras verificaciones de CI. Más tarde, se agregó una herramienta de línea de comandos oficial para Are The Types Wrong? y en realidad todavía necesito cambiar y hacer uso de eso. Pero ha sido extremadamente útil tanto en el desarrollo local como en CI para verificar que todas las definiciones del paquete estén configuradas de la manera correcta.

Entonces, unos meses después, estaba listo para intentarlo de nuevo y decidí trabajar primero en la biblioteca Redux Thunk porque es realmente pequeña. Sin embargo, todavía se estaba construyendo con Babel y Rollup, y quería cambiar a usar ESBuild, así que encontré un envoltorio muy bueno llamado TsUp. Pude configurarlo bastante rápido y funciona bastante bien. Es un envoltorio alrededor de ESBuild dirigido a bibliotecas de TypeScript. También tiene la capacidad de generar un archivo ts TypeDefs empaquetado para ti. Así que terminé con este paquete y es mejor, aunque probablemente aún necesita un poco de trabajo desde allí.

Ahora, mencioné anteriormente que enviamos formatos de archivos ES modules, CommonJS y UMD. ¿Qué es un archivo UMD? Universal Module Definition es un formato de módulo realmente extraño que se puede utilizar simultáneamente como un archivo AMD, un archivo CommonJS o una etiqueta de script global. No requiere mucho más esfuerzo mantenerlo, pero se sentía obsoleto y no sabía si deberíamos mantenerlo. Así que busqué, seguí pidiendo consejo y el mejor consejo que encontré fue que probablemente ya no lo necesitaba. Incluso para algo como CodePen, que ahora tiene soporte para ES modules, probablemente no lo necesites. Así que tomé la decisión de eliminar los archivos UMD de nuestros paquetes, aunque los reemplacé con una compilación ESM especial que se ha precompilado en modo de producción, por lo que debería funcionar bien en los navegadores.

Luego descubrí que Webpack 4 no le gustaba la configuración porque, en primer lugar, no admite el campo de exportaciones, tampoco admite el análisis de objetos ES 2018 con sintaxis de propagación o sintaxis de encadenamiento opcional. Y además, no puedes tener un archivo .mjs en el campo principal, también se bloqueará con eso, así que tienes que cambiar a una extensión .js solo para eso. Y el problema es que Webpack 4 todavía se usa bastante ampliamente por una serie de configuraciones de compilación más antiguas. Así que, para tratar de evitar romper el ecosistema, decidí a regañadientes que voy a enviar un artefacto de compilación adicional, formato ESM, pero compilado a ES 2017 con una extensión .js, solo para mantener contento a Webpack 4.

¿Y qué pasa con los typedefs? Bueno, la versión de tsup que estaba usando en ese momento generaba un archivo de definición empaquetado, pero siempre le daba una extensión .d.ts. Y esto es un problema, porque resulta que Are The Types Wrong? lo informa como una advertencia falsa de CJS cuando estás usando la resolución de módulos Node 16. Y hablando con Andrew Branch, resulta que realmente deberías tener archivos separados con una extensión .d.mts y .d.cts, para que TypeScript realmente sepa cómo se ven los tipos cuando se ejecuta en modo ESM versus modo CommonJS, porque puede haber algunas diferencias. Decidí posponer la solución de ese problema por ahora. Todavía es algo que necesito volver a revisar. Andrew Branch presentó una solicitud de extracción para .tsup, para que intente generar diferentes archivos de definición de TypeScript empaquetados. Eso salió en una versión posterior de .tsup y todavía necesito probarlo yo mismo.

Entonces, esto es lo que algunos de los paquetes parecen después del segundo intento, y esto es mejor, creo, pero probablemente aún necesita algunos ajustes. Probablemente necesite hacer alguna anidación para la importación y las condiciones predeterminadas para especificar diferentes archivos de definición de tipo para cada uno de ellos. Ahora, Michel Westray, autor de la biblioteca Imer, había estado trabajando en el desarrollo de Imer-10 durante la primavera, y también estaba tratando de modernizar ese paquete y eliminar algunas cosas de compatibilidad con versiones anteriores, y Redux Toolkit depende mucho de Imer. Así que estaba muy ansioso por probar Imer-10 Beta, pero noté que el tamaño del paquete en realidad aumentó un poco. Eso parecía extraño. Así que, en realidad, descargué, cloné el repositorio de Imer, descargué la rama Beta y lo estuve revisando, y descubrí que estaba usando una herramienta de compilación más antigua llamada TSDX y aún generaba mucha sintaxis de compilación ES5 y muchas cosas extrañas allí.

Así que había aprendido mucho, con suerte, sobre cómo empaquetar las cosas, y encontré una solicitud de extracción que cambió a usar TSUp y aplicó todos los mismos cambios de empaquetado que estaba usando en nuestras versiones beta, y eso funcionó y en realidad redujo significativamente el tamaño del paquete en aproximadamente un 40%. Michelle realmente implementó esos cambios como parte de Emerton Final, por lo que ahora está disponible en la práctica.

Luego las cosas se complicaron aún más. En mayo salió Next 13.4, que incluye componentes de servidor de React y el nuevo enrutador de aplicaciones como predeterminado. Las personas han estado intentando usar Redux con esto y, desafortunadamente, las cosas siguen rompiéndose, por lo que hemos estado recibiendo una serie constante de informes de errores de personas que dicen que React Redux o Redux Toolkit no funcionan en un entorno de componentes de servidor.

Ahora bien, mi co-mantenedor de Redux, Lensweber, ha estado trabajando en Apollo Client desde principios de año y ha estado investigando mucho sobre cómo las bibliotecas en el lado del cliente pueden interactuar con un entorno de componentes de servidor. Por lo tanto, presentó un problema de React pidiendo algunos consejos, escribió un RFC sobre cómo hacer que Apollo y Next funcionen juntos e incluso publicó un paquete experimental. Donde las cosas se complicaron realmente fue cuando una versión específica de Next Canary rompió Apollo brevemente. Esto se solucionó bastante rápido, pero generó un hilo de discusión muy largo, detallado y un poco argumentativo. Uno de los desarrolladores de Next dejó un comentario diciendo que los paquetes realmente necesitan publicar un artefacto de compilación adicional con una definición de paquete de servidor de React en su interior. Y eso parecía que iba a confundir mucho las cosas. Entonces Mark Baga dijo que debes asegurarte de que el código del cliente se elimine de allí. Lens y yo nos quejamos de que esto estaba dificultando mucho nuestro trabajo como mantenedores, y me frustré bastante. Puse mucho trabajo en esto. Se siente realmente, realmente desmoralizante.

Unas semanas después, Lens publicó una entrada de blog titulada Mi opinión sobre la controversia actual de los componentes de servidor de React. Había habido muchos argumentos y debates flotando en línea y mucha confusión sobre lo que estaba sucediendo. Y él quería dar nuestras opiniones como mantenedores de bibliotecas. Y dijo que creemos que los componentes de servidor de React son una tecnología realmente útil, pero la forma en que se ha implementado está dificultando mucho ayudar a nuestros usuarios y están presentando muchos más informes de errores. Hay mucho más sobre React y Next que debemos entender y esto dificulta mucho el mantenimiento y la publicación de una biblioteca que funcione con React. Además, realmente parece que ha habido muy poca comunicación por parte del equipo de React sobre cómo este tipo de cosas van a afectar al ecosistema.

Entonces, ¿en qué punto nos encontramos hoy? Tenemos versiones beta del núcleo de Redux y Redux Toolkit que están disponibles y funcionando con estos cambios, y nos gustaría que las personas las probaran. Tenemos versiones alfa de reselect y Redux slunk, y tengo una solicitud de extracción para intentar actualizar el empaquetado de React Redux. Aún necesito volver y terminar eso. Tenemos algunas correcciones para intentar evitar que React Redux se rompa en un entorno de componentes de servidor, y en general los paquetes pasan las comprobaciones de `¿Los tipos están equivocados?`, excepto por esa advertencia falsa de CJS que aún necesito revisar. Entonces, ¿qué he aprendido de todo el esfuerzo de este año? Tengo configuraciones de empaquetado que en su mayoría parecen funcionar. Intentar publicar typedefs definitivamente complica las cosas. Empaquetar mi JavaScript de antemano ayuda en algunos casos, pero es más difícil en otros. Es casi imposible mantenerse al día con todas las diferentes herramientas de compilación y sus combinaciones y entornos y las necesidades únicas que cada una tiene. Y desafortunadamente, no hay una guía definitiva sobre cómo publicar un paquete de la manera correcta.

Llevo años rogando que alguien que realmente sepa lo que está haciendo por favor escriba una guía así. Nadie lo ha hecho todavía. He escrito una larga publicación en el blog con lo mismo, muchas de las lecciones de esta charla. Créeme, no es una guía definitiva. Es una recopilación de todas las cosas dolorosas con las que me he encontrado y a las que me opongo.

El ecosistema necesita desesperadamente mejores herramientas para ayudar con la publicación. TS Up es bastante útil, aunque eso es solo el paso de compilación. Realmente podríamos usar algún tipo de servicio que tome una aplicación de ejemplo y una biblioteca y la compile con media docena de herramientas de compilación y te diga cómo funciona o falla cada una.

Y los componentes de servidor de React son una herramienta muy útil, pero también están interrumpiendo mucho el ecosistema. Hay muchas más cosas que tanto los usuarios como los mantenedores de bibliotecas deben tener en cuenta. Y no hay documentación para los autores de bibliotecas sobre cómo lidiar con esto. Y finalmente, la transición de CommonJS a ESM ha estado ocurriendo durante años y es una pesadilla que no muestra signos de detenerse en cualquier momento pronto.

Así que si quieres más información, esto se basa en una publicación de blog mucho más larga que escribí titulada Mi Experiencia, Modernizando Paquetes a ESM. Puedes encontrar muchos más detalles allí, así como recursos sobre muchas de las cosas que he investigado en mi intento de aprender cómo publicar un paquete correctamente. Espero que esta información te haya sido útil y si estás tratando de publicar un paquete en el entorno actual, lo siento, tienes mi simpatía. Buena suerte.