Node.js Subpath Imports와 Monorepo에서 Just-In-Time Internal Package 활용

Node.js Subpath Imports란?

Node.js Subpath Imports는 패키지 내부 경로를 명확하고 깔끔하게 가져올 수 있게 해주는 기능이다. 파일 경로를 직접 입력하지 않고, package.json의 imports 필드에 별칭을 정의해서 모듈을 불러온다. 이 방식을 사용하면 코드 가독성이 좋아지고 유지보수가 쉬워진다.

---

Subpath Imports 기본 설정

package.json 예시

imports 필드를 다음과 같이 설정한다:

{
  "name": "my-package",
  "type": "module",
  "exports": {
    ".": "./index.ts",
    "./utils": "./src/utils.ts"
  },
  "imports": {
    "#utils": "./src/utils.ts",
    "#config": "./config/index.ts"
  }
}

---

Subpath Imports 사용 예시

#utils로 정의한 별칭을 사용해 내부 모듈을 가져온다.

// 기존 방식
import utils from './src/utils.js';

// Subpath Imports 사용
import utils from '#utils';

#utils가 실제 경로인 ./src/utils.ts를 가리킨다. 별칭을 사용하면 경로가 변경되더라도 package.json만 수정하면 된다.

---

Monorepo에서 Subpath Imports를 사용하는 이유

Monorepo 환경에서는 여러 내부 패키지나 모듈을 서로 참조해야 하는 경우가 많다. 이때 Subpath Imports를 사용하면 다음과 같은 이점이 있다:

1. 경로 관리의 단순화
   파일 경로를 직접 입력하면 상대 경로가 복잡해지기 쉽다. Subpath Imports는 모듈 경로를 명확하게 관리할 수 있도록 해준다.

   // 복잡한 상대 경로
   import utils from '../../../../shared/utils.ts';
   
   // Subpath Imports 사용
   import utils from '#shared/utils';

2. 리팩토링이 쉬움
   파일 위치가 변경되더라도 package.json에서 별칭만 수정하면 되므로, 코드 전체를 수정할 필요가 없다.

3. Just-In-Time Internal Package
   Monorepo에서는 내부 패키지가 서로 의존성을 가지는 경우가 많다. Subpath Imports를 사용하면, 내부 패키지를 미리 빌드하지 않아도 바로 사용할 수 있다. 이를 통해 개발 속도가 빨라지고, 의존성 관리가 수월해진다.

---

Just-In-Time Internal Package와 Subpath Imports의 관계

Monorepo에서 내부 패키지(JIT Internal Package)를 Subpath Imports로 사용하는 이유는 다음과 같다:

• 내부 패키지를 명확하게 참조할 수 있다.
• 빌드 없이 바로 사용할 수 있어 개발 환경에서 효율적이다.
• 내부 패키지의 경로를 일관되게 관리할 수 있다.

예를 들어, #core라는 별칭으로 내부 코어 패키지를 정의하고 사용하면 다음과 같다:

package.json

{
  "imports": {
    "#*": "./*"
  }
}

코드

import { someFunction } from '#packages/core/src/index.ts';

이 방식을 사용하면 Monorepo 구조에서도 각 패키지가 독립성을 유지하면서도 쉽게 연결된다.