CLIコマンド

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

`astro`コマンド

好みのパッケージマネージャーによりこのページで説明されているコマンドのいずれかを実行し、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 TypeScript types for all Astro modules.
      preferences  Configure user preferences.
        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 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 dev`

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

`astro build`

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

下記の共通のフラグと組み合わせられます。

`astro preview`

astro buildの実行により作成される静的ディレクトリ（デフォルトではdist/）のコンテンツを配信するためのローカルサーバーを起動します。

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

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

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

`astro check`

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

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

フラグ

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

`--watch`

プロジェクトの変更を監視し、エラーを報告します。

`--root <path-to-dir>`

異なるルートディレクトリを指定します。デフォルトでは現在の作業ディレクトリを使用します。

`--tsconfig <path-to-file>`

手動でtsconfig.jsonファイルを指定します。指定しない場合、Astroは設定を探すか、プロジェクトの設定を自動的に推測します。

`--minimumFailingSeverity <error|warning|hint>`

コマンドを終了するために必要な最小の重要度を指定します。デフォルトはerrorです。

たとえばastro check --minimumFailingSeverity warningを実行すると、警告が検出された場合にコマンドがエラーで終了します。

`--minimumSeverity <error|warning|hint>`

出力される最小の重要度を指定します。デフォルトはhintです。

たとえばastro check --minimumSeverity warningを実行すると、エラーと警告が表示されますが、ヒントは表示されません。

`--preserveWatchOutput`

ウォッチモードでチェックしている間、出力をクリアしないように指定します。

`--noSync`

プロジェクトをチェックする前にastro syncを実行しないように指定します。

詳しくはAstroの型チェックを確認してください。

`astro sync`

追加： astro@2.0.0

すべてのAstroモジュールに対してTypeScriptの型を生成します。これにより、型推論に使用するsrc/env.d.tsファイルが設定され、生成される型に依存する機能のモジュールが定義されます。

コンテンツコレクションAPIのためのastro:contentモジュール
Astro DB (EN)のためのastro:dbモジュール
実験的なAstro Envのためのastro:envモジュール
Astroアクション (EN)のためのastro:actionsモジュール

`astro add`

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

`astro docs`

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

`astro info`

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

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 preferences`

ユーザー設定はastro preferencesコマンドで管理します。ユーザーの設定はAstroの個々のユーザーに固有です。プロジェクトで作業するすべての人に影響するastro.config.mjsファイルとは異なります。

ユーザー設定はデフォルトで現在のプロジェクトにスコープされ、ローカルの.astro/settings.jsonファイルに保存されます。

--globalフラグを使用すると、ユーザー設定を現在のマシン上のすべてのAstroプロジェクトに適用できます。グローバルユーザー設定は、オペレーティングシステム固有の場所に保存されます。

設定可能な値

devToolbar — ブラウザ内の開発ツールバーを有効化または無効化します。（デフォルトはtrue）
checkUpdates — Astro CLIの自動更新チェックを有効化または無効化します。（デフォルトはtrue）

listコマンドは、設定可能なすべてのユーザー設定の現在値を出力します。機械可読な--json出力もサポートしています。

astro preferences list

ターミナル出力の例:

設定	値
devToolbar.enabled	true
checkUpdates.enabled	true

設定をenable、disable、またはデフォルト値にresetできます。

たとえば、特定のAstroプロジェクトで開発ツールバーを無効にするには以下のようにします。

astro preferences disable devToolbar

現在のマシン上のすべてのAstroプロジェクトで開発ツールバーを無効にするには以下のようにします。

astro preferences disable --global devToolbar

あとで開発ツールバーを有効にするには以下のようにします。

astro preferences enable devToolbar

resetコマンドは設定をデフォルト値にリセットします。

astro preferences reset devToolbar

`astro telemetry`

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

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

astro telemetry disable

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

astro telemetry enable

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

astro telemetry reset

共通のフラグ

`--root <path>`

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

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

astro --root myRootFolder/myProjectFolder dev

`--config <path>`

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

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

`--outDir <path>`

追加： astro@3.3.0

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

`--site <url>`

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

`--base <pathname>`

追加： astro@1.4.1

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

`--port <ポート番号>`

どのポートで開発サーバーとプレビューサーバーを起動するかを指定します。デフォルト値は4321です。

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

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

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

`--verbose`

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

`--silent`

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

グローバルのフラグ

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

`--version`

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

`--open`

サーバーの起動時に自動的にブラウザでアプリを開きます。開く対象のURLを指定するために、完全なURL文字列（たとえば--open http://example.com）またはpathname（たとえば--open /about）を指定できます。

