Path Alias di tsconfig

Analogi: Alamat Lengkap vs Nama Jalan Pintas

Bayangkan kamu tinggal di perumahan besar. Setiap kali memberi tahu alamat, kamu tidak perlu menyebut "Indonesia, Jawa Barat, Kota Bandung, Kecamatan X, Jalan Y nomor Z" lengkap. Cukup sebut nama jalan pintas yang disepakati warga, misalnya "blok A". Path alias di tsconfig bekerja seperti itu: nama pendek yang disepakati untuk menunjuk ke folder tertentu, supaya import tidak perlu menulis alamat relatif yang panjang dan rapuh.

Kenapa Path Alias Ada?

Di project kecil, import relatif masih nyaman: import { Button } from "../components/Button". Tapi project tumbuh, struktur makin dalam, dan tiba-tiba kamu punya baris seperti ini:

import { Button } from "../../../components/Button";
import { formatRupiah } from "../../utils/format";

Tiga masalah muncul. Pertama, sulit dibaca: berapa banyak ../ itu artinya apa? Kedua, rapuh: pindahkan file satu folder lebih dalam, semua import-nya rusak. Ketiga, refactoring jadi mimpi buruk.

Path alias menyelesaikan ketiganya. Kamu memberi nama pendek untuk folder penting, biasanya @/ untuk folder src, lalu semua import memakai nama itu dari mana pun file berada.

Contoh 1: Menyalakan paths di tsconfig.json

Buka tsconfig.json dan tambahkan baseUrl dan paths di dalam compilerOptions:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  },
  "include": ["src"]
}

Artinya: setiap import yang diawali @/ dipetakan ke folder src/. Tanda * berarti "sisanya diteruskan apa adanya", jadi @/components/Button menjadi src/components/Button. Kamu bisa membuat beberapa alias sekaligus, misalnya @components dan @utils yang menunjuk langsung ke subfoldernya.

Sekarang bandingkan import sebelum dan sesudah:

// SEBELUM: relatif, rapuh, susah dibaca
import { Button } from "../../../components/Button";
import { formatRupiah } from "../../utils/format";

// SESUDAH: absolut dari sudut pandang alias, stabil
import { Button } from "@/components/Button";
import { formatRupiah } from "@/utils/format";

File yang memakai alias bisa dipindah ke folder sedalam apa pun tanpa mengubah satu pun baris import.

Contoh 2: Error Nyata Saat Alias Belum Dikonfigurasi

Misalkan kamu langsung menulis @/utils/format di kode, tapi lupa (atau belum) menambahkan paths di tsconfig.json:

import { formatRupiah } from "@/utils/format";

console.log(formatRupiah(150000));

Jalankan npx tsc --noEmit. Di terminal muncul:

Error TS2307 berarti TypeScript tidak tahu @/utils/format itu menunjuk ke file apa. Compiler tidak menebak-nebak: alias hanya dikenal kalau dideklarasikan di paths. Solusinya selalu sama, cek tiga hal berurutan: (1) paths sudah ada di compilerOptions, (2) pola alias-nya cocok dengan import yang ditulis, (3) file targetnya benar-benar ada di lokasi yang dipetakan.

Catatan teknis: paths hanya mengatur bagaimana TypeScript mencari file saat type checking, bukan bagaimana kode dijalankan. Saat compile ke JavaScript, tsc tidak menulis ulang @/components/Button menjadi path relatif. Artinya runtime (Node, bundler) juga harus paham alias ini: Vite butuh plugin vite-tsconfig-paths, Next.js sudah mendukung otomatis, dan Node murni butuh konfigurasi tambahan. Kalau alias jalan di editor tapi error saat dijalankan, masalahnya hampir pasti di sisi runtime, bukan di tsconfig.

Kesalahan Umum

1. Menulis alias di kode tapi lupa mendaftarkannya di tsconfig

// SALAH: alias dipakai tapi paths belum dikonfigurasi -> TS2307
import { Button } from "@/components/Button";

// BENAR: daftarkan dulu di tsconfig.json, baru pakai di kode
// "paths": { "@/*": ["src/*"] }

2. Pola paths tidak cocok dengan import

// SALAH: import "@/components/Button" tapi hanya ada "@utils/*"
// -> TS2307 karena tidak ada pola yang cocok

// BENAR: pastikan setiap awalan import punya polanya sendiri
// "paths": { "@/*": ["src/*"], "@components/*": ["src/components/*"] }

3. Mengira alias otomatis berlaku saat runtime

# SALAH: "di VS Code tidak error, pasti aman"
# npx tsc lolos, tapi node dist/app.js -> Error: Cannot find module '@/utils/format'

# BENAR: pastikan runtime/bundler juga dikonfigurasi
# Vite: tambahkan vite-tsconfig-paths. Next.js: sudah otomatis.