¿Por qué mi comando no funciona?

Cuando empezamos a usar npm/pnpm/yarn para instalar dependencias en nuestros proyectos, descubrimos que también podemos instalar paquetes que nos habilitan comandos que podemos usar desde la terminal.

Uno de los primeros problemas con que nos chocamos al empezar a experimentar con estos comandos, es cuando intentamos usar un comando de un paquete local. O sea, un paquete que instalamos dentro de un proyecto.

Para entender porque no funciona el comando cuando intentamos ejecutarlo directamente desde la terminal, y si desde el script del package, hay que entender como funciona el tema de los comandos en la terminal.

¿Cómo funcionan los comandos?

Cuando ejecutamos un comando como:

1ls
2node index.js
3npm install
4pnpm add

Cada uno de esos comandos (ls, node, npm, pnpm) es un archivo ejecutable que está en algún lugar de nuestra computadora. Para saber donde están ubicados podemos usar el comando which.

El sistema operativo usa una variable de entorno llamada PATH, para tener un listado de ubicaciones donde buscar comandos. Podemos ver el contenido de esta variable de entorno usando el comando echo.

Entonces, cuando ejecutamos un comando como:

1node index.js

El sistema operativo se fija dentro de todas las ubicaciones del PATH, para ver si existe un archivo ejecutable que se llame node.

Podemos verificar que la ubicación del comando node está dentro del path.

Paquetes globales

Cuando instalamos un paquete "ejecutable" de forma global con la opción --global, este se instala en una ubicación que forma parte del PATH.

Lo que permite ejecutar el comando sin importar en donde estemos ubicados en ese momento en la terminal.

Paquetes locales

Cuando instalamos un paquete local, o sea un paquete que pertenece a ese proyecto en particular.

1pnpm add tsx
2# ó
3npm install tsx

El paquete se instala en la carpeta node_modules de ese proyecto, que no se encuentra en el PATH. Y en el caso de los paquetes que habilitan comandos (o sea ejecutables), esos ejecutables se ubican en una carpeta nombrada .bin dentro de node_modules.

Esta carpeta no está en el PATH, por lo que, al intentar ejecutar el comando, obtenemos un error. Para poder usar este ejecutable, debemos recurrir a alguno de los métodos pensados para esto.

Script

Uno de los métodos más usados es usar un script dentro del package.json. Cuando ejecutamos un script del package este incluye la ubicación node_modules/.bin temporalmente dentro del PATH.

pnpm exec

PNPM incluye el sub-comando exec, que busca dentro de node_modules/.bin el ejecutable que intentamos usar.

npx

npx es un comando que viene con npm y nos permite llamar a paquetes ejecutables que estén en nuestro proyecto (node_modules/.bin) y si no lo encuentra, lo descarga temporalmente en otra ubicación y lo ejecuta.

Esta opción es muy utilizada, pero prefiero usarla solo cuando necesito ese comando temporalmente. Cuando quiero que mi proyecto tenga disponible ese comando para siempre, prefiero instalarlo como dependencia y llamarlo desde un script.