Astroでimportエイリアスを設定する方法

この記事はHRBrain Advent Calendar 2024 14日目の記事です。

はじめに

こんにちは。HRBrainでオウンドメディアやランディングページの開発を担当している渡邉です。

HRBrainでは、サービスサイトの開発にAstroを採用しています。

Astroは、高速なウェブサイト構築を可能にするフレームワークであり、サーバーサイドレンダリング（SSR）や静的サイト生成（SSG）を行うことができます。

この記事では、Astroプロジェクトでimportエイリアスを設定する方法と、設定する中で遭遇した問題への対処法について解説します。

tsconfig.jsonでのエイリアス設定

TypeScriptでimportエイリアスを使用するには、tsconfig.jsonを編集します。

以下の設定例では、@/*形式のエイリアスを使用して、src配下のディレクトリを対象にしています。

tsconfig.json

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "baseUrl": ".", // 追加
    "paths": {
      "@/*": ["src/*"] // 追加
    }
  }
}

compilerOptions.baseUrlが設定されていないと、エイリアスのパスが解決できないので注意して下さい。

パスを"src/*"のように設定することで、src配下に新しいディレクトリが増える場合でも、新たにエイリアス設定を追加する必要がありません。

src/pages/index.astro

// 相対パスを使用したimport
import Button from '../../components/Button.astro';
import companyLogo from '../../assets/images/logo.png';
import someFunction from '../../utils/someFunction.ts';

// エイリアスを使用したimport
import Button from '@/components/Button.astro';
import companyLogo from '@/assets/images/logo.png';
import someFunction from '@/utils/someFunction.ts';

エイリアスに関する注意点

@typesのように、スラッシュを挟まない形式でエイリアス設定をすると、TypeScriptがそれをnpmパッケージの@typesと誤認識し、以下のようなエラーが発生する場合があります。

Cannot find module '@types/...' or its corresponding type declarations.

この問題を回避するために、エイリアス名を@/から始めるように設定しています。

CSSのurl()で発生するパス解決問題

2024年12月時点では、前述した設定方法だと、CSSのurl()で画像パスを指定する際にエイリアスが正しく解決されないというバグが潜んでいました。

発生した環境は以下の通りです。

• Astro：v4.5.5
• Node：v20.17.0
• Package Manager：Yarn

例えば、以下のようにCSSでエイリアスを使用すると、ビルド時にパスが解決されずエラーになりました。

.image {
  background-image: url("@/images/example.png"); /* 解決されない */
}

この問題に対しては、astro.config.mjsでViteのエイリアスを設定することで、CSS内のurl()でもエイリアスが解決されるようになりました。

astro.config.mjs

import { fileURLToPath } from 'node:url' // 追加
import { defineConfig } from 'astro/config';

export default defineConfig({
  vite: {
    resolve: {
      alias: {
        '@/images': fileURLToPath(new URL('./src/assets/images', import.meta.url)) // 追加
      },
    },
  },
});

.image {
  background-image: url("@/images/example.png"); /* 解決される */
}

この問題はAstro本体に起因するものであり、今後のアップデートで公式による解消が期待されます。

現時点ではこの方法を利用しつつ、公式の修正を待つことにしました。

まとめ

Astroでimportエイリアスを設定する際のポイントと、CSSのurl()におけるパス解決問題への対処方法を紹介しました。

1. tsconfig.jsonのcompilerOptionsにimportエイリアスを設定。
2. CSSのurl()問題を回避するには、astro.config.mjsでViteのエイリアス設定を追加する。

これらを参考に、エイリアスを活用して効率的なプロジェクト運用を目指してください！

PR

HRBrainではフロントエンドエンジニア（コミュニケーションデザイン）の採用も行なっているので、ぜひ！