`--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,mts)ファイルを検索し、設定ファイルが見つかればそれを読み込みます。

相対パスが設定されている場合、rootオプションを基準として解決されます。

設定ファイルの読み込みを無効にするには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) => Promise<DevServer>

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

import { dev } from "astro";

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

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

`DevServer`

export interface DevServer {
  address: AddressInfo;
  handle: (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void;
  watcher: vite.FSWatcher;
  stop(): Promise<void>;
}

`address`

開発サーバーがリッスンしているアドレスです。

このプロパティには、Nodeのnet.Server#address()メソッドによって返される値が含まれます。

`handle()`

生のNode HTTPリクエストのハンドルです。ネットワークを介してリクエストを送信する代わりに、handle()をhttp.IncomingMessageとhttp.ServerResponseと共に呼び出すことができます。

`watcher`

Viteの開発サーバーによって公開されるChokidarのファイルウォッチャーです。

`stop()`

開発サーバーを停止します。すべてのアイドル状態の接続を閉じ、新しい接続のリッスンを停止します。

保留中のリクエストがすべてfullfillされ、すべてのアイドル状態の接続が閉じられると解決するPromiseを返します。

`build()`

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

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

import { build } from "astro";

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

`preview()`

データ型: (inlineConfig: AstroInlineConfig) => Promise<PreviewServer>

astro previewと同様に、ビルド出力を配信するためのローカルサーバーを起動します。

アダプターが設定されていない場合、プレビューサーバーはビルドされた静的ファイルのみを配信します。アダプターが設定されている場合、プレビューサーバーはアダプターによって提供されます。アダプターはプレビューサーバーを提供する必要はないため、選択したアダプターによってはこの機能が利用できない場合があります。

import { preview } from "astro";

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

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

`PreviewServer`

export interface PreviewServer {
  host?: string;
  port: number;
  closed(): Promise<void>;
  stop(): Promise<void>;
}

`host`

サーバーが接続をリッスンしているホストです。

アダプターはこのフィールドを設定しない場合があります。hostの値は実装に依存します。

`port`

サーバーが接続をリッスンしているポートです。

`stop()`

プレビューサーバーをクローズし、リクエストの受け入れを停止し、アイドル状態の接続を切断するように要求します。

返されるPromiseは、クローズリクエストが送信されると解決します。これはサーバーがクローズしたことを意味しません。サーバーが完全にクローズされたことを確認する必要がある場合は、closed()メソッドを使用してください。

`closed()`

サーバーがクローズされると解決し、サーバーでエラーが発生した場合はリジェクトするPromiseを返します。

`sync()`

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

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

import { sync } from "astro";

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

貢献する

コミュニティ

CLIコマンド

astroコマンド

package.jsonスクリプト

astro dev

astro build

astro preview

astro check

フラグ

--watch

--root <path-to-dir>

--tsconfig <path-to-file>

--minimumFailingSeverity <error|warning|hint>

--minimumSeverity <error|warning|hint>

--preserveWatchOutput

--noSync

astro sync

astro add

astro docs

astro info

astro preferences

設定可能な値

astro telemetry

共通のフラグ

--root <path>

--config <path>

--outDir <path>

--site <url>

--base <pathname>

--port <ポート番号>

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

--verbose

--silent

グローバルのフラグ

--version

--open

--help

高度なAPI（実験的）

AstroInlineConfig

configFile

mode

logLevel

dev()

DevServer

address

handle()

watcher

stop()

build()

preview()

PreviewServer

host

port

stop()

closed()

sync()

`astro`コマンド

`package.json`スクリプト

`astro dev`

`astro build`

`astro preview`

`astro check`

`--watch`

`--root <path-to-dir>`

`--tsconfig <path-to-file>`

`--minimumFailingSeverity <error|warning|hint>`

`--minimumSeverity <error|warning|hint>`

`--preserveWatchOutput`

`--noSync`

`astro sync`

`astro add`

`astro docs`

`astro info`

`astro preferences`

`astro telemetry`

`--root <path>`

`--config <path>`

`--outDir <path>`

`--site <url>`

`--base <pathname>`

`--port <ポート番号>`

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

`--verbose`

`--silent`

`--version`

`--open`

`--help`

`AstroInlineConfig`

`configFile`

`mode`

`logLevel`

`dev()`

`DevServer`

`address`

`handle()`

`watcher`

`stop()`

`build()`

`preview()`

`PreviewServer`

`host`

`port`

`stop()`

`closed()`

`sync()`