Cuando trabajamos en el entorno de desarrollo y usamos varios paquetes de Node.js que dependen entre sí, puede ser tedioso publicar cada cambio para probarlos juntos. El proceso es largo: hacer el cambio, hacer un commit, crear una nueva versión, usar la nueva versión en el proyecto, etc. Si sólo queremos usar la nueva versión temporalmente, con npm link podemos hacerlo rápidamente. Este comando nos permite vincular paquetes de manera local usando enlaces simbólicos.

Veamos cómo funciona en la práctica.

¿Qué hace realmente npm link?

Como ya hemos dicho, npm link crea un acceso directo (enlace simbólico) entre dos paquetes Node.js locales. Así, cuando importamos un paquete en nuestro proyecto, Node.js lo carga desde el directorio local que enlazamos, en lugar de buscarlo en el registro de npm o en la carpeta node_modules estándar.

Esto nos permite trabajar en varios proyectos a la vez —por ejemplo, una librería y una aplicación que la usa— sin tener que instalar, desinstalar ni publicar nada.

Caso práctico: librería y aplicación

Imaginemos que estamos desarrollando una librería llamada mi-lib y una aplicación llamada mi-app que la utiliza. Queremos probar cambios en mi-lib directamente desde mi-app.

Estructura de directorios:

/proyectos/
├── mi-lib/
│   └── package.json
└── mi-app/
    └── package.json

Contenido de los package.json:

mi-lib/package.json

{
  "name": "mi-lib",
  "version": "1.0.0",
  "main": "index.js"
}

mi-app/package.json

{
  "name": "mi-app",
  "version": "1.0.0",
  "dependencies": {
    "mi-lib": "^1.0.0"
  }
}

Supongamos que mi-lib/index.js tiene una función JavaScript simple:

export default function() {
  console.log('Hola desde mi-lib');
};

Queremos que cuando corramos mi-app, use la versión local de mi-lib —sin necesidad de publicarla.

Paso a paso con npm link

1. Vinculamos la librería globalmente
   Desde el directorio de mi-lib, ejecutamos:

   cd /proyectos/mi-lib
   npm link

   Esto crea un enlace simbólico global a mi-lib. En sistemas UNIX, lo encontraremos en algo como /usr/local/lib/node_modules/mi-lib.

2. Enlazamos la librería a la app
   Luego, en el directorio de mi-app, ejecutamos:

   cd /proyectos/mi-app
   npm link mi-lib

   Este comando crea un enlace simbólico dentro de mi-app/node_modules/mi-lib apuntando a nuestra versión local.

3. Verificamos el enlace
   Si listamos la carpeta node_modules de mi-app con el comando ls -lah:

   /proyectos/mi-app/node_modules/
   └── mi-lib -> /proyectos/mi-lib/

   El archivo node_modules/mi-lib no es una copia, es un acceso directo al código fuente de mi-lib. Así, cualquier cambio que hagamos en la librería se refleja de inmediato en la app.

4. Probamos la integración
   En mi-app/index.js podemos importar la librería:

   import miLib from 'mi-lib'
   miLib();

   Si ejecutamos la app:

   node index.js

   Veremos en consola:

   Hola desde mi-lib

   Ahora, si editamos mi-lib/index.js para que imprima otra cosa, los cambios se reflejan al instante al volver a ejecutar la app.

¿Y para deshacer el enlace?

Cuando terminamos de trabajar localmente, podemos revertir los enlaces simbólicos fácilmente:

• Desde mi-app:

  npm unlink mi-lib

• Opcionalmente, también desde mi-lib:

  npm unlink

Esto restablece las dependencias a su estado original. Es útil para evitar conflictos si luego queremos usar versiones publicadas.

Resumen

npm link es una herramienta que usamos para vincular paquetes locales durante el desarrollo sin pasar por el registro de npm. Nos permite trabajar más cómodos y con menos fricción cuando estamos creando y probando bibliotecas, herramientas CLI u otros componentes.

No es una solución permanente para la instalación de dependencias, pero nos ahorra tiempo valioso mientras escribimos y probamos código. En definitiva, nos da control y flexibilidad en un proceso que de otra forma sería más lento y propenso a errores.