Deno
목적
특히 코드베이스가 Deno와 Node 중심 도구를 혼합하여 사용하거나, 기존 Deno 패턴에서 깔끔한 마이그레이션 경로가 필요하거나, 기존 TypeScript 또는 Node 저장소에 Deno를 도입하는 경우, 현대적인 Deno 프로젝트를 위한 이식성 높은 기본 설정을 제공합니다.
이 스킬을 사용해야 하는 경우
- Deno 스크립트, 서버 또는 엣지 코드를 작성할 때
deno.json, 작업(task), 의존성 소스를 구성할 때- 기존
tsconfig.json또는eslint.config.*파일을 Deno와 공존하도록 조정할 때 - 하나의 저장소에서 Deno 코드와 Node 또는 TypeScript 코드를 혼합할 때
- Deno 권한, 테스트 또는 런타임 패턴을 검토할 때
기본 설정
- Deno의 진리 소스(source of truth)로
deno.json을 사용합니다. - Deno가 워크플로우를 소유하는 경우, 임시 래퍼(wrapper)보다
deno check,deno task,deno fmt,deno lint,deno test를 선호합니다. - Deno의 네이티브 도구는 Deno 소유 코드에 충분합니다. 저장소에 Deno 경계 외부에 Node에서 관리하는 패키지나 스크립트가 있는 경우에만 Yarn을 사용합니다.
tsconfig.json은 Node 소유 경로 또는 Deno 워크스페이스와 디렉토리 스코프로 깔끔하게 표현할 수 없는 TypeScript 프로젝트 그래프 케이스에 대해서만 유지합니다.- 현대적인 Node도 내장 타입 스트리핑(type stripping)을 통해 TypeScript를 직접 실행한다는 점을 기억하세요. 단순히
tsc나ts-node를 피하기 위한 목적이 아니라, 런타임, 권한, 의존성, 도구 모델을 위해 Deno를 선택하세요. - Deno 소유 파일에는
deno lint와deno fmt를 선호합니다. 저장소나 편집기가 정말로 ESLint 생태계를 필요로 하는 경우에만 ESLint를 추가하세요. - ESLint를
deno lint로 대체할 때는 기존 ESLint의 의도를 검사하고, 구성을 완전히 폐기하는 대신deno.json의 includes, excludes, lint 규칙 또는 문서화된 예외로 이월시킵니다. tsc를deno check로 대체할 때는 기존tsconfig.json을 검사하고 관련 컴파일러 옵션, includes, excludes, libs, 엄격성 기대치를deno.json또는 명확히 범위가 지정된 유지된tsconfig.json으로 변환합니다.- ESLint와 같은 npm 기반 편집기 도구를 Deno 저장소 내에서 실행해야 하는 경우
nodeModulesDir: "auto"로 설정하고 명령을deno task로 래핑합니다. - Deno가 의존성 관리를 소유하는 경우,
deno run npm:<package>를 설치의 대체 수단으로 취급하지 말고deno add로 의존성을 설치하세요. 개발 전용 CLI 및 도구에는deno add --dev npm:<package>를 사용합니다. - 설치된 CLI 도구에 대해서는
deno task이름을 도구 이름으로 지정하고 설치된 바이너리를 이름으로 호출합니다. 예를 들어deno add --dev npm:sample-tool후에"sample-tool": "sample-tool"을 추가합니다. - Deno 소유 코드에서는 기본적으로
.ts모듈을 선호합니다. Deno가 필요로 하지 않는 빌드 단계를 피하기 위해 JavaScript로 내려가지 마세요. - 분산된 레거시 URL 가져오기(import)보다 JSR 패키지,
npm:지정자 또는 명시적인 가져오기 맵(import map) 항목을 선호합니다. - npm 기반 CLI에 일회성 실행과 깔끔하게 협력하지 않는 설치 또는 설치 후(postinstall) 동작이 있는 경우,
nodeModulesDir: "auto"를 선호하고,allowScripts에서 패키지를 허용하며,deno add또는deno add --dev로 의존성을 추가하고,deno task에서 설치된 바이너리를 호출합니다. - Deno 2는 의도적으로
package.json, npm 패키지 및 Node 내장 모듈과 호환됩니다.tsconfig.json이 두 세계를 모두 처리하도록 하는 대신 Deno 관련 구성을deno.json에 유지하세요. - 서버에는 웹 표준 API와
Deno.serve를 선호합니다. - 권한을 나중에 생각하는 것이 아니라 설계 결정으로 취급하세요.
작업 프레이밍
| 명령 또는 작업 | 대상 | 이유 | 시기 | 예상 결과 |
|---|---|---|---|---|
tsconfig.json 및 ESLint 신중하게 도입 | Node 소유 구성에 남을 것과 deno.json으로 이동할 것을 결정합니다. | 두 도구 체인이 동일한 파일을 소유하려고 하면 하이브리드 저장소가 빠르게 혼란스러워집니다. | 기존 TypeScript 또는 Node 코드베이스에 Deno를 도입할 때. | Deno와 Node 도구가 각각 명시적인 소유권 경계를 갖습니다. |
deno.json 구성 | Deno의 구성 파일에서 작업, 컴파일러 옵션, 의존성 규칙을 정의합니다. | Deno는 실수로 Node 중심 구성을 빌리는 대신 자체 워크플로우를 소유해야 합니다. | Deno 프로젝트를 시작하거나 재구성할 때. | Deno 명령과 편집기 동작이 일관됩니다. |
| Deno 소유 npm CLI 설치 | 개발 도구에 대해 deno add --dev npm:<package>를 실행한 후, 설치된 바이너리를 호출하는 동일한 이름의 작업을 추가합니다. | 의존성, 잠금 파일, 로컬 바이너리, 작업 진입점이 Deno의 패키지 관리자 아래에서 정렬됩니다. | 코드 생성기, 브라우저 자동화 CLI, 린터, 포맷터와 같은 도구를 Deno 소유 워크플로우에 추가할 때. | deno.json과 잠금 파일이 의존성을 기록하고 deno task <tool>이 설치된 CLI를 실행합니다. |
| 하이브리드 경계 설정 | 혼합 저장소에서 Deno 소유 경로를 Node 소유 경로와 분리합니다. | 도구 충돌은 가장 일반적인 하이브리드 저장소 실패 중 하나입니다. | Deno 코드가 Node 또는 TS 도구와 함께 있을 때. | 편집기와 명령이 동일한 파일을 두고 충돌하지 않습니다. |
| 권한 검토 | 런타임 액세스를 위해 명시적 권한과 작업 래퍼를 선택합니다. | Deno의 보안 모델은 권한이 의도적일 때만 도움이 됩니다. | 새 스크립트를 실행하거나 Deno CLI 워크플로우를 노출하기 전에. | 파일 시스템, 네트워크, 환경 액세스가 의도적이고 감사 가능합니다. |
| Deno 워크플로우 문제 해결 | 추측하기 전에 Deno 네이티브 검사, 디버거 플래그, 모듈 그래프 도구를 사용합니다. | 많은 Deno 문제는 코드 버그보다는 구성, 권한 또는 소유권 문제입니다. | 하이브리드 저장소 또는 마이그레이션된 도구 체인이 예기치 않게 동작할 때. | 근본 원인이 구성, 권한 또는 런타임 동작으로 좁혀집니다. |
핵심 규칙
TypeScript, tsconfig.json 및 라이브러리
- Deno 컴파일러 설정은
deno.json의compilerOptions에 넣고deno check를 실행하기 위해 전체 Nodetsconfig.json을 복사하지 마세요. - 기존 Node 및 TypeScript 워크스페이스는
tsconfig.json을 유지할 수 있으며, Deno는 디렉토리에deno.json또는package.json도 포함된 경우 이를 검사합니다. - 상위
deno.json이compilerOptions를 정의하는 경우, 중복되는tsconfig.json옵션보다 우선합니다. - 목표가
tsc를 대체하는 것이라면, 먼저 현재tsconfig.json동작을 인벤토리화합니다. 의미 있는 엄격성, 모듈 해상도, JSX, 라이브러리, include 및 exclude 결정을 Deno 구성에 보존하거나 더 이상 적용되지 않는 이유를 문서화합니다. deno.json의compilerOptions.lib를 사용하여 실제 런타임 표면을 모델링합니다. SSR 또는 브라우저 및 Deno 코드의 경우["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]와 같은 조합을 선호하고, Deno 워커의 경우["deno.worker"]를 선호합니다.- JavaScript 모듈에 명시적 타입 검사 또는 선언이 필요한 경우
compilerOptions.checkJs,// @ts-check,@ts-types,@ts-self-types또는compilerOptions.types를 사용합니다. - Node 소유 폴더, TS 프로젝트 참조 또는 include/exclude 세분화가 여전히 필요한 경우에만
tsconfig.json을 유지합니다.
린팅, 포맷팅 및 ESLint
- Deno 소유 코드의 기본 린트 소유자로
deno lint및deno.json의lint섹션을 사용합니다. - Deno 소유 코드의 기본 포맷터로
deno fmt및deno.json의fmt섹션을 사용합니다. deno lint는 이미 ESLint에서 영감을 받은 권장 규칙 세트를 포함합니다. 습관적으로 ESLint를 유지하지 마세요.- 목표가 ESLint를 대체하는 것이라면, 먼저 현재
eslint.config.*동작을 인벤토리화합니다. 의미 있는 파일 범위, 전역 변수, 무시 항목, 규칙 의도를 Deno lint/fmt 구성에 보존하거나 Deno가 이미 포함하거나 거부하기 때문에 의도적으로 삭제된 규칙을 문서화합니다. - 사용자 정의 Deno 전용 규칙이 필요한 경우
lint.plugins를 고려하세요. lint 플러그인 API는 실험적이며 Deno 2.2 이상이 필요합니다. - 저장소 또는 편집기가 여전히 ESLint를 필요로 하는 경우, 이를 명시적인 보조 도구로 만듭니다.
nodeModulesDir: "auto"로 설정하고eslint.config.js를 생성한 후deno task eslint와 같이 호출을deno task로 래핑합니다. - 가능하면 파일 세트당 하나의 린트 소유자를 유지합니다.
deno lint와 ESLint가 동일한 파일에서 실행되는 경우 이유를 문서화하거나 중복 및 충돌하는 진단을 예상합니다.
Node 호환성 및 하이브리드 저장소
- Deno 2는
package.json,node_modules, npm 워크스페이스 및 Node 내장 모듈을 이해합니다. 하이브리드 저장소는 해결 방법이 아닌 지원되는 경로입니다. - 현대적인 Node도 TypeScript를 직접 실행할 수 있습니다. 하이브리드 저장소에서는 TypeScript 실행만으로가 아니라 권한, 의존성 모델, 작업 실행기, 배포 대상을 기준으로 Node 대 Deno 소유권을 결정합니다.
package.json이 존재하고 Deno가node_modules를 자동 생성 및 새로 고침하도록 하려면nodeModulesDir: "auto"를 설정합니다.package.json이 있는 경우 Deno 2는 기본적으로"manual"을 사용합니다.nodeModulesDir은 워크스페이스 루트 설정입니다. 워크스페이스 멤버별로 설정하려고 시도하지 마세요.- Deno가 의존성 업데이트 흐름을 소유하는 경우
deno install또는deno add를 사용합니다. Deno 1 자동 설치 동작을 가정하지 마세요. - Deno 소유 저장소에서 개발 전용 npm CLI에는
deno add --dev npm:<package>를 사용합니다. 추가 후에는"sample-tool": "deno run -A npm:sample-tool"대신"sample-tool": "sample-tool"과 같은deno task를 통해 바이너리를 노출합니다. deno add에 의해 생성된 매니페스트 및 잠금 파일 업데이트를 체크인합니다. 작업 별칭만으로는 의존성 설치가 아닙니다.- 하나의 하위 트리만 Deno인 경우 전체 혼합 워크스페이스에 대해 Deno 도구를 활성화하지 마세요.
- Node와 Deno 도구가 동일한 파일에서 충돌하지 않도록
deno.enablePaths와 같은 경로 기반 편집기 활성화를 선호합니다. - 폴더 구조, 작업 및 문서에서 Deno 경계를 명시적으로 유지합니다.
권한, 환경 및 보안
-A보다 좁은--allow-*플래그 또는deno.json의 명명된 권한 세트를 선호합니다.- 저장소가
deno.json에서 권한 세트를 정의하는 경우-P또는--permission-set=<name>을 사용합니다. - CLI가
.env파일을 로드해야 하는 경우--env-file을 사용하고, 프로그램 자체에서 로드해야 하는 경우@std/dotenv를 사용합니다. 둘 다 여전히 명시적 환경 및 파일 권한이 필요합니다. - 애플리케이션 코드에는 최소 권한을 선호하고 작업 및 예제에서 환경, 파일 시스템, 네트워크 및 서브프로세스 액세스를 명확하게 유지합니다.
--allow-run및--allow-ffi를 샌드박스 이스케이프 해치(escape hatch)로 취급합니다. 완전한 신뢰가 명시적으로 의도된 경우가 아니라면--allow-run=deno를 피하세요.- 권한 디버깅 또는 감사에는
DENO_TRACE_PERMISSIONS=1및DENO_AUDIT_PERMISSIONS=<path>를 사용합니다.
문제 해결 및 마이그레이션
- 런타임 성공과 타입 검사 동작이 다른 경우
deno check,deno check --all또는deno run --check를 사용합니다. deno info <entrypoint>를 사용하여 모듈 그래프를 검사하고 가져오기, 캐시 및 권한 동작을 이해합니다.- 모든 린트 문제를 수동으로 편집하기 전에 일반적인 마이그레이션 정리를 위해
deno lint --fix를 사용합니다. - 디버거 설정의 경우 프로세스가 수명이 짧은 경우
--inspect-brk를 사용하고, 검사기 또는 모듈 해상도가 혼란스러운 경우--log-level=debug를 사용하며, 런타임이 중단되거나 예기치 않게 느린 경우--strace-ops를 사용합니다. - 문제 해결 질문이 실제로 성능에 관한 것인 경우
--cpu-prof,--cpu-prof-md또는--cpu-prof-flamegraph와 같은 CPU 프로파일링 플래그를 사용합니다. - 마이그레이션 조언은 Deno 2 기본값을 반영해야 합니다.
nodeModulesDir은 이제"none" | "auto" | "manual"을 사용하고,deno cache는deno install --entrypoint가 되었고,deno vendor는"vendor": true가 되었으며,Deno.run()은new Deno.Command()가 되어야 하고,Deno.serveHttp()는Deno.serve()가 되어야 합니다. - 더 이상 사용되지 않는 가져오기 어설션(import assertion) 대신
with { type: "json" }와 같은 가져오기 속성(import attribute)을 사용합니다.
주의사항
- Deno와 Node 도구가 동일한 파일을 주장하면 편집기 진단이 시끄럽고 오해의 소지가 있습니다.
package.json이 존재하면 Deno 2는nodeModulesDir을"manual"로 기본 설정합니다. 이를 잊는 것은 npm 기반 도구가 반쯤 설치된 것처럼 보이는 일반적인 이유입니다.- VS Code ESLint 확장이 워크플로우의 일부인 경우 Deno의 글로벌 캐시만으로는 패키지를 해석하지 못합니다. 로컬
node_modules디렉토리가 필요합니다. deno run은 기본적으로 타입 검사를 건너뛰므로 통과하는 실행이deno check가 통과할 것이라는 증거가 아닙니다.deno run npm:<package>를 호출하는deno task는 일회성 실행 바로가기일 뿐, 적절한 의존성 설치가 아닙니다. Deno 소유 저장소에서 "이 CLI 설치 및 설정"에 대한 기본 답변으로 사용하지 마세요.-A는 신뢰할 수 있는 도구에는 허용되지만 일반 애플리케이션 코드에는 잘못된 기본값입니다.- 실제 혼합 런타임 저장소의 Supabase를 포함한 일부 npm CLI는
deno run npm:...을 통한 설치된 바이너리보다node_modules아래에서 더 신뢰할 수 없는 설치 시간 동작에 의존합니다. - 오래된 URL 가져오기 및 전체 워크스페이스 활성화 패턴은 전환 지원 수단일 뿐 현대적인 기본값이 아닙니다.
검증
deno.json이 Deno 구성 및 작업을 소유합니다.- 유지된 모든
tsconfig.json또는 ESLint 소유권은 명시적이며 올바른 파일로 범위가 지정됩니다. - ESLint 또는
tsc를 대체하면 기존 구성에서 유용한 동작을 보존하거나 의도적으로 삭제된 이유를 문서화합니다. - 하이브리드 저장소의 Deno 및 Node 부분이 도구를 두고 충돌하지 않습니다.
- 의존성 지정자가 현대적이고 명시적입니다.
- Deno 소유 npm CLI는
deno add또는deno add --dev로 추가되고, 매니페스트 및 잠금 파일에 기록되며, 설치된 바이너리 이름을 호출하는 작업을 통해 실행됩니다. nodeModulesDir, 편집기 활성화 및 npm 기반 Deno 도구가 의도적으로 구성됩니다.- npm CLI가 Deno 작업에서 구동되는 경우 저장소는 우발적인 설치 부작용에 의존하지 않고 의도적으로
nodeModulesDir및allowScripts를 구성합니다. - 권한은 의도적이며 중요한 곳에 문서화됩니다.
- 문제 해결 지침은 일반 Node 또는 TypeScript 디버깅 조언으로 대체하기 전에 Deno 네이티브 검사로 시작합니다.
참고 자료
- 작업이
tsconfig.json, ESLint, 하이브리드 Deno 또는 Node 마이그레이션, 또는 Deno 경계 문제 해결에 관한 경우./references/adoption-playbook.md를 읽으세요. - Deno LLM 요약: https://docs.deno.com/llms-summary.txt
- Deno 구성 참조: https://docs.deno.com/runtime/fundamentals/configuration/
- Deno TypeScript 구성 참조: https://docs.deno.com/runtime/reference/ts_config_migration/
- Deno 보안 참조: https://docs.deno.com/runtime/fundamentals/security/
./references/che읽기
…
[번역을 위해 잘렸습니다]