Evaluar Deno para un proyecto Node.js: checklist de compatibilidad

Deno 2 salió en octubre de 2024 con un soporte mucho mejor para Node.js y npm, y la línea 2.x siguió cerrando brechas desde entonces. Mejor soporte no es lo mismo que comportamiento idéntico. Si tenés un proyecto en Node.js y estás pensando en pasarlo a Deno, este checklist te ayuda a descubrir qué se rompería antes de comprometerte con el cambio.

Dónde está Deno hoy

Al momento de escribir esto, la versión mayor actual es Deno 2: la última versión publicada en la página de releases del proyecto en GitHub es la 2.9.7, de septiembre de 2026. Revisá esa página para saber contra qué versión vas a probar en la práctica, porque las notas de compatibilidad de la documentación están atadas a versiones menores específicas.

La propia página de compatibilidad de Deno es directa sobre la situación. Dice que la mayoría de los paquetes de npm escritos en JavaScript puro funcionan sin cambios y que, desde Deno 2.8, más del 75% de la suite de pruebas de Node pasa en Deno. También enumera los límites: algunas API son parciales, los paquetes con complementos nativos necesitan un directorio node_modules local y algunas herramientas suponen la estructura exacta de archivos en disco de npm.

Es un buen punto de partida, y también la razón para probar en lugar de suponer. Un proyecto es tan compatible como su dependencia menos compatible.

Definí por qué estás evaluando Deno

Escribí el motivo antes de empezar. Los más comunes:

• Querés el sistema de permisos integrado, para que los scripts no puedan leer archivos ni acceder a la red salvo que se lo permitas.
• Querés las herramientas integradas (formateador, linter, ejecutor de pruebas, TypeScript sin un paso de compilación aparte) en lugar de armarlas vos.
• Arranca un servicio nuevo y estás eligiendo un runtime, en lugar de migrar uno existente.

Si el motivo es difuso, cuesta justificar el costo de una migración. Un servicio nuevo y chico es una prueba mucho más barata que mover tu aplicación principal.

Checklist 1: dependencias

Empezá por acá, porque es donde aparecen la mayoría de las sorpresas.

• Hacé una lista de cada dependencia directa en package.json y anotá cuáles incluyen código nativo. Deno soporta complementos nativos de Node-API, pero solo cuando existe un directorio node_modules local y se otorga el permiso --allow-ffi.
• Buscá los paquetes que dependen de scripts de instalación. Deno no ejecuta por defecto scripts de ciclo de vida como postinstall. Los habilitás paquete por paquete, por ejemplo deno install --allow-scripts=npm:duckdb, o los aprobás de forma interactiva con deno approve-scripts. Sin esto, los paquetes que compilan código nativo al instalarse fallan en tiempo de ejecución.
• Buscá las herramientas que suponen la estructura exacta de carpetas de npm: algunos bundlers, generadores de código y plugins que recorren node_modules directamente.
• Fijate si usás un registro privado. Deno lee la configuración del registro desde .npmrc, incluidos los tokens de autenticación.
• Buscá paquetes que solo existen en CommonJS y archivos .js propios escritos en CommonJS. Deno soporta CommonJS en archivos .cjs y en archivos .js dentro de un paquete marcado con "type": "commonjs", pero no detecta CommonJS a partir del contenido del archivo salvo que pases --unstable-detect-cjs.

Checklist 2: API integradas de Node

La referencia de API de Node de Deno enumera cada módulo node: con un estado. Al momento de la revisión, 16 de 44 módulos figuraban con soporte parcial y 6 sin soporte.

• Sin soporte: cluster, domain, repl, sea, trace_events, wasi. Si tu aplicación crea procesos de trabajo con node:cluster, planificá otra forma de hacerlo; la documentación dice que sus exportaciones son stubs que no funcionan.
• Con soporte parcial están http, http2, https, net, tls, dns, vm, worker_threads, zlib, inspector y otros. "Parcial" puede significar un único método que no usás o algo de lo que depende tu aplicación, así que leé las notas de cada módulo que importás.

Buscá en tu código y en el de tus dependencias los imports node: y los nombres de módulos integrados sin prefijo, y compará con la lista:

grep -rhoE "from ['\"](node:)?(cluster|domain|repl|trace_events|wasi|http2|vm|worker_threads|inspector)['\"]" src/ | sort | uniq -c

Esto solo encuentra tu propio código. Las dependencias conviene probarlas ejecutándolas.

Checklist 3: globales y comportamiento en tiempo de ejecución

• process está disponible en todos lados, pero Buffer hay que importarlo desde node:buffer.
• __dirname y __filename se reemplazan por import.meta.dirname e import.meta.filename. El código que los lee en módulos ES necesita actualizarse.
• Los paquetes de npm corren bajo el sistema de permisos de Deno. Un paquete que escribe archivos temporales o lee variables de entorno necesita que se le otorguen esos permisos. Definí qué permisos necesita realmente cada punto de entrada, en lugar de otorgar todo para sacarte los errores de encima, porque eso elimina el principal beneficio de seguridad.
• Los scripts de package.json se ejecutan con deno task, de forma parecida a npm run. Los scripts que llaman a node directamente siguen ejecutando el binario de Node, así que en realidad no están probando Deno.

Checklist 4: compilación, pruebas y despliegue

• Definí cómo se maneja node_modules. La opción nodeModulesDir en deno.json acepta "none", "auto" y "manual". Los complementos nativos y las herramientas sensibles a la estructura de carpetas necesitan un directorio local.
• Corré tu suite de pruebas actual bajo Deno. Si depende de un ejecutor de pruebas específico de Node, reservá tiempo para adaptarla o para hacerla correr.
• Revisá tu hosting. Tu plataforma tiene que soportar la versión de Deno con la que probás, o permitirte usar tu propia imagen de contenedor.
• Revisá la observabilidad: los agentes de logs, de seguimiento de errores y de APM suelen modificar partes internas de Node y pueden depender de módulos con soporte parcial.
• Mantené funcionando la compilación para Node.js hasta que Deno lleve un tiempo corriendo en producción. Volver atrás tendría que ser un cambio de configuración, no un proyecto.

Una tabla de decisión

Cómo hacer la prueba

1. Elegí un servicio o script con buena cobertura de pruebas.
2. Creá una rama, agregá un deno.json y corré deno install sobre el package.json existente.
3. Arrancá sin permisos y agregalos de a uno a medida que aparecen errores. La lista resultante documenta lo que el código realmente toca.
4. Corré la suite de pruebas y la aplicación con una carga realista, en el mismo tipo de máquina donde desplegás.
5. Anotá cada solución alternativa que tengas que aplicar. Si la lista es larga, esa es tu respuesta por ahora.

Volvé a revisar el resultado cuando salga una nueva versión menor de Deno, porque las notas de compatibilidad cambian entre versiones.

Dónde entra automotif

La mayoría de las empresas con las que trabajamos no necesitan cambiar de runtime. Cuando Deno aparece, suele ser para un script o servicio chico que está entre otras herramientas, y eso entra en desarrollo de automatizaciones: podemos ayudarte a decidir si una tarea determinada va en n8n, Make o Zapier, o necesita un poco de código, y en qué runtime. Para hablar de un caso concreto, reservá una llamada gratis de 30 a 60 minutos.

Fuentes

• Node and npm Compatibility (Deno Docs)
• Node APIs (Deno Docs)
• Releases (denoland/deno on GitHub)
• Announcing Deno 2 (Deno blog)