Conexión de la biblioteca al proyecto usando npm/yarn link / Sudo Null IT News

¡Hola! Mi nombre es Sveta, soy desarrolladora front-end en el departamento de proyectos especiales de KTS.

Nuestro departamento desarrolla y lanza alrededor de 100 proyectos al año. Con tal carga de trabajo, buscamos constantemente nuevas formas de acelerar y automatizar el trabajo.

Tenemos muchas bibliotecas: con utilidades y ganchos generales, estilos, clases de tienda base, con utilidades para aplicaciones VK y OK. En todas estas bibliotecas, es necesario agregar y reemplazar constantemente algunos elementos y luego probar la funcionalidad de las bibliotecas.

Conectar una biblioteca a un proyecto no es un proceso tan sencillo, especialmente para principiantes. La primera vez nos llevó cinco artículos y diez horas de tiempo cometer errores, comprobar y recopilar novedades para el equipo. Después de eso, decidimos escribir un artículo de ayuda para facilitar la vida de otros desarrolladores y acelerar su trabajo.

Tabla de contenido

¿Cuál es la dificultad de trabajar con bibliotecas y por qué es conveniente nuestro método de conexión?

En la vida cotidiana, un desarrollador recibe tareas de desarrollo de biblioteca con menos frecuencia que tareas de proyecto. Si una persona trabaja con bibliotecas por primera vez, dos cosas le ayudarán: el conocimiento y la ayuda de colegas más experimentados y unas instrucciones claras.

Debe probar la biblioteca después de cada cambio: corregir errores, agregar nueva lógica o cambiar la lógica anterior, reemplazar una versión del paquete con una de las dependencias. Para las pruebas, utilizamos pruebas manuales y pruebas automatizadas.

Estamos cubriendo gradualmente todas nuestras bibliotecas internas con pruebas automáticas, pero escribirlas y probarlas requiere mucho tiempo. Y el enlace npm/yarn le permite ver el efecto de los cambios en el código de la biblioteca inmediatamente en el proyecto al que está conectado. Por tanto, este método facilita las pruebas en tiempo real, pero no excluye la importancia de las pruebas automatizadas.

Conectando y probando la biblioteca paso a paso

Necesitará la biblioteca y un proyecto experimental en el que se probará. Ambos proyectos deben usar la misma versión de hilo que su administrador de paquetes. A continuación, en el artículo, también consideraremos un caso más especial cuando la biblioteca y las dependencias del proyecto incluyen React. Si no tiene una biblioteca de prueba, puede usar biblioteca de pruebas de reacción. Se puede crear un proyecto de prueba usando una de las plantillas de Vite. Instale la biblioteca en el proyecto.

Para conectar la biblioteca al proyecto, en la mayoría de los casos, el comando de enlace de hilo es suficiente. Pero sucede que la funcionalidad de enlace de hilo no es suficiente, y entonces npm link viene al rescate.

Este ejemplo utilizó el siguiente entorno:

npm 10.2.3, hilo 1.22.21, nodo 20.10.0, terminal bash dentro de VS Code 1.84.2, macOS Sonoma 14.1.1

Algunos comandos pueden requerir derechos de administrador. En estos casos, en MacOS y Linux recibirás un error como “Permiso denegado” y en Windows como este: “Acceso denegado. No tienes privilegios suficientes”. Para la solución, escriba sudo antes del comando en macOS y Linux, o abra una terminal con derechos de administrador en Windows.

Imaginemos que la biblioteca que se está probando es @ktsstudio/test-library, este nombre se puede encontrar en el campo “nombre” en package.json en el proyecto de la biblioteca. Se clona en la carpeta de la biblioteca de pruebas y el proyecto de prueba se encuentra en la carpeta del proyecto de prueba. Se supone que el proyecto de prueba ya tiene instalada esta biblioteca.

La estructura de carpetas del proyecto es aproximadamente la siguiente:

Mirar

Navegue hasta la sucursal de la biblioteca con los cambios que desea consultar. Después de eso, siga los pasos a continuación.

