CLIコマンド

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

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

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

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

# 開発サーバーを起動する
pnpm astro dev

# 開発サーバーを起動する
yarn astro dev

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

npx astro --help

pnpm astro --help

yarn astro --help

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

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のスクリプトも使用できます。スクリプトにより、他のプロジェクトでよく見るnpm run buildのようなコマンドを使用できます。

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

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

{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}

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

# `package.json`の`start`スクリプトを使用して、ポート8080で開発サーバーを起動する
npm run start -- --port 8080

# `package.json`の`build`スクリプトを使用して、サイトのビルド時に詳細なログを出力する
npm run build -- --verbose

# `package.json`の`start`スクリプトを使用して、ポート8080で開発サーバーを起動する
pnpm start --port 8080

# `package.json`の`build`スクリプトを使用して、サイトのビルド時に詳細なログを出力する
pnpm build --verbose

# `package.json`の`start`スクリプトを使用して、ポート8080で開発サーバーを起動する
yarn start --port 8080

# `package.json`の`build`スクリプトを使用して、サイトのビルド時に詳細なログを出力する
yarn build --verbose

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

フラグ

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

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

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

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

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

フラグ

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

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

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

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

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

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

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

フラグ

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

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

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

追加: astro@2.0.0

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

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

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

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

astro info

以下は出力例です。

Astro version            v2.6.6
Package manager          pnpm
Platform                 darwin
Architecture             arm64
Adapter                  @astrojs/vercel/serverless
Integrations             None or couldn't determine.

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

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

astro telemetry disable

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

astro telemetry enable

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

astro telemetry clear

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

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

astro --root myRootFolder/myProjectFolder dev

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

astro --config config/astro.config.mjs dev

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

import { dev } from "astro";

const devServer = await dev({
  root: "./my-project",
});

// 必要に応じてサーバーを停止する
await devServer.stop();

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

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

import { build } from "astro";

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

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

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

import { preview } from "astro";

const previewServer = await preview({
  root: "./my-project",
});

// 必要に応じてサーバーを停止する
await previewServer.stop();

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

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

import { sync } from "astro";

const exitCode = await sync({
  root: "./my-project",
});

process.exit(exitCode)