Deno
Propósito
Fornecer padrões portáteis para projetos modernos com Deno, especialmente quando a base de código mistura Deno com ferramentas orientadas ao Node, precisa de um caminho de migração limpo de padrões antigos do Deno, ou está adotando Deno em um repositório TypeScript ou Node existente.
Quando usar este skill
- Escrevendo scripts, servidores ou código de borda com Deno.
- Configurando
deno.json, tarefas e fontes de dependência. - Adaptando
tsconfig.jsonoueslint.config.*existentes para coexistir com Deno. - Misturando código Deno com código Node ou TypeScript em um único repositório.
- Revisando permissões, testes ou padrões de tempo de execução do Deno.
Padrões
- Use
deno.jsoncomo a fonte de verdade do Deno. - Prefira
deno check,deno task,deno fmt,deno lintedeno testem vez de wrappers ad hoc quando o Deno for o dono do fluxo de trabalho. - As ferramentas nativas do Deno são suficientes para código de propriedade do Deno; use Yarn apenas quando o repositório também tiver pacotes gerenciados pelo Node ou scripts fora do limite do Deno.
- Mantenha
tsconfig.jsonapenas para caminhos de propriedade do Node ou para casos de gráfico de projeto TypeScript que espaços de trabalho e escopos de diretório do Deno não conseguem expressar de forma limpa. - Lembre-se de que o Node moderno também executa TypeScript diretamente através da remoção de tipos integrada; escolha Deno pelo seu modelo de tempo de execução, permissões, dependência e ferramentas, não apenas para evitar
tscouts-node. - Prefira
deno lintedeno fmtpara arquivos de propriedade do Deno; adicione ESLint apenas quando o repositório ou editor realmente precisar do ecossistema ESLint. - Ao substituir ESLint por
deno lint, inspecione e leve adiante a intenção existente do ESLint para includes, excludes, regras de lint ou exceções documentadas emdeno.json, em vez de descartar a configuração por completo. - Ao substituir
tscpordeno check, inspecione otsconfig.jsonexistente e traduza opções de compilador, includes, excludes, libs e expectativas de rigor relevantes paradeno.jsonou umtsconfig.jsonretido com escopo claramente definido. - Quando ferramentas de editor baseadas em npm, como ESLint, precisarem ser executadas dentro de um repositório Deno, defina
nodeModulesDir: "auto"e envolva o comando emdeno task. - Quando o Deno for o dono do gerenciamento de dependências, instale dependências com
deno add, não tratandodeno run npm:<package>como substituto para instalação. Usedeno add --dev npm:<package>para CLIs e ferramentas de desenvolvimento. - Para ferramentas CLI instaladas, nomeie a
deno taskcom o nome da ferramenta e invoque o binário instalado pelo nome, por exemplo, apósdeno add --dev npm:sample-tool, adicione"sample-tool": "sample-tool". - Prefira módulos
.tspor padrão em código de propriedade do Deno; não recorra a JavaScript apenas para evitar uma etapa de build que o Deno não exige. - Prefira pacotes JSR, especificadores
npm:ou entradas de mapa de importação explícitas em vez de importações de URL legadas espalhadas. - Quando um CLI baseado em npm tiver comportamento de instalação ou pós-instalação que não coopera de forma limpa com execução única, prefira
nodeModulesDir: "auto", permita o pacote emallowScripts, adicione a dependência comdeno addoudeno add --dev, e invoque o binário instalado a partir de umadeno task. - O Deno 2 é intencionalmente compatível com
package.json, pacotes npm e built-ins do Node; mantenha a configuração específica do Deno emdeno.jsonem vez de tentar fazertsconfig.jsoncarregar ambos os mundos. - Prefira APIs padrão da Web e
Deno.servepara servidores. - Trate permissões como uma decisão de design, não um pensamento posterior.
Enquadramento de Tarefas
| Comando ou ação | O quê | Por quê | Quando | Resultado esperado |
|---|---|---|---|---|
Adotar tsconfig.json e ESLint com cuidado | Decidir o que fica na configuração de propriedade do Node e o que vai para deno.json. | Repositórios híbridos ficam barulhentos rapidamente quando ambas as toolchains tentam ser donas dos mesmos arquivos. | Ao introduzir o Deno em uma base de código TypeScript ou Node existente. | Ferramentas Deno e Node têm limites de propriedade explícitos. |
Configurar deno.json | Definir tarefas, opções de compilador e convenções de dependência no arquivo de configuração do Deno. | O Deno deve ser dono do seu próprio fluxo de trabalho, em vez de pegar emprestada uma configuração centrada no Node por acidente. | Ao iniciar ou reestruturar um projeto Deno. | Comandos Deno e comportamento do editor são consistentes. |
| Instalar um CLI npm de propriedade do Deno | Execute deno add --dev npm:<package> para ferramentas de desenvolvimento, depois adicione uma tarefa com o mesmo nome que invoca o binário instalado. | A dependência, o lockfile, o binário local e o ponto de entrada da tarefa permanecem alinhados sob o gerenciador de pacotes do Deno. | Ao adicionar ferramentas como geradores de código, CLIs de automação de navegador, linters ou formatadores a um fluxo de trabalho de propriedade do Deno. | deno.json e o lockfile registram a dependência, e deno task <tool> executa o CLI instalado. |
| Definir limites híbridos | Separar caminhos de propriedade do Deno de caminhos de propriedade do Node em repositórios mistos. | Conflitos de ferramentas são uma das falhas mais comuns em repositórios híbridos. | Quando o código Deno está ao lado de ferramentas Node ou TS. | Editores e comandos não disputam os mesmos arquivos. |
| Revisar permissões | Escolher flags --allow-* explícitas ou conjuntos de permissões nomeados em deno.json. | O modelo de segurança do Deno só ajuda quando as permissões são deliberadas. | Antes de executar novos scripts ou expor um fluxo de trabalho CLI do Deno. | O acesso a sistema de arquivos, rede e ambiente é intencional e auditável. |
| Solucionar problemas de fluxos de trabalho do Deno | Usar verificações nativas do Deno, flags de depuração e ferramentas de gráfico de módulo antes de adivinhar. | Muitos problemas com Deno são de configuração, permissão ou propriedade, não bugs de código. | Quando um repositório híbrido ou toolchain migrada se comporta inesperadamente. | A causa raiz é reduzida a configuração, permissões ou comportamento de tempo de execução. |
Regras Principais
TypeScript, tsconfig.json e bibliotecas
- Coloque configurações de compilador do Deno em
deno.jsonsobcompilerOptions; não copie umtsconfig.jsoninteiro do Node apenas para fazerdeno checkfuncionar. - Espaços de trabalho existentes do Node mais TypeScript podem manter
tsconfig.json; o Deno o consulta quando um diretório também contémdeno.jsonoupackage.json. - Se um
deno.jsonpai definecompilerOptions, essas opções têm precedência sobre opções sobrepostas detsconfig.json. - Se o objetivo é substituir
tsc, primeiro faça um inventário do comportamento atual dotsconfig.json. Preserve decisões significativas de rigor, resolução de módulo, JSX, biblioteca, include e exclude na configuração do Deno ou documente por que elas não se aplicam mais. - Use
compilerOptions.libemdeno.jsonpara modelar a superfície de tempo de execução real. Para SSR ou código de navegador mais Deno, prefira combinações como["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]; para workers Deno, prefira["deno.worker"]. - Use
compilerOptions.checkJs,// @ts-check,@ts-types,@ts-self-typesoucompilerOptions.typesquando módulos JavaScript precisarem de verificação de tipo ou declarações explícitas. - Mantenha
tsconfig.jsonapenas quando pastas de propriedade do Node, referências de projeto TS ou granularidade de include ou exclude ainda exigirem.
Linting, formatação e ESLint
- Use
deno linte a seçãolintemdeno.jsoncomo o proprietário padrão de linting para código de propriedade do Deno. - Use
deno fmte a seçãofmtemdeno.jsoncomo o formatador padrão para código de propriedade do Deno. deno lintjá cobre um conjunto de regras recomendado inspirado no ESLint; não mantenha ESLint apenas por hábito.- Se o objetivo é substituir ESLint, primeiro faça um inventário do comportamento atual de
eslint.config.*. Preserve escopos de arquivo, globais, ignores e intenção de regras significativos na configuração de lint/fmt do Deno ou documente quais regras são intencionalmente descartadas porque o Deno já as cobre ou rejeita. - Se regras personalizadas exclusivas do Deno forem necessárias, considere
lint.plugins; note que a API de plugin de lint é experimental e requer Deno 2.2 ou superior. - Se o repositório ou editor ainda precisar de ESLint, torne-o uma ferramenta secundária explícita: defina
nodeModulesDir: "auto", crieeslint.config.jse envolva a invocação emdeno task, por exemplodeno task eslint. - Mantenha um proprietário de lint por conjunto de arquivos sempre que possível. Se ambos
deno linte ESLint forem executados nos mesmos arquivos, documente o porquê ou espere diagnósticos duplicados e conflitantes.
Compatibilidade com Node e repositórios híbridos
- O Deno 2 entende
package.json,node_modules, espaços de trabalho npm e built-ins do Node; repositórios híbridos são um caminho suportado, não uma gambiarra. - O Node moderno também pode executar TypeScript diretamente. Em repositórios híbridos, decida a propriedade Node versus Deno por permissões, modelo de dependência, executor de tarefas e destino de implantação, não apenas pela execução de TypeScript.
- Se um
package.jsonexistir e você quiser que o Deno crie e atualize automaticamentenode_modules, definanodeModulesDir: "auto". Compackage.json, o Deno 2, caso contrário, usa o padrão"manual". nodeModulesDiré uma configuração de raiz do espaço de trabalho; não tente defini-la por membro do espaço de trabalho.- Use
deno installoudeno addquando o Deno for o dono do fluxo de atualização de dependências. Não assuma o comportamento de auto-instalação do Deno 1. - Use
deno add --dev npm:<package>para CLIs npm exclusivos de desenvolvimento em repositórios de propriedade do Deno. Após a adição, exponha o binário através de umadeno task, como"sample-tool": "sample-tool"em vez de"sample-tool": "deno run -A npm:sample-tool". - Faça commit das atualizações de manifesto e lockfile produzidas por
deno add; um alias de tarefa sozinho não é uma instalação de dependência. - Não habilite ferramentas Deno para um espaço de trabalho misto inteiro se apenas uma subárvore for Deno.
- Prefira ativação de editor baseada em caminho, como
deno.enablePaths, para que as ferramentas Node e Deno não disputem os mesmos arquivos. - Mantenha o limite do Deno explícito na estrutura de pastas, tarefas e docs.
Permissões, ambiente e segurança
- Prefira flags
--allow-*específicas conjuntos de permissões nomeados emdeno.jsonem vez de-A. - Use
-Pou--permission-set=<nome>quando o repositório definir conjuntos de permissões emdeno.json. - Use
--env-filequando o CLI deve carregar arquivos.env, ou@std/dotenvquando o próprio programa precisar carregá-los; ambos ainda precisam de permissões explícitas de ambiente e arquivo. - Prefira privilégio mínimo para código de aplicação e mantenha o acesso a ambiente, sistema de arquivos, rede e subprocessos óbvio em tarefas e exemplos.
- Trate
--allow-rune--allow-fficomo portas de escape do sandbox. Evite--allow-run=denoa menos que confiança total seja intencionalmente pretendida. - Para depuração ou auditoria de permissões, use
DENO_TRACE_PERMISSIONS=1eDENO_AUDIT_PERMISSIONS=<caminho>.
Solução de problemas e migração
- Recorra a
deno check,deno check --alloudeno run --checkquando o sucesso em tempo de execução e o comportamento de verificação de tipo divergirem. - Use
deno info <entrypoint>para inspecionar o gráfico de módulo e entender o comportamento de importação, cache e permissão. - Use
deno lint --fixpara limpeza comum de migração antes de editar manualmente cada problema de lint. - Para configuração de depurador, use
--inspect-brkquando o processo for de curta duração,--log-level=debugquando o inspetor ou a resolução de módulo estiver confuso, e--strace-opsquando o tempo de execução estiver travado ou inesperadamente lento. - Use flags de perfil de CPU como
--cpu-prof,--cpu-prof-mdou--cpu-prof-flamegraphquando a questão de solução de problemas for realmente sobre desempenho. - O conselho de migração deve refletir os padrões do Deno 2:
nodeModulesDiragora usa"none" | "auto" | "manual",deno cachetornou-sedeno install --entrypoint,deno vendortornou-se"vendor": true,Deno.run()deve se tornarnew Deno.Command(), eDeno.serveHttp()deve se tornarDeno.serve(). - Use atributos de importação como
with { type: "json" }em vez de asserções de importação obsoletas.
Peculiaridades
- Se as ferramentas Deno e Node reivindicarem os mesmos arquivos, os diagnósticos do editor se tornam barulhentos e enganosos.
- Se
package.jsonexistir, o Deno 2 usa o padrãonodeModulesDircomo"manual"; esquecer disso é uma razão comum para ferramentas baseadas em npm parecerem meio instaladas. - Se a extensão ESLint do VS Code fizer parte do fluxo de trabalho, ela não resolverá pacotes apenas do cache global do Deno; ela precisa de um diretório
node_moduleslocal. deno runpula a verificação de tipo por padrão, então uma execução bem-sucedida não é evidência de quedeno checkpassará.- Uma
deno taskque chamadeno run npm:<package>é um atalho de execução única, não uma instalação de dependência adequada. Não use isso como a resposta padrão para "instalar e configurar este CLI" em um repositório de propriedade do Deno. -Aé aceitável para ferramentas confiáveis, mas é o padrão errado para código de aplicação comum.- Alguns CLIs npm, incluindo Supabase em repositórios reais de tempo de execução misto, dependem de comportamento em tempo de instalação que pode ser menos confiável através de
deno run npm:...do que através de um binário instalado emnode_modules. - Padrões antigos de importação de URL e ativação de espaço de trabalho inteiro são auxílios de transição, não padrões modernos.
Validação
deno.jsoné o dono da configuração e tarefas do Deno.- Qualquer
tsconfig.jsonretido ou propriedade do ESLint é explícito e escopado aos arquivos corretos. - Substituir ESLint ou
tscpreserva o comportamento útil da configuração existente ou documenta por que foi intencionalmente descartado. - As partes Deno e Node de um repositório híbrido não disputam ferramentas.
- Especificadores de dependência são modernos e explícitos.
- CLIs npm de propriedade do Deno são adicionados com
deno addoudeno add --dev, registrados no manifesto e lockfile, e executados através de tarefas que invocam nomes de binários instalados. nodeModulesDir, ativação de editor e quaisquer ferramentas Deno baseadas em npm são configurados intencionalmente.- Se um CLI npm é acionado a partir de tarefas Deno, o repositório configura intencionalmente
nodeModulesDireallowScriptsem vez de depender de efeitos colaterais acidentais de instalação. - Permissões são intencionais e documentadas onde importam.
- A orientação de solução de problemas começa com verificações nativas do Deno antes de recorrer a conselhos genéricos de depuração Node ou TypeScript.
Referências
- Leia
./references/adoption-playbook.mdquando a tarefa for sobretsconfig.json, ESLint, migração híbrida Deno ou Node, ou solução de problemas de um limite Deno. - Resumo do LLM do Deno: https://docs.deno.com/llms-summary.txt
- Referência de Configuração do Deno: https://docs.deno.com/runtime/fundamentals/configuration/
- Referência de Configuração TypeScript do Deno: https://docs.deno.com/runtime/reference/ts_config_migration/
- Referência de Segurança do Deno: https://docs.deno.com/runtime/fundamentals/security/
- Leia `./references/che
[truncated for translation]