Next.jsでimport地獄を解消！@/でスッキリ書くエイリアス設定術

てんハロ運営者

こんなあなたにピッタリな記事👇

import文書くとき「../../../」となっている
フォルダ構成変わったときのimport文修正が大変
「＠/」を使っている理由がよくわかっていない

がまぁまぁわかります！

プロが教える、業界最前線のノウハウ【Coloso】

困ってた自分に届けたい話
エイリアスってなに？
Next.js + TypeScriptでの設定方法
1. tsconfig.json にパスエイリアスを設定
現場ではどう使われてる？
豆知識：baseUrl を "./" にしないとどうなる？

困ってた自分に届けたい話

開発が進んでくると、ファイルの階層が深くなっていきますよね。
気づけば、../../../components/Button のような import 文が何度も登場…。

「あれ？このファイル、どこから import してたっけ？」
「../ を3回戻って、また中に入って……ややこしい！」

そんな風に、パスが複雑になって迷子になる問題に悩まされていた方も多いはず。
実際、現場でも「エイリアスパスを使わないとPRが通らない」なんてこともあるらしいっす…。

てんハロ運営者

この記事は、同じように困っていた方への備忘録兼シェアとして書いています。

エイリアスってなに？

エイリアスとは、長い相対パスを短くわかりやすくするための別名のこと。

// Before（地獄）
import Header from "../../../components/shared/Header";

// After（天国）
import Header from "@/components/shared/Header";

// Before（地獄）
import Header from "../../../components/shared/Header";

// After（天国）
import Header from "@/components/shared/Header";

このように、@/ を使ってパスを簡略化することで、

階層の深さに悩まされない
コードが一気に読みやすくなる

といったメリットがあります。

Next.js + TypeScriptでの設定方法

tsconfig.json にパスエイリアスを設定

こうしておくと、@/components は src/components にマッピングされます。

{
  "compilerOptions": {  // tsのコンパイル設定
    "baseUrl": "./",　　　// パスの基準（プロジェクトルート）
    "paths": {
      "@/*": ["src/*"]　// "@/..." → "src/..." に変換
    }
  }
}

{
  "compilerOptions": {  // tsのコンパイル設定
    "baseUrl": "./",　　　// パスの基準（プロジェクトルート）
    "paths": {
      "@/*": ["src/*"]　// "@/..." → "src/..." に変換
    }
  }
}

現場ではどう使われてる？

エイリアスは、以下のように「機能別フォルダ」と組み合わせて使われています。

エイリアス	説明
`@/components`	見た目のパーツ（ボタンなど）
`@/hooks`	再利用できる動き（フック）
`@/lib`	外部サービス連携（APIなど）
`@/utils`	どこでも使える便利な関数集
`@/constants`	変わらない設定値のメモ帳