コンテンツにスキップ

CLIコマンド

Astro が提供するコマンドラインインターフェイス(CLI)を使用して、ターミナルウィンドウからプロジェクトの開発、ビルド、およびプレビューができます。

astroコマンド

好みのパッケージマネージャーによりこのページで説明されているコマンドのいずれかを実行し、CLIを使用します。オプションでフラグも指定できます。フラグはコマンドの動作をカスタマイズします。

最もよく使用するコマンドの1つはastro devです。このコマンドは開発サーバーを起動し、ブラウザで作業中のサイトのライブプレビューを提供します。

Terminal window
# 開発サーバーを起動する
npx astro dev

ターミナルでastro --helpと入力すると、利用可能なすべてのコマンドのリストが表示されます。

Terminal window
npx astro --help

ターミナルには以下のメッセージが表示されます。

Terminal window
astro [command] [...flags]
Commands
add Add an integration.
build Build your project and write it to disk.
check Check your project for errors.
dev Start the development server.
docs Open documentation in your web browser.
info List info about your current Astro setup.
preview Preview your build locally.
sync Generate content collection types.
telemetry Configure telemetry settings.
Global Flags
--config <path> Specify your config file.
--root <path> Specify your project root folder.
--site <url> Specify your project site.
--base <pathname> Specify your project base.
--verbose Enable verbose logging.
--silent Disable all logging.
--version Show the version number and exit.
--open Open the app in the browser on server start.
--help Show this help message.

package.jsonスクリプト

これらのコマンドの短縮版としてpackage.jsonのスクリプトも使用できます。スクリプトにより、他のプロジェクトでよく見るnpm run buildのようなコマンドを使用できます。

最もよく使うastroコマンド(astro devastro buildastro preview)に対応する以下のスクリプトは、create astroウィザードを使用してプロジェクトを作成すると自動的に追加されます。

手動でAstroをインストールする手順に従うと、これらのスクリプトを自分で追加するよう促されます。また、このリストにその他のよく使用するコマンド用のスクリプトを手動で追加することもできます。

package.json
{
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "astro build",
"preview": "astro preview"
}
}

これらのastroコマンド、またはそれらを実行するスクリプトは、フラグなしで使用することが多いですが、コマンドの動作をカスタマイズしたい場合はコマンドにフラグを追加します。たとえば、開発サーバーを別のポートで起動したり、サイトをビルドする際にデバッグ用に詳細なログを出力したりできます。

Terminal window
# `package.json`の`start`スクリプトを使用して、ポート8080で開発サーバーを起動する
npm run start -- --port 8080
# `package.json`の`build`スクリプトを使用して、サイトのビルド時に詳細なログを出力する
npm run build -- --verbose

astro dev

Astroの開発サーバーを起動します。これはアセットをバンドルしないローカルのHTTPサーバーです。ホットモジュールリプレースメント(HMR)を使用して、エディターで変更を保存した際にブラウザを更新します。

フラグ

Astroの開発サーバーの動作をカスタマイズするために以下のフラグを使用してください。他のAstroのコマンドと共通しているフラグについては、下記の共通のフラグを確認してください。

--port <ポート番号>

どのポートで起動するかを指定します。デフォルト値は4321です。

--host [オプションのホストアドレス]

開発サーバーがリッスンするネットワークIPアドレス、たとえばlocalhost以外のIPアドレスなどを設定します。これは開発時に携帯電話などのローカルの端末でプロジェクトをテストする際に便利です。

  • --host - LANやパブリックのアドレスを含むすべてのアドレスでリッスンします
  • --host <カスタムアドレス> - <カスタムアドレス>のネットワークIPアドレスで公開します

astro build

サイトをデプロイ用にビルドします。デフォルトでは、静的ファイルを生成しdist/ディレクトリに配置します。SSRが有効な場合には、サイトに必要なサーバーのファイルを生成します。

フラグ

ビルドをカスタマイズするために以下のフラグを使用してください。他のAstroのコマンドと共通しているフラグについては、下記の共通のフラグを確認してください。

astro preview

静的なdist/ディレクトリを配信するためのローカルサーバーを起動します。

このコマンドはデプロイ前に静的ビルドをローカルでプレビューする際に便利です。本番環境で実行するようには設計されていません。本番環境のホスティングについて知りたい場合は、Astroウェブサイトをデプロイするためのガイドを確認してください。

Astro 1.5.0から、アダプターがサポートしている場合はSSRビルドに対してもastro previewを使えます。現在、Nodeアダプター (EN)のみastro previewをサポートしています。

下記の共通のフラグと組み合わせることができます。

astro check

プロジェクトに対して診断機能(.astroファイル内の型チェックなど)を実行し、コンソールにエラーを報告します。もし何かエラーがあれば、終了ステータス1でプロセスが終了します。

このコマンドはCIワークフローで使用されることを想定しています。

フラグ

コマンドの動作をカスタマイズするために以下のフラグを使用してください。

--watch

.astroファイルへの変更を監視し、エラーを報告します。

📚 詳しくはAstroのTypeScriptサポートを確認してください。

astro sync

追加: astro@2.0.0

すべてのAstroモジュールに対してTypeScriptの型を生成します。これにより、型推論に使用するsrc/env.d.tsファイルが設定され、コンテンツコレクションAPIのためのastro:contentモジュールが定義されます。

astro add

