Primeros pasos con vlt, una alternativa a npm

vlt es un gestor de paquetes de JavaScript gratuito y de código abierto, creado por las mismas personas que crearon y mantuvieron npm.

vlt se convirtió en una opción seria con la publicación de la versión 1.0. Instala a partir de package.json, divide la instalación en una fase de descarga y otra de ejecución de scripts, e incluye un lenguaje de consultas para tu grafo de dependencias. Las fricciones están en los detalles: los lockfiles, la autenticación de .npmrc, los scripts de postinstall y, sobre todo, de qué registro proceden tus paquetes. Esta guía repasa todos esos aspectos sobre un proyecto existente y termina con un veredicto claro.

¿Qué es el gestor de paquetes vlt y quién lo creó?

vlt es un cliente de gestión de paquetes junto con un servicio de registro alojado, y lo han desarrollado personas que construyeron npm. El artículo de lanzamiento de noviembre de 2024, firmado por Darcy Clarke, Ruy Adorno y Luke Karrys, lo presentó como gratuito y de código abierto. vlt 1.0 se publicó el 4 de agosto de 2026, y desde entonces han seguido nuevas versiones 1.x.

La CLI de vlt resultará familiar a quienes usan npm, pero la arquitectura es distinta. Si lo estás comparando con la otra gran alternativa a npm, consulta cómo aborda pnpm los mismos problemas.

Instalar vlt y ejecutarlo en un proyecto existente

Puedes instalar vlt con el script oficial o a través de npm. Después, vlt install descarga tus dependencias y vlt build ejecuta sus scripts.

# official installer, then configure a registry and account
curl -fsSL https://install.vlt.sh | bash
vlt setup

# or install through npm
npm install -g vlt

cd your-project
vlt install   # resolve, download, extract; no dependency scripts run
vlt build     # run lifecycle scripts for eligible packages

La instalación mediante npm aparece en la guía de migración desde npm. Es necesario configurar un registro antes de que vlt install funcione. La documentación de configuración indica que vlt no incluye ningún registro predeterminado, y cualquier comando que necesite acceder a un registro se detiene con un error de configuración hasta que definas uno.

Trabajarás con dos archivos en la raíz del proyecto:

• vlt.json: configuración del proyecto, que sustituye a .npmrc.
• vlt-lock.json: el lockfile de vlt.

Según la guía de migración desde npm, vlt no lee package-lock.json, sino que lo resuelve todo desde cero. Puedes eliminar el lockfile antiguo o conservarlo mientras ambas herramientas conviven. Este enfoque es menos suave que la importación de lockfiles de pnpm, que se explica en cambiar de npm a pnpm. Compara las versiones resueltas antes de fusionar cualquier cambio.

¿Es vlt un sustituto directo?

Trata lo de «sustituto directo» como algo que debes comprobar, no como algo que se da por hecho. El artículo de lanzamiento de 2024 afirmaba que vlt podía reemplazar a tu gestor de paquetes actual «en la mayoría de los casos». El artículo de la versión 1.0 va más allá y describe el cliente como un sustituto directo (drop-in replacement) de npm. Ambas afirmaciones proceden del propio fabricante. Revisa estas cinco áreas en tu proyecto:

1. Configuración de .npmrc. La documentación no indica que vlt lea .npmrc. La configuración de registros y scopes va en vlt.json, bajo scoped-registries. Los tokens de autenticación se guardan en el archivo de keychain de vlt o en variables de entorno VLT_TOKEN, tal como se describe en la guía de migración desde npm. Los scopes privados suelen ser lo primero que falla en una migración.
2. Paquetes con scripts de instalación. Los addons nativos y los paquetes que descargan un binario no funcionarán hasta que se ejecute vlt build (ver más abajo).
3. Peer dependencies. La documentación de instalación indica que vlt intenta mantener una sola copia de cada peer dependency. Si dos partes del árbol necesitan versiones de un peer que no pueden coexistir, vlt asigna a cada parte su propio contexto de peers. Los árboles que fallan con el error ERESOLVE de npm pueden resolverse con vlt, posiblemente con más de una copia del peer.
4. Workspaces. Los monorepos tienen una página específica en la documentación de vlt. Comprueba tu estructura frente a ella.
5. CI. Usa vlt ci seguido de vlt build.

