[SvelteKit][TypeScript] Cannot find module '$env/dynamic/private' or its corresponding type declarations.

문제

SvelteKit에서 VITE에서 PUBLIC, PRIVATE를 이용하는 형식으로 바꾸는 중에 발생한 오류입니다.

import { env } from "$env/dynamic/private";

Cannot find module '$env/dynamic/private' or its corresponding type declarations.

tsconfig.json에서 아래와 같은 설정을 사용 중이었습니다.

{
	"include": [
		"src/**/*",
		"svelte.config.js",
		"types/**/*"
	],
	"exclude": [
		"node_modules"
	]
}

 

문제 원인

TypeScript는 tsconfig.json의 include와 exclude 설정에 따라 검사할 파일의 범위를 제한합니다. 위 오류는 이 설정 때문에 $env/dynamic/private 모듈이 타입 검사 대상에서 제외되었기 때문입니다.

1. exclude 설정

"exclude": [
    "node_modules"
]

• exclude는 TypeScript가 타입 검사나 컴파일 시 제외할 디렉토리를 명시합니다.
• $env/dynamic/private는 SvelteKit의 가상 모듈로 node_modules 내부에 정의된 타입을 참조하지만, exclude 설정으로 인해 TypeScript가 이를 무시하게 됩니다.

2. include 설정

"include": [
    "src/**/*",
    "svelte.config.js",
    "types/**/*"
]

• include는 TypeScript가 검사해야 할 파일의 범위를 명시적으로 지정합니다.
• $env/dynamic/private는 실제 파일로 존재하지 않는 가상 모듈이며, src, types, svelte.config.js 경로 안에 포함되지 않으므로 TypeScript가 이를 찾을 수 없습니다.

3. $env/dynamic/private의 역할

• $env/dynamic/private는 SvelteKit에서 제공하는 런타임 환경 변수 모듈입니다.
• 이 모듈은 실제 파일로 존재하지 않고, SvelteKit의 내부 시스템에서 동적으로 제공됩니다.
• 따라서 TypeScript 설정에서 이를 포함하지 않으면 "Cannot find module" 오류가 발생합니다.

---

문제 해결

include와 exclude를 처음에 모두 지웠더니 오류가 해결되었습니다. 이는 include와 exclude 설정을 모두 제거하게 되면 TypeScript는 기본 동작으로 모든 파일을 포함하고, 자동으로 node_modules를 제외합니다. 이에 따라 $env/dynamic/private 모듈도 검사 대상에 포함되면서 오류가 해결된 것입니다.

정확한 해결 방법

1. include와 exclude 설정 조정

SvelteKit의 가상 모듈 경로인 .svelte-kit 디렉토리를 포함하도록 include 설정을 수정합니다:

"include": [
    "src/**/*",
    "svelte.config.js",
    "types/**/*",
    ".svelte-kit/**/*" // SvelteKit의 가상 모듈 포함
],
"exclude": [
    "node_modules"
]

2. paths를 사용한 가상 모듈 매핑

TypeScript의 compilerOptions.paths를 사용해 $env/dynamic/private와 같은 가상 모듈을 명시적으로 매핑할 수 있습니다:

"compilerOptions": {
    "baseUrl": ".",
    "paths": {
        "$env/dynamic/private": ["./node_modules/@sveltejs/kit/types/env.d.ts"]
    }
}

이 설정은 TypeScript가 $env/dynamic/private를 가리키는 경로를 알 수 있도록 정의합니다.