1 – Instalar dependencias y construir la biblioteca

Hay dos maneras de hacer esto.

Camino corto — dentro del proyecto con la biblioteca, ejecuta el comando:

yarn install && yarn build

Al inicio del apartado indicamos el entorno que se utilizó durante la comprobación:

npm 10.2.3, hilo 1.22.21, nodo 20.10.0, terminal bash dentro de VS Code 1.84.2, macOS Sonoma 14.1.1.

Ambos métodos funcionan en este entorno. Si después de seguir todos los pasos siguientes el primero no funciona correctamente, primero intenta eliminar los cambios en Yarn.lock y reinstalar las dependencias en los proyectos que estás utilizando. Para hacer esto, puede usar los siguientes comandos y luego seguir los pasos 1 a 4 de la sección actual nuevamente:

root-folder $ cd test-project
test-project $ git restore yarn.lock && rm -rf node_modules/ && yarn install
test-project $ cd ../test-library
test-library $ git restore yarn.lock && rm -rf node_modules/ && yarn install

Si este método aún no funciona o no funciona correctamente, utilice la siguiente opción.

Largo camino:

yarn install && yarn build

Mirar

Estructura de la biblioteca en node_modules del proyecto bajo prueba

Cuando haya copiado la carpeta dist y el paquete.json a otro directorio, debe ejecutar el comando yarn install desde este directorio para instalar dependencias allí. Por ejemplo, en la carpeta larga creó una carpeta similar a una biblioteca de prueba para probar la biblioteca @ktsstudio/test-library.
Así es como se vería la estructura del directorio después de completar los pasos anteriores:

Mirar

Después de esto, todos los comandos relacionados con el proyecto con la biblioteca que se está desarrollando deberán ejecutarse desde el mismo directorio. En nuestro ejemplo, de test-library-like.

Ahora necesita conectar la biblioteca al proyecto de prueba y deshabilitarlo una vez completado el trabajo.

2 – Crear un enlace a instancias de paquetes React

Si la biblioteca @ktsstudio/test-library utiliza la biblioteca React internamente, hay una advertencia a considerar.

Al instalar una biblioteca en un proyecto normalmente usando yarn add el proyecto y la biblioteca pueden usar fácilmente la misma biblioteca bajo el capó. Con esta instalación, las dependencias del proyecto se resuelven correctamente: el administrador de paquetes analiza las dependencias y selecciona las versiones más recientes de las bibliotecas.

Pero al usar yarn link El proyecto crea un enlace simbólico que apunta a la ubicación local de la biblioteca en el sistema de archivos. En este caso, es posible que las dependencias de la biblioteca no estén vinculadas correctamente y la duplicación de paquetes y tipos de React al ejecutar el proyecto provocará errores, cuya causa puede no ser obvia. Por lo tanto, la biblioteca construida debe hacer referencia a una única instancia de React, que se utiliza en el proyecto de prueba.

Para hacer esto, ejecute el comando enlace npm para reaccionar (nombre del paquete en node_modules) y para @types/react si se usan en la biblioteca.

Antes de ejecutar los siguientes comandos, asegúrese de que no haya cambios no confirmados en Yarn.lock en el proyecto de prueba y en la biblioteca, ya que al usar npm link este archivo está siendo modificado.

Dentro del proyecto con la biblioteca en desarrollo, ejecute los comandos:

Por ejemplo, en nuestro caso, los comandos para la ruta corta se verán así:

Esto creará enlaces simbólicos en el entorno global npm y vinculará la biblioteca al paquete en node_modules del proyecto de prueba. Si necesita probar varias bibliotecas, repita este paso para todas ellas.

Para asegurarse de que se creen enlaces a instancias de paquetes, escriba el comando:

npm list -g --depth=0

Busque la instancia de reacción y su instancia @types/react en la lista, donde la ruta apunta a los paquetes incluidos en su proyecto de prueba. Usando nuestro proyecto de prueba como ejemplo, podría verse así:

