インポート

Astroは、ほとんどの静的アセットを設定不要でサポートしています。プロジェクトのJavaScript（Astro frontmatterスクリプトを含む）のどこでもimport文を使用でき、Astroは最終ビルドにその静的アセットのビルドされた最適化されたコピーを含めます。また、@importはCSSと<style>タグの中でもサポートされています。

対応するファイル形式

Astroは、標準で以下のファイル形式をサポートしています。

• Astroコンポーネント（.astro）
• Markdown（.md, .markdownなど）
• JavaScript（.js、.mjs）
• TypeScript（.ts）
• NPMパッケージ
• JSON（.json）
• CSS（.css）
• CSS Modules（.module.css）
• イメージとアセット（.svg、.jpg、.pngなど）

さらに、Astroを拡張して、React、Svelte、Vueコンポーネントなど、さまざまなUIフレームワークのサポートを追加できます。また、Astro MDXインテグレーションやAstro Markdocインテグレーションをインストールし、.mdxファイルや.mdocファイルも使用できます。

public/内のファイル

プロジェクトのpublic/ディレクトリには、任意の静的アセットを置けます。Astroはそれをそのまま最終ビルドとして直接コピーします。public/内のファイルはビルドやバンドルの対象とならないため、あらゆる種類のファイルがサポートされます。

HTMLテンプレートからは、URLパスで public/ 内のファイルを直接参照できます。

// /public/reports/annual/2024.pdf へのリンク
<a href="/reports/annual/2024.pdf">2024年の年次報告書（PDF）をダウンロード</a>

// /public/assets/cats/ginger.jpg を表示
<img src="/assets/cats/ginger.jpg" alt="ベッドで眠るオレンジ色の猫。">

Import構文

Astroは、ESMを使います。これは、ブラウザでサポートされているのと同じimportおよびexport構文です。

JavaScript

import { getUser } from './user.js';

JavaScriptは、通常のESMのimportとexportの構文でインポートできます。

JSXファイルのインポート

JSXやTSXファイルをレンダリングするには、適切なUIフレームワーク（React、Preact、Solid）が必要です。Astroは.jsや.tsファイル内のJSXをサポートしていないため、必要に応じて.jsxか.tsx拡張子を使用してください。

TypeScript

import { getUser } from './user';
import type { UserType } from './user';

Astroには、TypeScriptのサポートが組み込まれています。Astroプロジェクトで.tsや .tsxファイルを直接インポートしたり、Astroのコンポーネントスクリプトや 巻き上げられたscriptタグの中で直接TypeScriptコードを書けます。

Astroは、型チェックを自ら行うことはありません。型チェックは、IDEや別のスクリプトなど、Astroの外部で行う必要があります。Astroファイルの型チェックには、astro checkコマンドが用意されています。

TypeScriptとファイル拡張子

TypeScriptのモジュール解決ルールでは、TypeScriptファイルをインポートする際に.tsと.tsxのファイル拡張子を使用するべきではありません。代わりに、.js/.jsxというファイル拡張子を使うか、ファイル拡張子を完全に省略する必要があります。

import { getUser } from './user.js'; // user.ts
import MyComponent from "./MyComponent"; // MyComponent.tsx

AstroのTypeScriptサポートの詳細はこちら。

npmパッケージ

npmパッケージをインストールした場合、Astroでインポートできます。

---
import { Icon } from 'astro-icon';
---

パッケージがレガシーフォーマットを使用して公開されていた場合、Astroはimport文が機能するように、パッケージをESMに変換します。場合によっては、動作させるためにvite configを調整する必要があるかもしれません。

注意

一部のパッケージは、ブラウザ環境に依存しています。Astroコンポーネントはサーバー上で動作するため、パッケージをフロントマターでインポートするとエラーになることがあります。

JSON

// デフォルトのエクスポートでJSONオブジェクトを読み込む
import json from './data.json';

Astroは、JSONファイルをアプリケーションへ直接インポートできます。インポートされたファイルは、デフォルトのインポートで完全なJSONオブジェクトを返します。

CSS

// 'style.css'を読み込んで、ページに注入します。
import './style.css';

Astroは、CSSファイルをアプリケーションに直接インポートできます。インポートされたスタイルはエクスポートされませんが、インポートすることで自動的にそれらのスタイルがページに追加されます。これはデフォルトですべてのCSSファイルに対して機能し、プラグインによってSassやLessのようなコンパイル可能なCSS言語もサポートします。

CSSファイルのURLを直接参照したり、CSSを文字列としてインポートするなどの高度なCSSインポートの使用例については、スタイリングガイドを参照してください。

CSSモジュール

// 1. './style.module.css'のクラス名をユニークでスコープされた値に変換します。
// 2. 元のクラス名と、最終的にスコープされた値をマッピングしたオブジェクトを返します。
import styles from './style.module.css';

