インポート

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

対応するファイル形式

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

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

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

`public/`内のファイル

プロジェクトのpublic/ディレクトリには、任意の静的アセットを置けます。Astroはそれをそのまま最終ビルドとして直接コピーします。HTMLテンプレートの中では、public/内のファイルをURLパスで直接参照できます。

Import構文

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

JavaScript

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

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

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ファイルをインポートする際に.tsと.tsxのファイル拡張子を使用するべきではありません。代わりに、.js/.jsxというファイル拡張子を使うか、ファイル拡張子を完全に省略する必要があります。

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

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

JSX / TSX

import { MyComponent } from './MyComponent.jsx';

Astroには、プロジェクトにJSX（*.jsxと*.tsx）ファイルのサポートが組み込まれています。JSXの構文は、自動的にJavaScriptにトランスパイルされます。

AstroはJSX構文を標準で理解できますが、React、Preact、Solidなどのフレームワークを適切にレンダリングするには、フレームワークのインテグレーションをインストールする必要があります。詳しくは、インテグレーションガイドをご覧ください。

npmパッケージ

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

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

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

JSON

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

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

CSS

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

Astroは、CSSファイルをアプリケーションに直接インポートできます。インポートされたスタイルはエクスポートされませんが、インポートすることで自動的にそれらのスタイルがページに追加されます。これはデフォルトですべてのCSSファイルに対して機能し、プラグインによってSassやLessのようなコンパイル可能な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モジュールは、スタイルシートのために一意に生成されたクラス名によって、フロントエンドでコンポーネントのスコープと分離を強制するのに役立ちます。

その他のアセット

import imgReference from './image.png'; // img === '/src/image.png'
import svgReference from './image.svg'; // svg === '/src/image.svg'
import txtReference from './words.txt'; // txt === '/src/words.txt'

// この例ではJSXを使用していますが、どのようなフレームワークでもインポート参照を使用できます。
<img src={imgReference.src} alt="画像の説明" />;

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

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

importエイリアス

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

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

---
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またはjsconfig.jsonのどちらかから追加できます。

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

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

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

これらのエイリアスは、VS Codeや他のエディタにも自動的に統合されます。

`Astro.glob()`

Astro.glob()は、多数のファイルを一度にインポートするための方法です。

Astro.glob()は、インポートしたいローカルファイルと一致する相対globパターンを1つのパラメータとして受け取るだけです。これは非同期で、マッチした各ファイルのエクスポートを配列で返します。

---
// `./src/pages/post/`の`.md`で終わるすべてのファイルをインポート
const posts = await Astro.glob('../pages/post/*.md');
---
<!-- ブログ投稿の最初の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>

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

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

globパターン

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

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

Astroのglobパターン

Astro.glob()で使用する場合、globパターンは文字列リテラルである必要があり、変数を含むことはできません。回避策については、トラブルシューティングガイドを参照してください。

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

./ （カレントディレクトリで起動する）
../ （親ディレクトリから開始する場合）
/ （プロジェクトのルートから開始する場合）

globパターンの構文について、詳しくはこちらをご覧ください。

`Astro.glob()`と`getCollection()`

コンテンツコレクションは、Astro.glob()の代わりに複数のファイルを読み込むためのgetCollection() APIを提供します。コンテンツファイル（Markdown、MDX、Markdocなど）がsrc/content/ディレクトリ内のコレクションに配置されている場合、getCollection()を使用してコレクションのクエリを行い、コンテンツのエントリーを返します。

WASM

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

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

Nodeビルトイン

Astroのユーザーには、可能な限りNode.jsのビルトイン（fs、pathなど）を避けることをおすすめします。Astroは、アダプターを使用して複数のランタイムと互換性があります。これには、fsなどのNodeビルトインモジュールをサポートしないDenoやCloudflare Workersが含まれます。

私たちの目的は、一般的なNode.jsのビルトインに対するAstroの代替機能を提供することです。しかし、今のところそのような代替機能は存在しません。ですから、もし本当にこれらのビルトインモジュールを使う必要があるのなら、それを止めたいとは思いません。AstroはNode.jsのビルトインを、Nodeの新しいプレフィックスであるnode:を使ってサポートしています。たとえば、ファイルを読み込む場合、次のようにします。

---
// 例: Node.js から "fs/promises" ビルトインをインポートします。
import fs from 'node:fs/promises';

const url = new URL('../../package.json', import.meta.url);
const json = await fs.readFile(url, 'utf-8');
const data = JSON.parse(json);
---

<span>Version: {data.version}</span>

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

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

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

GitHub Issueを作成

フィードバックを送信

インポート

対応するファイル形式

`public/`内のファイル

Import構文

JavaScript

TypeScript

JSX / TSX

npmパッケージ

JSON

CSS

CSSモジュール

その他のアセット

importエイリアス

`Astro.glob()`

globパターン

Astroのglobパターン

`Astro.glob()`と`getCollection()`

WASM

Nodeビルトイン

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

インポート

対応するファイル形式

public/内のファイル

Import構文

JavaScript

TypeScript

JSX / TSX

npmパッケージ

JSON

CSS

CSSモジュール

その他のアセット

importエイリアス

Astro.glob()

globパターン

Astroのglobパターン

Astro.glob()とgetCollection()

WASM

Nodeビルトイン

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

`public/`内のファイル

`Astro.glob()`

`Astro.glob()`と`getCollection()`