feat: npm-add

[ohah]

PR 요약: npm 모듈 지원 및 ESM 우선순위 개선

📋 개요

ExecuteJS에서 npm 레지스트리의 패키지를 직접 다운로드하고 사용할 수 있는 기능을 추가했습니다. 또한 ESM(ES Module) 형식의 패키지를 우선적으로 로드하도록 개선하고, npm 패키지 호환성을 높이기 위한 여러 기능을 구현했습니다.

✨ 주요 변경사항

1. npm 패키지 다운로드 및 import 지원

• 파일: crates/deno-runtime/src/npm_resolver.rs, crates/deno-runtime/src/lib.rs
• npm 레지스트리 API를 통한 패키지 다운로드 및 캐싱
• npm: 프로토콜을 통한 패키지 import 지원
• 로컬 캐시를 통한 빠른 재사용
• 패키지 내부 상대 경로 import 지원

2. ESM 우선순위로 진입점 찾기 개선

• 파일: crates/deno-runtime/src/npm_resolver.rs
• exports.import → module → exports.default → main 순서로 ESM 파일 우선 선택
• immer, lodash-es 등 ESM 패키지가 올바르게 로드되도록 개선

3. Node.js process 객체 추가

• 파일: crates/deno-runtime/src/bootstrap.js
• npm 모듈 호환성을 위한 process.env.NODE_ENV 지원
• immer 등 npm 패키지에서 사용하는 Node.js 전역 객체 지원

4. TypeScript 타입 정의 파일 지원

• 파일: crates/deno-runtime/src/npm_resolver.rs
• .d.ts 파일 자동 감지 및 로드
• TypeScript 타입 정보 제공

5. CommonJS to ES Module 변환 개선

• 파일: crates/deno-runtime/src/lib.rs
• 정적 분석을 통한 named exports 추출
• React 등 CommonJS 패키지의 named import 지원

6. 문서 구조 개선 및 사용자 가이드 추가

• 파일: docs/docs/guide/npm-modules.mdx, docs/docs/dev/
• npm 모듈 사용 가이드 추가
• 개발 문서 구조 재구성 (API 참조를 개발하기 섹션으로 이동)
• 홈페이지에 npm 모듈 지원 기능 소개 추가

🔧 기술적 세부사항

아키텍처

• NpmResolver: npm 패키지 다운로드, 캐싱, 압축 해제 담당
• NpmModuleLoader: Deno Core의 ModuleLoader 트레이트 구현
• npm_path_map: npm 패키지 내부 상대 경로 import 해결

우선순위 로직

exports["."].import.default  // 1순위: ESM (exports.import)
→ package.json["module"]     // 2순위: ESM (module 필드)
→ exports["."]               // 3순위: 기본 exports
→ exports["."].require       // 4순위: CommonJS (exports.require)
→ package.json["main"]       // 5순위: CommonJS (main 필드)

📦 지원되는 패키지 예제

• ✅ lodash-es: 순수 ESM 패키지
• ✅ immer: ESM + CommonJS 모두 지원
• ✅ date-fns: ESM 우선 패키지
• ✅ react: CommonJS → ES Module 변환

🎯 사용 예제

// ESM 패키지 import
import { produce } from 'npm:immer';
import _ from 'npm:lodash-es';
import { format } from 'npm:date-fns';

📚 문서 변경사항

1. 새로운 가이드 추가: docs/docs/guide/npm-modules.mdx

   • npm 패키지 사용 방법
   • 버전 지정 및 스코프 패키지 지원
   • 예제 코드 (Lodash, date-fns)

2. 문서 구조 개선:

   • 개발 가이드와 API 참조를 dev/ 섹션으로 통합
   • 사용자 가이드와 개발자 문서 분리

3. 홈페이지 업데이트:

   • npm 모듈 지원 기능 소개
   • CommonJS 변환 기능 소개

🧪 테스트

• ESM 패키지 로드 (lodash-es)
• CommonJS 패키지 로드 및 변환 (react)
• 패키지 내부 상대 경로 import
• TypeScript 타입 정의 파일 감지
• process.env 사용 패키지 (immer)

🔄 관련 이슈

• npm 패키지 import 기능 구현
• ESM 우선순위 로딩 개선
• CommonJS → ES Module 변환 개선
• Node.js 호환성 개선

📝 커밋 내역

• feat(deno-runtime): npm 패키지 다운로드 및 import 지원 추가
• refactor(deno-runtime): ES 모듈 실행 개선 및 디버깅 로그 추가
• fix(deno-runtime): npm 패키지 내부 상대 경로 import 지원
• feat(deno-runtime): npm 패키지 TypeScript 타입 정의 파일 지원
• feat: 에러 명확하게 수정
• fix(deno-runtime): ESM 우선순위로 npm 패키지 진입점 찾기 개선
• feat(deno-runtime): Node.js process 객체 추가로 npm 모듈 호환성 개선
• docs: 개발 문서 구조 재구성
• docs: npm 모듈 사용 가이드 추가 및 홈페이지 업데이트
• chore(docs): 사용하지 않는 API 문서 제거
• docs: 개발 가이드에 API 참조 링크 추가

🚀 다음 단계 (향후 개선사항)

• SWC를 통한 CommonJS → ES Module 변환 (버전 호환성 해결 후)
• 패키지 버전 범위 지정 지원 (semver)
• 패키지 의존성 자동 해결
• 더 많은 Node.js 전역 객체 지원

[Copilot]

Pull Request Overview

This PR adds npm module support to ExecuteJS, allowing users to directly import and use packages from the npm registry using the npm: protocol. The implementation includes a custom module loader, package resolution, caching, and documentation for the new feature.

• Implements NpmModuleLoader and NpmResolver to handle npm package downloads and caching
• Adds documentation for npm module usage in Korean
• Restructures documentation navigation to include development and API reference sections

Reviewed Changes

Copilot reviewed 12 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
crates/deno-runtime/src/npm_resolver.rs	New module implementing npm package resolution, download, and caching logic
crates/deno-runtime/src/lib.rs	Adds NpmModuleLoader that handles npm: protocol imports and integrates with Deno runtime
crates/deno-runtime/src/bootstrap.js	Adds Node.js compatibility shims (process object) for npm modules
crates/deno-runtime/Cargo.toml	Adds dependencies for HTTP client, tarball extraction, and JSON parsing
docs/docs/guide/npm-modules.mdx	New documentation page explaining npm module usage
docs/docs/guide/getting-started.mdx	Updates getting started guide with npm module examples
docs/docs/dev/development.mdx	Documents npm module loading architecture
docs/docs/dev/api/commands.mdx	New API reference documentation
docs/docs/*/_meta.json	Updates navigation structure
.cursorrules	Removes clippy from linting checklist

Comments suppressed due to low confidence (2)

docs/docs/dev/development.mdx:177

• The description says 'CommonJS 패키지' (CommonJS packages) but the label is 'UMD 변환' (UMD conversion). This should be corrected to 'UMD 변환: UMD 패키지를 ES 모듈로 자동 변환(지원 예정)' for consistency.
  docs/docs/dev/development.mdx:189
• Line 189 is missing '를' between 'UMD' and 'ES'. Should be 'swc를 통해 UMD를 ES 모듈로 변환(지원 예정)'.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Bori-github]

전부다 제대로 읽은건 아닌데.. 그래도 여차저차 최선을 다해 코드 읽어봄...