Deno
Propósito
Proporcionar configuraciones predeterminadas portables para proyectos modernos de Deno, especialmente cuando el código base combina Deno con herramientas orientadas a Node, necesita una ruta de migración limpia desde patrones antiguos de Deno, o está adoptando Deno en un repositorio TypeScript o Node existente.
Cuándo usar esta habilidad
- Escribir scripts, servidores o código de borde con Deno.
- Configurar
deno.json, tareas y fuentes de dependencia. - Adaptar
tsconfig.jsonoeslint.config.*existentes para coexistir con Deno. - Mezclar código Deno con código Node o TypeScript en un solo repositorio.
- Revisar permisos, pruebas o patrones de tiempo de ejecución de Deno.
Valores predeterminados
- Usar
deno.jsoncomo la fuente de verdad de Deno. - Preferir
deno check,deno task,deno fmt,deno lintydeno testsobre envoltorios ad hoc cuando Deno es el propietario del flujo de trabajo. - Las herramientas nativas de Deno son suficientes para el código propiedad de Deno; usar Yarn solo cuando el repositorio también tenga paquetes o scripts gestionados por Node fuera del límite de Deno.
- Mantener
tsconfig.jsonsolo para rutas propiedad de Node o para casos de gráfico de proyecto TypeScript que los espacios de trabajo y ámbitos de directorio de Deno no puedan expresar limpiamente. - Recordar que el Node moderno también ejecuta TypeScript directamente a través de la eliminación de tipos incorporada; elegir Deno por su modelo de tiempo de ejecución, permisos, dependencias y herramientas, no solo para evitar
tscots-node. - Preferir
deno lintydeno fmtpara archivos propiedad de Deno; agregar ESLint solo cuando el repositorio o el editor realmente necesiten el ecosistema de ESLint. - Al reemplazar ESLint con
deno lint, inspeccionar y trasladar la intención existente de ESLint a las inclusiones, exclusiones, reglas de lint o excepciones documentadas dedeno.jsonen lugar de descartar la configuración por completo. - Al reemplazar
tsccondeno check, inspeccionar eltsconfig.jsonexistente y traducir las opciones del compilador, inclusiones, exclusiones, bibliotecas y expectativas de rigor relevantes adeno.jsono untsconfig.jsonretenido con ámbito claro. - Cuando herramientas de editor respaldadas por npm, como ESLint, deban ejecutarse dentro de un repositorio Deno, configurar
nodeModulesDir: "auto"y envolver el comando endeno task. - Cuando Deno sea el propietario de la gestión de dependencias, instalar dependencias con
deno add, no tratardeno run npm:<paquete>como un sustituto de la instalación. Usardeno add --dev npm:<paquete>para CLI y herramientas de solo desarrollo. - Para herramientas CLI instaladas, nombrar la
deno tasksegún la herramienta e invocar el binario instalado por nombre; por ejemplo, después dedeno add --dev npm:herramienta-ejemplo, agregar"herramienta-ejemplo": "herramienta-ejemplo". - Preferir módulos
.tspor defecto en el código propiedad de Deno; no recurrir a JavaScript solo para evitar un paso de compilación que Deno no requiere. - Preferir paquetes JSR, especificadores
npm:o entradas de mapa de importación explícitas sobre importaciones de URL heredadas dispersas. - Cuando una CLI respaldada por npm tenga un comportamiento de instalación o postinstalación que no coopere limpiamente con la ejecución única, preferir
nodeModulesDir: "auto", permitir el paquete enallowScripts, agregar la dependencia condeno addodeno add --dev, e invocar el binario instalado desde unadeno task. - Deno 2 es intencionalmente compatible con
package.json, paquetes npm y módulos integrados de Node; mantener la configuración específica de Deno endeno.jsonen lugar de intentar quetsconfig.jsonmaneje ambos mundos. - Preferir APIs estándar web y
Deno.servepara servidores. - Tratar los permisos como una decisión de diseño, no como una ocurrencia tardía.
Encuadre de tareas
| Comando o acción | Qué | Por qué | Cuándo | Resultado esperado |
|---|---|---|---|---|
Adoptar tsconfig.json y ESLint cuidadosamente | Decidir qué permanece en la configuración propiedad de Node y qué se mueve a deno.json. | Los repositorios híbridos se vuelven ruidosos rápidamente cuando ambos conjuntos de herramientas intentan ser propietarios de los mismos archivos. | Al introducir Deno en un código base TypeScript o Node existente. | Las herramientas de Deno y Node tienen límites de propiedad explícitos. |
Configurar deno.json | Definir tareas, opciones del compilador y convenciones de dependencia en el archivo de configuración de Deno. | Deno debe ser propietario de su propio flujo de trabajo en lugar de tomar prestada la configuración céntrica en Node por accidente. | Al iniciar o reestructurar un proyecto Deno. | Los comandos de Deno y el comportamiento del editor son consistentes. |
| Instalar una CLI npm propiedad de Deno | Ejecutar deno add --dev npm:<paquete> para herramientas de desarrollo, luego agregar una tarea con el mismo nombre que invoque el binario instalado. | La dependencia, el archivo de bloqueo, el binario local y el punto de entrada de la tarea se mantienen alineados bajo el administrador de paquetes de Deno. | Al agregar herramientas como generadores de código, CLI de automatización de navegadores, linters o formateadores a un flujo de trabajo propiedad de Deno. | deno.json y el archivo de bloqueo registran la dependencia, y deno task <herramienta> ejecuta la CLI instalada. |
| Establecer límites híbridos | Separar las rutas propiedad de Deno de las rutas propiedad de Node en repositorios mixtos. | Los conflictos de herramientas son una de las fallas más comunes en repositorios híbridos. | Cuando el código Deno coexiste con herramientas Node o TS. | Los editores y comandos no compiten por los mismos archivos. |
| Revisar permisos | Elegir banderas --allow-* explícitas o conjuntos de permisos nombrados para el acceso en tiempo de ejecución. | El modelo de seguridad de Deno solo ayuda cuando los permisos son deliberados. | Antes de ejecutar nuevos scripts o exponer un flujo de trabajo CLI de Deno. | El acceso al sistema de archivos, red y entorno es intencional y auditable. |
| Solucionar problemas de flujos de trabajo Deno | Usar comprobaciones nativas de Deno, banderas de depuración y herramientas de gráfico de módulos antes de adivinar. | Muchos problemas de Deno son de configuración, permisos o propiedad, no errores de código. | Cuando un repositorio híbrido o un conjunto de herramientas migrado se comporta inesperadamente. | La causa raíz se reduce a configuración, permisos o comportamiento en tiempo de ejecución. |
Reglas principales
TypeScript, tsconfig.json y bibliotecas
- Colocar la configuración del compilador de Deno en
deno.jsonbajocompilerOptions; no copiar untsconfig.jsoncompleto de Node solo para quedeno checkfuncione. - Los espacios de trabajo existentes de Node más TypeScript pueden mantener
tsconfig.json; Deno lo explora cuando un directorio también contienedeno.jsonopackage.json. - Si un
deno.jsonpadre definecompilerOptions, estas tienen prioridad sobre las opciones superpuestas detsconfig.json. - Si el objetivo es reemplazar
tsc, primero inventariar el comportamiento actual detsconfig.json. Preservar las decisiones significativas de rigor, resolución de módulos, JSX, bibliotecas, inclusiones y exclusiones en la configuración de Deno o documentar por qué ya no aplican. - Usar
compilerOptions.libendeno.jsonpara modelar la superficie de tiempo de ejecución real. Para SSR o código de navegador más Deno, preferir combinaciones como["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]; para workers de Deno, preferir["deno.worker"]. - Usar
compilerOptions.checkJs,// @ts-check,@ts-types,@ts-self-typesocompilerOptions.typescuando los módulos JavaScript necesiten verificación de tipos o declaraciones explícitas. - Mantener
tsconfig.jsonsolo cuando las carpetas propiedad de Node, las referencias de proyecto TS o la granularidad de inclusiones o exclusiones aún lo requieran.
Linting, formateo y ESLint
- Usar
deno linty la secciónlintendeno.jsoncomo el propietario de linting predeterminado para el código propiedad de Deno. - Usar
deno fmty la secciónfmtendeno.jsoncomo el formateador predeterminado para el código propiedad de Deno. deno lintya cubre un conjunto de reglas recomendado inspirado en ESLint; no mantener ESLint solo por costumbre.- Si el objetivo es reemplazar ESLint, primero inventariar el comportamiento actual de
eslint.config.*. Preservar los ámbitos de archivo, globales, ignorados y la intención de las reglas significativas en la configuración de lint/fmt de Deno o documentar qué reglas se descartan intencionalmente porque Deno ya las cubre o rechaza. - Si se requieren reglas personalizadas solo para Deno, considerar
lint.plugins; notar que la API de complementos de lint es experimental y requiere Deno 2.2 o más reciente. - Si el repositorio o el editor aún necesitan ESLint, convertirlo en una herramienta secundaria explícita: configurar
nodeModulesDir: "auto", creareslint.config.jsy envolver la invocación endeno task, por ejemplodeno task eslint. - Mantener un propietario de lint por conjunto de archivos siempre que sea posible. Si tanto
deno lintcomo ESLint se ejecutan en los mismos archivos, documentar por qué o esperar diagnósticos duplicados y conflictivos.
Compatibilidad con Node y repositorios híbridos
- Deno 2 entiende
package.json,node_modules, espacios de trabajo npm y módulos integrados de Node; los repositorios híbridos son una ruta compatible, no una solución alternativa. - El Node moderno también puede ejecutar TypeScript directamente. En repositorios híbridos, decidir la propiedad Node versus Deno según permisos, modelo de dependencias, ejecutor de tareas y destino de implementación, no solo por la ejecución de TypeScript.
- Si existe un
package.jsony se desea que Deno cree y actualice automáticamentenode_modules, configurarnodeModulesDir: "auto". Conpackage.json, Deno 2 por defecto usa"manual". nodeModulesDires una configuración a nivel de raíz del espacio de trabajo; no intentar configurarlo por miembro del espacio de trabajo.- Usar
deno installodeno addcuando Deno sea el propietario del flujo de actualización de dependencias. No asumir el comportamiento de instalación automática de Deno 1. - Usar
deno add --dev npm:<paquete>para CLI npm de solo desarrollo en repositorios propiedad de Deno. Después de agregarlo, exponer el binario a través de unadeno taskcomo"herramienta-ejemplo": "herramienta-ejemplo"en lugar de"herramienta-ejemplo": "deno run -A npm:herramienta-ejemplo". - Registrar en el repositorio las actualizaciones del manifiesto y el archivo de bloqueo producidas por
deno add; un alias de tarea solo no es una instalación de dependencia. - No habilitar el conjunto de herramientas de Deno para todo un espacio de trabajo mixto si solo un subárbol es Deno.
- Preferir la activación del editor basada en rutas como
deno.enablePathspara que las herramientas de Node y Deno no compitan por los mismos archivos. - Mantener el límite de Deno explícito en la estructura de carpetas, tareas y documentación.
Permisos, entorno y seguridad
- Preferir banderas
--allow-*estrechas o conjuntos de permisos nombrados endeno.jsonsobre-A. - Usar
-Po--permission-set=<nombre>cuando el repositorio defina conjuntos de permisos endeno.json. - Usar
--env-filecuando la CLI deba cargar archivos.env, o@std/dotenvcuando el programa mismo necesite cargarlos; ambos aún necesitan permisos explícitos de entorno y archivos. - Preferir el mínimo privilegio para el código de aplicación y mantener el acceso al entorno, sistema de archivos, red y subprocesos obvio en tareas y ejemplos.
- Tratar
--allow-runy--allow-fficomo puertas de escape de la zona de pruebas. Evitar--allow-run=denoa menos que se intente explícitamente la confianza total. - Para depuración o auditoría de permisos, usar
DENO_TRACE_PERMISSIONS=1yDENO_AUDIT_PERMISSIONS=<ruta>.
Resolución de problemas y migración
- Recurrir a
deno check,deno check --allodeno run --checkcuando el éxito en tiempo de ejecución y el comportamiento de verificación de tipos diverjan. - Usar
deno info <punto_de_entrada>para inspeccionar el gráfico de módulos y comprender el comportamiento de importación, caché y permisos. - Usar
deno lint --fixpara la limpieza de migración común antes de editar manualmente cada problema de lint. - Para la configuración del depurador, usar
--inspect-brkcuando el proceso sea de corta duración,--log-level=debugcuando el inspector o la resolución de módulos sea confusa, y--strace-opscuando el tiempo de ejecución se esté colgando o sea inesperadamente lento. - Usar banderas de perfilado de CPU como
--cpu-prof,--cpu-prof-mdo--cpu-prof-flamegraphcuando la pregunta de resolución de problemas sea realmente sobre rendimiento. - Los consejos de migración deben reflejar los valores predeterminados de Deno 2:
nodeModulesDirahora usa"none" | "auto" | "manual",deno cachese convirtió endeno install --entrypoint,deno vendorse convirtió en"vendor": true,Deno.run()debe convertirse ennew Deno.Command(), yDeno.serveHttp()debe convertirse enDeno.serve(). - Usar atributos de importación como
with { type: "json" }en lugar de aserciones de importación obsoletas.
Errores comunes
- Si las herramientas de Deno y Node reclaman los mismos archivos, los diagnósticos del editor se vuelven ruidosos y engañosos.
- Si existe
package.json, Deno 2 establecenodeModulesDiren"manual"por defecto; olvidar esto es una razón común por la que las herramientas respaldadas por npm parecen medio instaladas. - Si la extensión ESLint de VS Code es parte del flujo de trabajo, no resolverá paquetes solo desde la caché global de Deno; necesita un directorio
node_moduleslocal. deno runomite la verificación de tipos por defecto, por lo que una ejecución exitosa no es evidencia de quedeno checkpasará.- Una
deno taskque ejecutadeno run npm:<paquete>es un atajo de ejecución única, no una instalación de dependencia adecuada. No usarlo como la respuesta predeterminada a "instalar y configurar esta CLI" en un repositorio propiedad de Deno. -Aes aceptable para herramientas de confianza, pero es el valor predeterminado incorrecto para el código de aplicación ordinario.- Algunas CLI npm, incluyendo Supabase en repositorios reales de tiempo de ejecución mixto, dependen de comportamiento en tiempo de instalación que puede ser menos confiable a través de
deno run npm:...que a través de un binario instalado bajonode_modules. - Los patrones antiguos de importación de URL y activación de todo el espacio de trabajo son ayudas de transición, no valores predeterminados modernos.
Validación
deno.jsones propietario de la configuración y tareas de Deno.- Cualquier
tsconfig.jsono propiedad de ESLint retenido es explícito y está limitado a los archivos correctos. - Reemplazar ESLint o
tscpreserva el comportamiento útil de la configuración existente o documenta por qué se descartó intencionalmente. - Las partes de Deno y Node de un repositorio híbrido no compiten por las herramientas.
- Los especificadores de dependencia son modernos y explícitos.
- Las CLI npm propiedad de Deno se agregan con
deno addodeno add --dev, se registran en el manifiesto y el archivo de bloqueo, y se ejecutan a través de tareas que invocan nombres de binarios instalados. nodeModulesDir, la activación del editor y cualquier herramienta Deno respaldada por npm se configuran intencionalmente.- Si una CLI npm se maneja desde tareas de Deno, el repositorio configura intencionalmente
nodeModulesDiryallowScriptsen lugar de depender de efectos secundarios de instalación accidentales. - Los permisos son intencionales y están documentados donde importan.
- La guía de resolución de problemas comienza con comprobaciones nativas de Deno antes de recurrir a consejos genéricos de depuración de Node o TypeScript.
Referencias
- Leer
./references/adoption-playbook.mdcuando la tarea trate sobretsconfig.json, ESLint, migración híbrida Deno o Node, o resolución de problemas de un límite de Deno. - Resumen LLM de Deno: https://docs.deno.com/llms-summary.txt
- Referencia de configuración de Deno: https://docs.deno.com/runtime/fundamentals/configuration/
- Referencia de configuración TypeScript de Deno: https://docs.deno.com/runtime/reference/ts_config_migration/
- Referencia de seguridad de Deno: https://docs.deno.com/runtime/fundamentals/security/
- Leer `./references/che
…
[truncado para traducción]