// この例ではJSXを使っていますが、CSSモジュールはどんなフレームワークでも使えます。
return <div className={styles.error}>Your Error Message</div>;

Astroは、[name].module.cssという命名規則でCSSモジュールをサポートしています。他のCSSファイルと同様に、インポートすると自動的にそのCSSがページに適用されます。しかし、CSSモジュールは、オリジナルのクラス名を一意の識別子にマップする特別なデフォルトの styles オブジェクトをエクスポートします。

CSSモジュールは、スタイルシートのために一意に生成されたクラス名によって、フロントエンドでコンポーネントのスコープと分離を強制するのに役立ちます。

その他のアセット

// `src`などのプロパティを持つオブジェクトを取得します
import imgReference from './image.png';
import svgReference from './image.svg';

// HTMLやUIフレームワークのコンポーネントでは明示的に`src`プロパティを指定します
<img src={imgReference.src} alt="画像の説明" />;

// Astroの`<Image />`と`<Picture />`コンポーネントはデフォルトで`src`を参照します
<Image src={imgReference} alt="画像の説明">

上記で明示されていないその他のアセットは、ESMの import を使ってインポートすることができ、最終的にビルドされたアセットへのURLリファレンスを返します。これは、JS以外のアセットをURLで参照する場合に便利です。たとえば、画像要素を作成して、その画像を指すsrc属性を指定できます。

また、ディレクトリ構造で説明されているように、画像はpublic/フォルダに配置するのも便利です。

?urlや?rawなど、Viteのインポートパラメータを追加する方法については、Viteの静的アセットの取り扱いガイドを参照してください。

ノート

アクセシビリティの観点から、<img>タグにaltテキストを付加することが推奨されています！画像要素にalt="役に立つ説明"属性を追加することを忘れないでください。画像が単なる装飾である場合は、この属性を空で指定します。

importエイリアス

エイリアスは、インポートのためのショートカットを作成する方法です。

エイリアスは、多くのディレクトリや相対的なインポートを持つコードベースにおいて、開発体験を改善するのに役立ちます。

src/pages/about/company.astro

---
import Button from '../../components/controls/Button.astro';
import logoUrl from '../../assets/logo.png?url';
---

この例では、開発者はsrc/pages/about/company.astro、src/components/controls/Button.astro、そしてsrc/assets/logo.png間のツリーの関係を理解する必要があります。そして、company.astroファイルが移動された場合、これらのインポートも更新しなければなりません。

インポートエイリアスはtsconfig.jsonから追加できます。

tsconfig.json

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

設定を変更すると、開発サーバーが自動的に再起動します。これにより、プロジェクト内の任意の場所でエイリアスを使用してインポートできます。

src/pages/about/company.astro

---
import Button from '@components/controls/Button.astro';
import logoUrl from '@assets/logo.png?url';
---

import.meta.glob()

Viteのimport.meta.glob()は、globパターンで多数のファイルを一度にインポートする方法です。

import.meta.glob()は、インポートしたいローカルファイルを示すglobパターンを引数として受け取ります。戻り値は、マッチしたファイルのパスをキーとするオブジェクトです。モジュールを同期的に読み込むには、第2引数に{ eager: true }を渡します。

src/components/my-component.astro

---
// `./src/pages/post/`内の`.md`で終わるすべてのファイルをインポート
const matches = import.meta.glob('../pages/post/*.md', { eager: true });
const posts = Object.values(matches);
---
<!-- ブログ投稿の最初の5つを<article>としてレンダリングする -->
<div>
{posts.slice(0, 4).map((post) => (
  <article>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
    <a href={post.url}>もっと読む</a>
  </article>
))}
</div>

import.meta.globでインポートしたAstroコンポーネントは、AstroInstance型です。各コンポーネントのインスタンスは、そのdefaultプロパティでレンダリングできます。

src/pages/component-library.astro

---
// `./src/components/`内の`.astro`で終わるすべてのファイルをインポート
const components = Object.values(import.meta.glob('../components/*.astro', { eager: true }));
---
<!-- すべてのコンポーネントを表示 -->
{components.map((component) => (
  <div>
    <component.default size={24} />
  </div>
))}

サポートされる値

Viteのimport.meta.glob()は静的な文字列リテラルのみをサポートし、動的な変数や文字列補間は使えません。

回避策として、必要なファイルをすべて含む、より広いパターンを指定しておいて、あとから絞り込む方法があります。

src/components/featured.astro

---
const { postSlug } = Astro.props;
const pathToMyFeaturedPost = `src/pages/blog/${postSlug}.md`;

const posts = Object.values(import.meta.glob("../pages/blog/*.md", { eager: true }));
const myFeaturedPost = posts.find(post => post.file.includes(pathToMyFeaturedPost));
---