$ npm list -g --depth=0
/Users/user/.npm-global/lib
├── @types/react@18.2.4 -> ./../../projects/test-project/node_modules/@types/react
└── react@18.2.0 -> ./../../projects/test-project/node_modules/react

En el sistema de archivos o la interfaz IDE, las instancias vinculadas de paquetes en la carpeta node_modules de la biblioteca bajo prueba tendrán un ícono de acceso directo. si está encendido instalación de dependencia y paso de construcción Si elegiste el camino más largo, así es como se vería la carpeta node_modules:

Notas:

En algunos casos, utilice npm link No hay necesidad.
Depende de qué funciones de biblioteca se utilicen en el proyecto. Por ejemplo, si está probando una biblioteca que usa reaccionar, pero el proyecto de prueba usa solo aquellos métodos de la biblioteca que no importan nada de reaccionar: npm link no requerido.
La versión del nodo debe ser la misma en la biblioteca y en el proyecto de prueba; de lo contrario, el proyecto de prueba no verá la biblioteca npm link.
Puede verificar la versión en package.json en el campo motores.nodo. Si no existe tal campo, el proyecto utilizará la versión de nodo instalada globalmente en su computadora. Puede averiguar la versión global usando el comando node -v. Si la versión de nodo instalada globalmente es diferente de la que figura en package.json, se puede cambiar fácilmente utilizando un administrador de versiones como NVM. Puede cambiar a otra versión del nodo, que se especifica en el IDE o en el archivo .nvmrc del proyecto, usando el comando nvm use (requerido previamente instalar nvm). Este comando instala la versión requerida solo para el terminal actual.

3 – Crea un enlace global a la biblioteca.

Dentro del directorio de la biblioteca, ejecute el comando yarn link. Esto creará una referencia global que se puede utilizar en un proyecto de prueba.

Puede asegurarse de que el enlace a la biblioteca se haya creado usando los comandos:

El directorio que aparece debe contener los mismos archivos que preparó en el directorio con la biblioteca que se está desarrollando. Por ejemplo, si utilizamos el primer método de compilación para nuestra biblioteca en el paso de instalación y compilación de la dependencia, los archivos podrían ser los siguientes:

$ ls ~/.config/yarn/link/@ktsstudio/test-library
dist    node_modules    package.json    src    tsconfig.json    yarn.lock

El nombre exacto de la biblioteca se puede encontrar (o configurar para la biblioteca recién creada) en package.json en el campo “nombre”.

4 — Conexión de la biblioteca bajo prueba al proyecto

Para hacer esto, dentro del proyecto de prueba, ejecute el comando: yarn link "@ktsstudio/test-library". De esta manera obligarás a Yarn a mirar específicamente la biblioteca que se está desarrollando con los cambios necesarios.

Nota: al realizar nuevos cambios en el código de la biblioteca, deberá reconstruirlo; esto es nuevamente paso de instalar dependencias y construir la biblioteca.

Si después de esto el IDE/linter se niega a verlo en el proyecto de prueba, repita el paso actual.

5 – Pruebas

Conectar la biblioteca al proyecto es el primer paso de la prueba. Se considera aprobado si la biblioteca está conectada y sus cambios se aplican al proyecto sin errores. Por ejemplo, si los estilos de un botón se cambiaron en una biblioteca, esos estilos deberían aparecer cambiados en el proyecto en el que se utilizan.

En este artículo solo cubrimos las pruebas manuales, por lo que el resto de los pasos de prueba dependen de la biblioteca y de sus solicitudes.

Errores

En esta sección veremos algunos errores no obvios que pueden ocurrir durante el proceso de conexión de la biblioteca.

No se puede resolver 'reaccionar'/No se pueden leer las propiedades de null (leyendo 'useCallback') y otros similares. Para resolver, en la terminal de la biblioteca, ejecute:
npm link <путь до тестового проекта>/node_modules/react
Puede encontrar más información sobre este error en Reaccionar documentación.

ver error