Una regresión provocada por el cambio de gestor de paquetes puede superar la CI y manifestarse por primera vez en producción. Una versión transitiva distinta, o un postinstall omitido que debía generar un archivo, puede aparecer como un error en tiempo de ejecución en el navegador. El session replay con captura de consola y de red vincula ese error con el despliegue que modificó el lockfile.

El registro: de dónde proceden tus paquetes

El cliente de vlt no tiene un registro predeterminado; tú eliges uno. La documentación de registros indica que los comandos de instalación (vlt install, vlt ci, vlx y otros) requieren que esté definido el alias de registro npm. Para ellos no basta con un valor registry simple en vlt.json, en un flag o en VLT_REGISTRY. La alternativa es vlt setup, que configura los registros de tu cuenta de vlt.io.

Ejecutar vlt setup cambia el origen de tus paquetes: apunta el alias npm al mirror de tu cuenta en el registro de vlt. La página principal de vlt indica que cada solicitud de un paquete público pasa por una comprobación de seguridad en ese mirror, que bloquea el malware conocido. Tu raíz de confianza pasa de npm a vlt.

Para usar directamente el registro público de npm, ejecuta:

vlt config set registries=npm=https://registry.npmjs.org/

Si lo ejecutas dentro del proyecto, el alias se escribe en el vlt.json del proyecto. Haz commit de ese archivo para que todo el equipo y la CI utilicen el mismo origen.

Una advertencia: una incidencia abierta en abril de 2026 informa de que vlt install sigue usando las URL de registro registradas en un vlt-lock.json existente. Si cambias de registro, regenera el lockfile.

El bloqueo en el registro solo detiene el malware que ya ha sido identificado. Una versión maliciosa recién publicada puede colarse hasta que alguien la detecte. Los equipos que necesiten alojamiento privado también pueden autoalojar vsr, el registro compatible con npm y con licencia Fair Source de vlt, que el artículo de lanzamiento ofrece para uso local, autoalojado o gestionado.

Valores de seguridad predeterminados: instalaciones por fases y vlt build

vlt install no ejecuta ningún script de las dependencias. Después, vlt build ejecuta los scripts de ciclo de vida de todos los paquetes que los tengan, salvo los que presenten alertas de malware conocidas, a menos que acotes el objetivo con un selector. La documentación de build establece como objetivo predeterminado:

:scripts:not(:built):not(:malware)

No hay ningún aviso de aprobación. Los scripts se aprueban escribiendo una consulta más restrictiva en Dependency Selector Syntax. Pásala como objetivo de build, o usa --allow-scripts en la instalación, y guárdala en vlt.json para que todo el equipo use la misma. El anuncio de vlt build explica el modelo en detalle.

En la práctica, las instalaciones por fases implican que un paquete que necesita un script de postinstall para descargar un binario precompilado o compilar un addon nativo no queda construido tras vlt install. Todo lo que dependa de su binario o de sus archivos generados puede fallar hasta que se ejecute vlt build. Incluye vlt build en todos los scripts de configuración y en todos los jobs de CI.

La idea coincide con desactivar por defecto los scripts de instalación de npm. Sin embargo, los controles del lado del consumidor solo protegen las instalaciones. En el lado de la publicación, revisa el contenido de los paquetes con npm pack --dry-run para no publicar archivos por error.

Consultas al grafo de dependencias con vlt query

vlt query selecciona paquetes de tu grafo de dependencias resuelto mediante selectores al estilo CSS, de forma muy parecida a como querySelectorAll selecciona elementos de una página. El artículo de la versión 1.0 menciona más de 60 pseudoselectores de grafo, unos 30 de ellos centrados en la seguridad. El artículo de vlt sobre los selectores de insights indica que los selectores de seguridad utilizan metadatos de Socket.