<p>
  お気に入りの投稿をみてください！ <a href={myFeaturedPost.url}>{myFeaturedPost.frontmatter.title}</a>
</p>

インポート時の型ユーティリティ

Markdownファイル

import.meta.glob()で読み込まれたMarkdownファイルは、MarkdownInstanceインターフェースを持ちます。

export interface MarkdownInstance<T extends Record<string, any>> {
  /* YAML/TOMLフロントマターで指定されたデータ */
  frontmatter: T;
  /* ファイルの絶対パス */
  file: string;
  /* ファイルのレンダリング後のパス */
  url: string | undefined;
  /* ファイルの内容をレンダリングするAstroコンポーネント */
  Content: AstroComponentFactory;
  /** （Markdownのみ）レイアウトHTMLとYAML/TOMLフロントマターを除く生のMarkdownコンテンツ */
  rawContent(): string;
  /** （Markdownのみ）レイアウトHTMLを除いたHTMLにコンパイル済みのMarkdown */
  compiledContent(): string;
  /* ファイル内の h1〜h6 要素の配列を返す関数 */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
  default: AstroComponentFactory;
}

TypeScriptのジェネリクスを使って、frontmatter変数に型を指定できます。

---
import type { MarkdownInstance } from 'astro';
interface Frontmatter {
  title: string;
  description?: string;
}

const posts = Object.values(import.meta.glob<MarkdownInstance<Frontmatter>>('./posts/**/*.md', { eager: true }));
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
</ul>

Astroファイル

Astroファイルは次のインターフェースを持ちます。

export interface AstroInstance {
  /* ファイルのパス */
  file: string;
  /* ファイルのURL（pagesディレクトリにある場合） */
  url: string | undefined;
  default: AstroComponentFactory;
}

その他のファイル

その他のファイルのインターフェースはさまざまですが、ファイルの中身が分かっている場合は、import.meta.glob() にTypeScriptのジェネリクスを指定できます。

---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = import.meta.glob<CustomDataFile>('../data/**/*.js');
---

globパターン

globパターンは、特殊なワイルドカード文字をサポートするファイルパスです。プロジェクト内の複数のファイルを一度に参照する場合に使用します。

たとえば、globパターン./pages/**/*.{md,mdx}は、pagesサブディレクトリで始まり、そのサブディレクトリをすべて調べ（/**）、 ファイル名（/*）が.mdまたは.mdxで終わる（.{md,mdx})ファイルにマッチします。

Astroにおけるglobパターン

import.meta.glob()を使用する場合、引数として指定するglobパターンは文字列リテラルである必要があり、変数を含むことはできません。

また、globパターンは、以下のいずれかで始まる必要があります。

• ./（カレントディレクトリを基準にする）
• ../（親ディレクトリを基準にする）
• /（プロジェクトのルートを基準にする）

globパターンの構文の詳細はpicomatchのリポジトリをご覧ください。

import.meta.glob()とgetCollection()

コンテンツコレクションは、複数ファイルの読み込みにimport.meta.glob()の代わりとなるgetCollection() API (EN)を提供します。Markdown/MDX/Markdocなどのコンテンツファイルがsrc/content/配下のコレクションにある場合は、getCollection()を使ってコレクションをクエリし、コンテンツを取得します。

WASM

// 要求されたWASMファイルをロードして初期化する
const wasm = await WebAssembly.instantiateStreaming(fetch('/example.wasm'));

Astroは、ブラウザのWebAssembly APIを使用して、WASMファイルをアプリケーションに直接読み込むことをサポートしています。

Nodeビルトイン

AstroはNode.jsのビルトインを、いくつかの制限付きでnode:プレフィックス経由でサポートします。開発と本番で挙動が異なる場合や、オンデマンドレンダリングと互換性がない機能もあります。いくつかのアダプターは、これらのビルトインと互換性がない、または一部のみサポートするための設定が必要な場合があります（例: Cloudflare Workers、Deno）。

次の例では、Nodeのutilモジュールを読み込み、MIMEタイプを解析しています。

src/components/MyComponent.astro

---
// 例: Node.jsの "util" ビルトインをインポート
import util from 'node:util';

export interface Props {
  mimeType: string,
}

const mime = new util.MIMEType(Astro.props.mimeType)
---

<span>Type: {mime.type}</span>
<span>SubType: {mime.subtype}</span>

ファイル形式のサポートを拡張

Viteと互換性のあるRollupプラグインを使用すると、Astroがネイティブでサポートしていないファイル形式をインポートできます。必要なプラグインがどこにあるかは、Viteドキュメントのプラグインの検索セクションを参照してください。

プラグイン設定

設定オプションや正しいインストール方法については、プラグインのドキュメントを参照してください。

関連レシピ： ViteまたはRollupプラグインをインストールする