문제 상황

tsconfig.json에 path alias를 설정했는데 import가 계속 실패할 수 있습니다.

tsconfig paths가 동작하지 않을 때 해결 방법 설명 이미지

import Button from "@/components/Button";

Editor에서는 정상처럼 보이지만 app 실행이 실패할 수 있고, 반대로 app은 실행되는데 tsc만 실패할 수도 있습니다. TypeScript, bundler, test runner, Node runtime이 하나의 alias 설정을 자동으로 공유하지 않기 때문입니다.

원인

tsconfig paths는 여러 이유로 동작하지 않을 수 있습니다.

  • baseUrl 또는 paths가 없거나 잘못 작성되었습니다.
  • Alias pattern이 실제 import와 맞지 않습니다.
  • Framework가 tsconfig.app.json 같은 다른 config를 사용합니다.
  • Vite, Webpack, Jest, Vitest, Node에 같은 alias가 설정되지 않았습니다.
  • Compile된 JavaScript를 Node에서 실행하지만 Node는 TypeScript path alias를 모릅니다.
  • 파일 이동 후 alias가 잘못된 폴더를 가리킵니다.

핵심 규칙은 간단합니다. TypeScript paths는 TypeScript가 type과 import를 이해하도록 돕지만, 그 자체로 emitted import path를 바꾸지는 않습니다.

빠른 해결

먼저 최소한의 tsconfig.json alias를 확인합니다.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

그다음 bundler 설정도 맞춥니다. Vite 예시:

import { defineConfig } from "vite";
import path from "node:path";

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src")
    }
  }
});

Config를 바꾼 뒤에는 dev server와 editor의 TypeScript server를 다시 시작합니다.

단계별 해결 방법

1. Alias Pattern 확인하기

paths의 key와 value는 import 문과 맞아야 합니다.

아래 import를 사용한다면:

import Button from "@/components/Button";

다음처럼 설정합니다.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

@/ import를 쓰는데 아래처럼 작성하면 맞지 않습니다.

{
  "paths": {
    "@": ["src"]
  }
}

이 설정은 import x from "@"만 match하고 @/components/Button에는 맞지 않습니다.

2. 실제 tsconfig 파일 확인하기

많은 프로젝트에는 TypeScript config가 여러 개 있습니다.

  • tsconfig.json
  • tsconfig.app.json
  • tsconfig.node.json
  • tsconfig.spec.json
  • tsconfig.test.json

App source가 tsconfig.app.json으로 compile된다면 tsconfig.json에만 paths를 추가해도 현재 파일에 적용되지 않을 수 있습니다.

최종 config를 확인합니다.

npx tsc --noEmit --showConfig

출력에 alias가 없다면 source file을 실제로 포함하는 config에 넣거나, 여러 config가 extend하는 shared base config로 옮깁니다.

3. Vite 또는 Bundler 설정하기

TypeScript는 alias를 이해하지만 Vite는 모를 수 있습니다. vite.config.ts에 같은 alias를 추가합니다.

import { defineConfig } from "vite";
import path from "node:path";

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src")
    }
  }
});

최근 Vite에는 resolve.tsconfigPaths option도 있습니다. 이 option을 사용한다면 현재 Vite version이 해당 option을 지원하는지, 그리고 active tsconfig.json에 alias가 있는지 확인해야 합니다.

다른 bundler를 사용한다면 tsconfig만 믿지 말고 해당 bundler의 alias 설정을 추가해야 합니다.

4. Test 설정 따로 확인하기

Test runner는 별도 alias mapping이 필요할 수 있습니다.

Vitest는 보통 Vite config를 읽지만 프로젝트 설정에 따라 다를 수 있습니다. Test만 실패한다면 vitest.config.ts를 확인하세요.

Jest는 보통 moduleNameMapper가 필요합니다.

module.exports = {
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1"
  }
};

tsc와 app은 통과하는데 test만 실패한다면 TypeScript alias가 아니라 test runner resolver 문제일 가능성이 큽니다.

5. Node Runtime 처리하기

Node는 기본적으로 tsconfig.json의 paths를 읽지 않습니다. Script, CLI, server code, compile된 JavaScript를 직접 실행할 때 중요합니다.

선택지는 다음과 같습니다.

  • Runtime Node script에서는 relative import를 사용합니다.
  • 실행 전에 bundling합니다.
  • ts-node와 함께 tsconfig-paths 같은 runtime helper를 사용합니다.
  • Framework의 server build tool이 alias를 resolve하도록 설정합니다.

npx tsc --noEmit은 통과하지만 node dist/index.js가 실패한다면 emitted JavaScript import path를 확인하세요. 출력 파일에 여전히 @/가 남아 있다면 Node는 추가 설정 없이 resolve하지 못합니다.

6. Cache된 도구 다시 시작하기

Config를 바꾼 뒤 아래 도구를 재시작합니다.

  • Vite dev server
  • test watcher
  • VS Code TypeScript server
  • ESLint server

tsconfig 변경 후 editor diagnostic이 오래 남는 경우가 흔합니다. Editor만 믿지 말고 terminal command로 확인해야 합니다.

해결 확인 방법

다음을 실행합니다.

npx tsc --noEmit
npm run build

Test가 있다면 실행합니다.

npm test

Vite app이라면 dev server도 확인합니다.

npm run dev

TypeScript, bundler, 그리고 실패했던 runtime 또는 test command가 모두 alias를 resolve해야 해결된 것입니다.

흔한 실수

  • paths가 JavaScript import를 자동으로 rewrite한다고 기대합니다.
  • "@/..." import를 쓰면서 "@": ["src"]만 설정합니다.
  • Framework가 tsconfig.app.json을 쓰는데 tsconfig.json만 수정합니다.
  • Vite는 설정했지만 Jest 같은 test runner 설정을 빠뜨립니다.
  • Compile된 JavaScript를 Node에서 실행하면서 unresolved @/ import를 남깁니다.
  • Config 변경 후 dev server를 재시작하지 않습니다.

공식 문서

관련 글

자주 묻는 질문

이 글은 언제 먼저 적용하면 좋나요?

오류 메시지, 실행한 명령, 사용 중인 OS와 버전을 먼저 기록한 뒤 이 글의 원인별 순서대로 확인하는 것이 좋습니다.

초보자가 가장 먼저 확인할 부분은 무엇인가요?

처음에는 환경 변수, 설치 경로, 권한, 캐시처럼 재현 가능성이 높은 항목부터 확인하세요. 그다음 로그와 설정 파일을 비교하면 원인을 좁히기 쉽습니다.

더 찾아볼 때 어떤 키워드를 쓰면 좋나요?

추가 검색할 때는 “tsconfig paths가 동작하지 않을 때 해결 방법” 같은 핵심 문구와 error message, version, Windows, GitHub Pages, Jekyll 같은 실제 환경 키워드를 붙이면 더 정확한 결과를 얻기 쉽습니다.

Leave a comment

You may also enjoy