'ErrorBoundary' no se puede utilizar como componente JSX y otros similares. Este error se produce debido a una discrepancia entre las versiones del paquete @types/react en el proyecto de prueba y en la biblioteca. Para resolver, en la terminal de la biblioteca, ejecute:

npm link <путь до тестового проекта>/node_modules/@types/react

Parece que hay varios casos de “componentes con estilo”. Este tipo de advertencia puede aparecer en la consola al probar una biblioteca que utiliza componentes con estilo bajo el capó. Para una solución intente:
1. Dentro del proyecto con la biblioteca, ejecute el comando npm link /node_modules/styled-components/
2. Reinicie el proyecto de prueba. Tal vez reinstalar las dependencias.
3. Cuando termines la prueba, no olvides desvincular el enlace: npm uninstall -g styled-components
  Más detalles sobre el error en Documentación de componentes con estilo.
Como solución general, Si algo no funciona, en tu proyecto de prueba y biblioteca prueba estos pasos:
1. Eliminar cambios en Yarn.lock: git restore yarn.lock
2. Reinstale las dependencias: rm -rf node_modules && yarn install

Cómo desvincular una biblioteca en desarrollo

Volvamos al ejemplo con la biblioteca en desarrollo @ktsstudio/test-library. Una vez completadas las pruebas, debe eliminar las referencias de la biblioteca creada para que cuando trabaje en otro proyecto, estas referencias no generen confusión ni posibles conflictos de dependencia.

Para borrar enlaces necesitas seguir estos pasos:

Si usted referencias creadas a instancias de paquetes React — dentro del directorio con la biblioteca compilada o dentro del proyecto de prueba, ejecute el comando npm uninstall -g react @types/react. Esto desacoplará React y sus tipos de la biblioteca construida. Si está probando varias bibliotecas, basta con escribir esto una vez.
Si dentro de un proyecto con una biblioteca que llamaste npm linkelimine los cambios en Yarn.lock desde allí.
Dentro del proyecto de prueba, ejecute el comando yarn unlink "@ktsstudio/test-library"
Nota: esto es necesario por si acaso: para eliminar el enlace a la biblioteca recopilada anteriormente.
Dentro del directorio de la biblioteca, ejecute yarn unlink
Esto eliminará el enlace global al paquete con la biblioteca que se está desarrollando. Puede verificar que el enlace se ha eliminado ejecutando:
- Para MacOS— ls ~/.config/yarn/link
- Para ventanas – ls ~/AppData/Local/Yarn/Data/link
- Vea el contenido del directorio raíz en la ruta adecuada. Puede haber una carpeta “@ktsstudio” en el directorio (u otro prefijo dependiendo de la biblioteca que se esté probando), pero no debería haber una carpeta con la biblioteca específica que se está desarrollando/probando (“test-library” en nuestro caso).
Dentro del proyecto de prueba hazlo yarn install --forcepara restaurar las dependencias.

Conclusión

Analizamos una forma sencilla y eficaz de probar bibliotecas en sus proyectos. Espero que nuestra solución le ayude a mejorar su experiencia de desarrollo de bibliotecas y le facilite navegar por las complejidades de las dependencias.

¿Ha encontrado algún problema al utilizar npm/yarn link? Comparte tus experiencias e ideas en los comentarios.

Otros artículos sobre React:

• Construyendo nuestra propia biblioteca para SSR en React
• Creando un editor de texto usando React.js
• Juego controlado por voz en React y Phaser
• ¿Qué hay de nuevo en reaccionar-enrutador v6?
• Reaccionar Arrastrar y Soltar: “Juego de Botellas”

Otros artículos sobre JavaScript:

• Cómo diseñar una carta para que llegue al destinatario según lo previsto
• Hoja de ruta para una interfaz moderna de KTS / Habr (habr.com)
• Personalización de VS Code para desarrollo web / Habr (habr.com)
• Lista de verificación del frontend al desarrollar un proyecto especial publicitario / Habr (habr.com)
• Cómo Yarn v3 y la filosofía Zero Installs nos ayudaron a reducir 3 veces la duración del proceso ci/cd / Habr (habr.com)