경로 별칭은 프로젝트의 디렉터리 구조에서 멀리 떨어진 경로의 단축 표현을 정의할 수 있게 해주는 유용한 TypeScript 기능입니다. 이를 통해 코드에서 긴 상대 경로 import를 피하고 프로젝트 구조를 더 쉽게 리팩터링할 수 있습니다. 특히 코드에서 긴 상대 경로 import를 피하는 데 유용합니다.

기본적으로 TanStack Start에는 경로 별칭이 포함되지 않습니다. 하지만 프로젝트 루트의 tsconfig.json 파일을 업데이트하고 다음 설정을 추가하면 프로젝트에 쉽게 추가할 수 있습니다:

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

이 예제에서는 ./src/* 디렉터리에 매핑되는 경로 별칭 ~/*을 정의했습니다. 이제 ~ 접두사를 사용하여 src 디렉터리에서 파일을 import할 수 있습니다.

tsconfig.json 파일을 업데이트한 후 동일한 경로 별칭을 해석하도록 빌드 도구를 설정합니다.

Vite

Vite 8

Vite 8+에는 경로 별칭에 대한 기본 제공 지원이 있으며, 기본적으로 비활성화되어 있습니다. 활성화하려면 vite.config.ts 파일에 다음 설정을 추가하면 됩니다:

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  resolve: {
    // This enables built-in support for path aliases defined in tsconfig.json
    tsconfigPaths: true,
  },
})

Vite 7 및 이전 버전

Vite 7 및 이전 버전에서는 TanStack Start 프로젝트에서 경로 별칭을 활성화하려면 vite-tsconfig-paths 플러그인을 설치합니다. 다음 명령을 실행하면 됩니다:

npm install -D vite-tsconfig-paths

이제 vite.config.ts 파일을 업데이트하여 다음 내용을 포함해야 합니다:

// vite.config.ts
import { defineConfig } from 'vite'
import viteTsConfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [
    // this is the plugin that enables path aliases
    viteTsConfigPaths({
      projects: ['./tsconfig.json'],
    }),
  ],
})

Rsbuild

Rsbuild는 기본적으로 tsconfig.json의 paths 필드를 읽습니다. 별칭이 루트 tsconfig.json에 있으면 추가 설정이 필요하지 않습니다.

사용자 지정 tsconfig 파일을 사용하는 경우 source.tsconfigPath을 사용하여 Rsbuild가 해당 파일을 가리키도록 합니다:

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'

export default defineConfig({
  source: {
    tsconfigPath: './tsconfig.custom.json',
  },
})

이 설정을 완료하면 다음과 같이 경로 별칭을 사용하여 파일을 가져올 수 있습니다:

// app/routes/posts/$postId/edit.tsx
import { Input } from '~/components/ui/input'

// instead of

import { Input } from '../../../components/ui/input'