設定ファイルにインテグレーションを追加します。詳しくはインテグレーションガイドを確認してください。

astro docs

ターミナルからAstroのドキュメントサイトを直接起動します。

astro info

現在のAstro環境に関する重要な情報を報告します。Issueを開く際の情報提供に便利です。

Terminal window
astro info

以下は出力例です。

Astro v3.0.12
Node v20.5.1
System macOS (arm64)
Package Manager pnpm
Output server
Adapter @astrojs/vercel/serverless
Integrations none

astro telemetry

現在のCLIのユーザーに対してテレメトリーの設定をおこないます。テレメトリーは、Astroのどの機能がもっともよく使われているかをAstroチームに提供するための匿名のデータです。

テレメトリーは以下のCLIコマンドで無効にできます。

Terminal window
astro telemetry disable

テレメトリーは次のコマンドにより再び有効にできます。

Terminal window
astro telemetry enable

clearコマンドはテレメトリーのデータをリセットします。

Terminal window
astro telemetry clear

共通のフラグ

--root <path>

プロジェクトルートのパスを指定します。もし何も指定されなければ現在の作業ディレクトリがルートとみなされます。

ルートはAstroの設定ファイルを見つけるために使用されます。

Terminal window
astro --root myRootFolder/myProjectFolder dev

--config <path>

プロジェクトルートからの相対パスで設定ファイルのパスを指定します。デフォルト値はastro.config.mjsです。異なる名前の設定ファイルを使用する場合や別のフォルダに設定ファイルがある場合はこのフラグを使用してください。

Terminal window
astro --config config/astro.config.mjs dev

--site <url>

プロジェクトのsiteを設定します。このフラグを渡すと、astro.config.mjsファイルのsiteの値が上書きされます。

--base <pathname>

追加: astro@1.4.1

プロジェクトのbaseを設定します。このフラグを渡すと、astro.config.mjsファイルのbaseの値が上書きされます。

--verbose

詳細なログを有効にします。これは問題をデバッグするのに有用です。

--silent

サイレントなロギングを有効にし、コンソールの出力なしでサーバーが実行されます。

グローバルのフラグ

astroのCLIについての情報を取得するために以下のフラグを使用してください。

--version

Astroのバージョン番号を出力し、終了します。

--open

サーバーの起動時に自動的にブラウザでアプリを開きます。

--help

ヘルプメッセージを出力し、終了します。

高度なAPI(実験的)

Astroを実行する際により細かな制御が必要な場合のために、"astro"パッケージはCLIコマンドをプログラムで実行するためのAPIもエクスポートしています。

これらのAPIは実験的であり、APIのシグネチャは変更される可能性があります。更新情報はAstroの変更履歴に記載されており、以下の情報は常に現在の最新情報を表示しています。

AstroInlineConfig

AstroInlineConfig型は以下のすべてのコマンドAPIで使用されます。これはユーザーのAstro設定型の拡張です。

interface AstroInlineConfig extends AstroUserConfig {
configFile?: string | false;
mode?: "development" | "production";
logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}

configFile

データ型: string | false
デフォルト値: undefined

Astro設定ファイルへのカスタムパスです。

この値がundefind(デフォルト)であるか設定されていない場合、Astroはrootを起点としてastro.config.(js,mjs,ts)ファイルを検索し、設定ファイルが見つかればそれを読み込みます。

相対パスが設定されている場合、現在の作業ディレクトリを基準として解決されます。

設定ファイルの読み込みを無効にするにはfalseを設定します。

このオブジェクトに渡されたインライン設定は、読み込まれた他のユーザー設定とマージされる際に最優先されます。

mode

データ型: "development" | "production"
デフォルト値: astro devの実行時は"development"astro buildの実行時は"production"

サイトをビルドする際に使用されるモードで、“development”または”production”のコードを生成します。

logLevel

データ型: "debug" | "info" | "warn" | "error" | "silent"
デフォルト値: "info"

Astroが出力するログメッセージをフィルタリングするためのログレベルです。

  • "debug": ノイズを含むデバッグ用の情報とともにすべてのログを出力します。
  • "info": 情報メッセージ、警告、エラーをログに出力します。
  • "warn": 警告とエラーをログに出力します。
  • "error": エラーのみをログに出力します。
  • "silent": ログを出力しません。

dev()

データ型: (inlineConfig: AstroInlineConfig) => AstroDevServer

astro devと同様に、Astroの開発サーバーを実行します。

import { dev } from "astro";
const devServer = await dev({
root: "./my-project",
});
// 必要に応じてサーバーを停止する
await devServer.stop();

build()

データ型: (inlineConfig: AstroInlineConfig) => void

astro buildと同様に、サイトをデプロイ用にビルドします。

import { build } from "astro";
await build({
root: "./my-project",
});

preview()

データ型: (inlineConfig: AstroInlineConfig) => AstroPreviewServer

astro previewと同様に、静的なdist/ディレクトリを配信するためのローカルサーバーを起動します。

import { preview } from "astro";
const previewServer = await preview({
root: "./my-project",
});
// 必要に応じてサーバーを停止する
await previewServer.stop();

sync()

データ型: (inlineConfig: AstroInlineConfig) => number

astro syncと同様に、すべてのAstroモジュールに対してTypeScriptの型を生成します。

import { sync } from "astro";
const exitCode = await sync({
root: "./my-project",
});
process.exit(exitCode)