vlt query ':scripts'                  # packages with install scripts
vlt query ':malware'                  # packages with known malware alerts
vlt query ':prod'                     # production dependencies only
vlt query ':scripts' --view=mermaid   # render matches as a Mermaid diagram

La documentación de query enumera los modos de salida: human, json, mermaid, svg, png y count. Empieza con :scripts, porque esa es la lista de la que vlt build elige por defecto (y después omite los paquetes ya construidos y los que tienen alertas de malware). Según el artículo de vlt sobre host context, :host(local) ejecuta una consulta sobre todos los proyectos configurados en el dashboard de vlt.

Los mismos selectores funcionan en la CI:

- run: npm install -g vlt
- run: vlt ci          # vlt install --expect-lockfile
- run: vlt build
- name: Report dependencies with malware alerts
  run: vlt query ':malware' --view=count

Para que ese último paso haga fallar el job, añade --expect-results=0, tal como describe la documentación de query. La consulta es la misma en todas partes: es tu política, almacenada como una única cadena de selector.

Veredicto: vale la pena en un proyecto secundario, pero aún no como opción predeterminada

Merece la pena probar vlt ya en un proyecto secundario. Un equipo en producción debería mantener su gestor de paquetes actual hasta que su CI, la autenticación con registros privados y los paquetes con scripts de instalación funcionen sin problemas con vlt. Las instalaciones por fases y vlt query son útiles. La resolución del lockfile desde cero y la elección del registro requieren una decisión meditada. Si lo que más te importa es la velocidad de instalación, compáralo con la reescritura en Rust de pnpm 12 en tu propio repositorio.

Empieza en una rama. Define explícitamente el alias de registro npm, ejecuta vlt install, vlt build y vlt query ':scripts', y compara las versiones resueltas en vlt-lock.json con tu lockfile anterior antes de que nada llegue a main.

Preguntas frecuentes

¿Qué versión de Node.js requiere vlt? ¿Sigue creando una carpeta node_modules?

El paquete vlt requiere Node.js 22.22 o posterior. vlt sigue generando un directorio node_modules, pero utiliza su propia estructura interna en node_modules/.vlt/, distinta del árbol plano de npm. Por defecto, vlt crea hard links a los archivos desde un almacén global en Linux y desempaqueta cada paquete en macOS y Windows; la opción store-linker modifica este comportamiento. Los paquetes se siguen resolviendo con normalidad en tiempo de ejecución, por lo que el código de tu aplicación no debería necesitar cambios.

¿Qué sustituye a npx y a npm run al usar vlt?

vlt exec sustituye a npx. También puedes invocarlo como vlt x o con el atajo vlx. Ejecuta el binario de un paquete y descarga el paquete si no está en node_modules, pidiendo confirmación antes de obtener cualquier cosa nueva. vlxl solo ejecuta binarios que ya están instalados. vlt run, abreviado como vlr, ejecuta los scripts de package.json con sus hooks pre y post. Ambos aceptan un selector --scope para apuntar a workspaces concretos.

¿Cómo migro los overrides de npm a vlt?

El equivalente en vlt del campo overrides de npm son los Graph Modifiers. Se definen en vlt.json y se escriben como consultas en Dependency Selector Syntax. Esto te permite apuntar a una dependencia por ruta, workspace o rango semver, y no solo por nombre de paquete. Cuando varios modificadores coinciden con la misma dependencia, vlt aplica reglas de especificidad similares a las de CSS para decidir cuál prevalece.

¿Cómo configuro los workspaces en un monorepo con vlt?

vlt lee tal cual el campo workspaces del package.json raíz, por lo que un monorepo existente de npm o yarn funciona sin cambios. Usa el campo workspaces del vlt.json raíz cuando quieras grupos con nombre o estés migrando desde pnpm-workspace.yaml. Si vlt.json tiene un campo workspaces, vlt utiliza solo ese e ignora el de package.json; ambos no se combinan. En vlt.json, el valor puede ser una cadena glob, un array de globs como packages/* o un objeto de grupos con nombre, cada uno asociado a rutas o globs. Un array simple se asigna al grupo predeterminado, llamado packages.