TypeScript

AstroにはTypeScriptのサポートが組み込まれています。Astroプロジェクトで.tsや.tsxファイルをインポートしたり、Astroコンポーネントの中で直接TypeScriptコードを書いたり、お好みでastro.config.tsファイルを使うこともできます。

TypeScriptにより、オブジェクトやコンポーネントの形状（shape）をコードで定義して実行時エラーを防ぐことができます。たとえば、TypeScriptでコンポーネントのpropsに型を付けると、コンポーネントが受け付けないpropを設定した場合にエディタ内にエラーが発生します。

AstroプロジェクトでTypeScriptコードを書かなくても、その恩恵を受けられます。Astroは常にコンポーネントのコードをTypeScriptとして扱い、Astro VSCode拡張機能は自動補完やヒント、エラーをエディタ内で提供するためにできる限りの推論を行います。

Astroの開発サーバーは型チェックを行いませんが、スクリプトの追加によりコマンドラインから型エラーをチェックできます。

Astroのスタータープロジェクトにはtsconfig.jsonファイルが含まれています。TypeScriptコードを書かない場合でも、AstroやVS Codeなどのツールがプロジェクトを理解するために、このファイルは重要です。tsconfig.jsonファイルがないと、npmパッケージのインポートなどの一部の機能がエディタで完全にサポートされません。Astroを手動でインストールする場合は、必ずこのファイルを自分で作成してください。

Astroには、base、strict、strictestという3つの拡張可能なtsconfig.jsonのテンプレートが含まれています。baseテンプレートは、JavaScriptのモダンな機能のサポートを可能とし、他のテンプレートの基礎としても使用されます。プロジェクトでTypeScriptを書く予定がある場合は、strictまたはstrictestを使用することをお勧めします。astro/tsconfigs/で3つのテンプレートの設定を確認・比較できます。

いずれかのテンプレートを継承するには、extendsという設定項目を使用します。

{
  "extends": "astro/tsconfigs/base"
}

また、Viteのクライアント型をプロジェクトで利用できるように、テンプレートにはsrcフォルダ内にenv.d.tsが含まれています。

/// <reference types="astro/client" />

プロジェクトでUIフレームワークを使用する場合は、フレームワークに応じた追加の設定が必要かもしれません。詳細については、フレームワークのTypeScriptドキュメントを参照してください。 (Vue、React、Preact、Solid)

可能な限り、明示的な型のインポートとエクスポートを使用しましょう。

import { SomeType } from './script';
import type { SomeType } from './script';

こうすることで、Astroのバンドラーがインポートした型をJavaScriptであるかのように誤ってバンドルするようなエッジケースを避けることができます。

.tsconfigファイルで、TypeScriptにこれを補助させることができます。importsNotUsedAsValuesをerrorにセットすることで、TypeScriptはインポートをチェックし、いつimport typeを使うべきか教えてくれるのです。この設定は、strictとstrictestテンプレートにデフォルトで含まれています。

{
  "compilerOptions": {
    "importsNotUsedAsValues": "error",
  }
}

Astroは、tsconfig.jsonとjsconfig.jsonのpaths設定で定義するimportエイリアスをサポートしています。詳しくはガイドをご覧ください。

---
import HelloWorld from '@components/HelloWorld.astro';
import Layout from '@layouts/Layout.astro';
---

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

AstroはTypeScriptによるコンポーネントpropsの型付けをサポートしています。有効にするには、コンポーネントのfrontmatterにTypeScriptのPropsインターフェースを追加します。export文を使用することもできますが、必須ではありません。Astro VSCode拡張機能は、Propsインターフェースを自動的に探し、そのコンポーネントを他のテンプレート内で使用するときに適切なTSサポートを提供します。

---
interface Props {
  name: string;
  greeting?: string;
}
const { greeting = 'Hello', name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

• コンポーネントがpropsやスロット経由のコンテンツを受け取らない場合は、type Props = Record<string, unknown>を使用できます。

• コンポーネントがデフォルトスロットから子要素を受け取る必要がある場合は、type Props = { children: any; };によりこれを強制できます。

Astroには、propsに型を付ける際によく出くわすパターン向けに、組み込みのユーティリティ型を提供しています。これらはastro/typesエントリポイントから利用可能です。

Astroは、マークアップが有効なHTML属性を使用していることを確認するためにHTMLAttributes型を提供しています。この型により、コンポーネントのpropsを構成しやすくなります。

たとえば<Link>コンポーネントを作成する場合、次のようにコンポーネントのprops型に<a>タグのデフォルトHTML属性を反映できます。

---
import { HTMLAttributes } from 'astro/types'
// `type`を使う
type Props = HTMLAttributes<'a'>;
// または`interface`を拡張します
interface Props extends HTMLAttributes<'a'> {
  myProp?: boolean;
}
const { href, ...attrs } = Astro.props;
---
<a href={href} {...attrs}>
  <slot />
</a>

また、.d.tsファイルでastroHTML.JSX名前空間を再宣言し、デフォルトのJSX定義を拡張して非標準の属性を追加することも可能です。

declare namespace astroHTML.JSX {
  interface HTMLAttributes {
    'data-count'?: number;
    'data-label'?: string;
  }
}

エディタで型エラーを確認するには、Astro VS Code拡張機能をインストールしてください。astro startとastro buildコマンドは、esbuildでコードをトランスパイルしますが、型チェックは実行しないことに注意してください。TypeScriptのエラーが含まれている場合にビルドされないようにするには、package.jsonのbuildスクリプトを次のように変更します。

  "scripts": {
    "build": "astro build",
    "build": "astro check && tsc --noEmit && astro build",
  },

📚 Astroにおける.tsファイルのインポートについてもっと読む。 📚 TypeScriptの設定についてもっと読む。

同じプロジェクトで複数のJSXフレームワークを使用する場合、フレームワークごとにtsconfig.json内の設定が異なり、互いにコンフリクトして問題が発生することがあります。

解決策：最も使用するフレームワークに合わせて、jsxImportSource設定をreact（デフォルト）、preactまたはsolid-jsに設定します。次に、競合する異なるフレームワークのファイル内でプラグマコメントを使用します。

デフォルト設定であるjsxImportSource: reactの場合は、次のように使用します。

// Preact向け
/** @jsxImportSource preact */

// Solid向け
/** @jsxImportSource solid-js */