Commandes CLI

Vous pouvez utiliser l’interface en ligne de commande (CLI) fournie par Astro pour développer, construire et prévisualiser votre projet à partir d’une fenêtre de terminal.

Commandes `astro`

Utilisez le CLI en exécutant l’une des commandes documentées sur cette page avec votre gestionnaire de paquets préféré, suivie éventuellement de toutes les options. Les options personnalisent le comportement d’une commande.

L’une des commandes que vous utiliserez le plus souvent est astro dev. Cette commande démarre le serveur de développement et vous donne un aperçu votre site mis à jour en direct dans un navigateur pendant que vous travaillez :

# démarre le serveur de développement
npx astro dev

# démarre le serveur de développement
pnpm astro dev

# démarre le serveur de développement
yarn astro dev

Vous pouvez taper astro --help dans votre terminal pour afficher une liste de toutes les commandes disponibles :

npx astro --help

pnpm astro --help

yarn astro --help

Le message suivant s’affichera dans votre terminal :

astro [commande] [...options]

Commands
              add  Add an integration.
            build  Build your project and write it to disk.
            check  Check your project for errors.
       create-key  Create a cryptography key
              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.
           --help  Show this help message.

Vous pouvez ajouter l’option --help après n’importe quelle commande pour obtenir une liste de toutes les options pour cette commande.

# obtenir une liste de toutes les options pour la commande `dev`
npm run dev -- --help

# obtenir une liste de toutes les options pour la commande `dev`
pnpm dev --help

# obtenir une liste de toutes les options pour la commande `dev`
yarn dev --help

Le message suivant s’affichera dans votre terminal :

astro dev [...flags]

Flags
                 --port  Specify which port to run on. Defaults to 4321.
                 --host  Listen on all addresses, including LAN and public addresses.
--host <custom-address>  Expose on a network IP address at <custom-address>
                 --open  Automatically open the app in the browser on server start
                --force  Clear the content layer cache, forcing a full rebuild.
            --help (-h)  See all available flags.

Scripts `package.json`

Vous pouvez également utiliser des scripts dans package.json pour des versions plus courtes de ces commandes. L’utilisation d’un script vous permet d’utiliser les mêmes commandes avec lesquelles vous pourriez être familier dans d’autres projets, telles que npm run build.

Pour les commandes astro les plus courantes (astro dev, astro build et astro preview), les scripts suivants sont ajoutés automatiquement lorsque vous créez un projet en utilisant l’assistant d’installation create astro.

Lorsque vous suivez les instructions pour installer Astro manuellement, vous êtes invité à ajouter vous-même ces scripts. Vous pouvez également ajouter manuellement d’autres scripts à cette liste pour toute commande que vous utilisez fréquemment.

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

Vous utiliserez souvent ces commandes astro, ou les scripts qui les exécutent, sans aucune option. Ajoutez des options à la commande lorsque vous souhaitez personnaliser le comportement de la commande. Par exemple, vous souhaitez peut-être démarrer le serveur de développement sur un port différent ou Build votre site en incluant les pages de brouillon.

# lance le serveur de développement sur le port 8080 en utilisant le script `start` dans `package.json`
npm run start -- --port 8080

# Build votre site en incluant les pages de brouillon en utilisant le script `build` dans `package.json`
npm run build -- --drafts

# lance le serveur de développement sur le port 8080 en utilisant le script `start` dans `package.json`
pnpm start --port 8080

# Build votre site en incluant les pages de brouillon en utilisant le script `build` dans `package.json`
pnpm build --drafts

# lance le serveur de développement sur le port 8080 en utilisant le script `start` dans `package.json`
yarn start --port 8080

# Build votre site en incluant les pages de brouillon en utilisant le script `build` dans `package.json`
yarn build --drafts

`astro dev`

Lance le serveur de développement d’Astro. Il s’agit d’un serveur HTTP local qui ne regroupe pas les fichiers et les ressources. Il utilise le Remplacement de Modules à Chaud (HMR) pour mettre à jour votre navigateur lorsque vous enregistrez des modifications dans votre éditeur.

`astro build`

Compile votre site pour le déploiement. Par défaut, cela générera des fichiers statiques et les placera dans un répertoire dist/. Si le SSR est activé, cela générera les fichiers serveur nécessaires à votre site.

Peut être combiné avec les options courantes documentées ci-dessous.

`astro preview`

Démarre un serveur local pour servir votre répertoire statique dist/.

Cette commande est utile pour prévisualiser votre Build localement avant de le déployer. Elle n’est pas conçue pour être exécutée en production. Pour obtenir de l’aide sur l’hébergement en production, consultez notre guide sur Déployer un site Astro.

Depuis Astro 1.5.0, astro preview fonctionne également pour les Builds SSR si vous utilisez un adaptateur qui le supporte. Actuellement, seul l’adaptateur Node prend en charge astro preview.

Peut être combiné avec les options courantes documentées ci-dessous.

`astro check`

Lance les diagnostics (comme la vérification de type dans les fichiers .astro) sur votre projet et signale les erreurs à la console. Si des erreurs sont trouvées, le processus se terminera avec un code de 1.

Cette commande est destinée à être utilisée dans un processus d’intégration continue.

Options

Utilisez ces options pour personnaliser le comportement d’une commande.

`--watch`

La commande surveillera toute modification apportée aux fichiers .astro et signalera toute erreur.

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

Spécifie un autre répertoire racine à vérifier. Par défaut, le répertoire de travail actuel est utilisé.

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

Spécifie un fichier tsconfig.json à utiliser manuellement. S’il n’est pas fourni, Astro essaiera de trouver une configuration, ou déduira automatiquement la configuration du projet.

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

Spécifie la gravité minimale nécessaire pour sortir avec un code d’erreur. La valeur par défaut est error.

Par exemple, l’exécution de astro check --minimumFailingSeverity warning entraînera la sortie de la commande avec une erreur si des avertissements sont détectés.

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

Spécifie la gravité minimale à afficher. La valeur par défaut est hint.

Par exemple, l’exécution de astro check --minimumSeverity warning montrera les erreurs et les avertissements, mais pas les indices.

`--preserveWatchOutput`

Spécifie qu’il ne faut pas effacer la sortie entre les contrôles lorsqu’on est en mode de surveillance.

`--noSync`

Spécifie de ne pas exécuter astro sync avant de vérifier le projet.

En savoir plus sur la vérification des types dans Astro.

`astro sync`

Ajouté à la version : astro@2.0.0

Génère des types TypeScript pour tous les modules Astro. Cela configure un fichier src/env.d.ts pour l’inférence de type et définit le module astro:content pour l’API de Collections de Contenu.

Le module astro:content pour l’API des Collections de contenus.
Le module astro:db pour Astro DB.
Le module astro:env pour la fonctionnalité expérimentale Astro Env.
Le module astro:actions pour Astro Actions

`astro add`

Ajoute une intégration à votre configuration. En savoir plus dans le guide des intégrations.

`astro docs`

Lance directement le site web Astro Docs depuis le terminal.

`astro info`

Rapporte des informations utiles sur votre environnement Astro actuel. Utile pour fournir des informations lors de l’ouverture d’un problème.

astro info

Exemple de sortie :

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

`astro preferences`

Gérer les préférences des utilisateurs avec la commande astro preferences. Les préférences utilisateur sont spécifiques à chaque utilisateur d’Astro, contrairement au fichier astro.config.mjs qui modifie le comportement de toutes les personnes travaillant sur un projet.

Par défaut, les préférences de l’utilisateur sont limitées au projet en cours, et sont stockées dans un fichier local .astro/settings.json..

En utilisant l’option --global, les préférences utilisateur peuvent aussi être appliquées à tous les projets Astro sur la machine courante. Les préférences utilisateur globales sont stockées dans un emplacement spécifique au système d’exploitation.

Préférences disponibles

devToolbar — Active ou désactive la barre d’outils de développement dans le navigateur. (Défaut : true)
checkUpdates — Active ou désactive les vérifications automatiques des mises à jour pour l’Astro CLI. (Défaut : true)

La commande list affiche les paramètres actuels de toutes les préférences configurables de l’utilisateur. Elle supporte également une sortie --json lisible par la machine.

astro preferences list

Exemple de sortie du terminal :

Preference	Value
devToolbar.enabled	true
checkUpdates.enabled	true

Vous pouvez enable, disable, ou reset les préférences à leur valeur par défaut.

Par exemple, pour désactiver la devToolbar dans un projet Astro spécifique :

astro preferences disable devToolbar

Pour désactiver la devToolbar dans tous les projets Astro sur la machine actuelle :

astro preferences disable --global devToolbar

La devToolbar peut ensuite être activée avec :

astro preferences enable devToolbar

La commande reset réinitialise une préférence à sa valeur par défaut :

astro preferences reset devToolbar

`astro telemetry`

Configure la télémétrie pour l’utilisateur actuel du CLI. La télémétrie est une donnée anonyme qui fournit à l’équipe Astro des informations sur les fonctionnalités Astro les plus souvent utilisées. Pour en savoir plus, voir la page télémetrie d’Astro’.

La télémétrie peut être désactivée avec cette commande CLI :

astro telemetry disable

La télémétrie peut être réactivée ultérieurement avec :

astro telemetry enable

La commande reset réinitialise les données de télémétrie :

astro telemetry reset

Options courantes

`--root <chemin>`

Spécifie le chemin de la racine du projet. Si aucun chemin n’est spécifié, le répertoire de travail actuel est considéré comme la racine.

La racine est utilisée pour trouver le fichier de configuration Astro.

astro --root monDossierRacine/monDossierProjet dev

`--config <chemin>`

Spécifie le chemin du fichier de configuration par rapport à la racine du projet. Il est défini par défaut à astro.config.mjs. Utilisez cette option si vous utilisez un nom différent pour votre fichier de configuration ou si votre fichier de configuration est dans un autre dossier.

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

`--outDir <chemin>`

Ajouté à la version : astro@3.3.0

Configure le outDir pour votre projet. Passer cette option remplacera la valeur de outDir dans votre fichier astro.config.mjs, s’il en existe un.

`--site <url>`

Configure le site pour votre projet. Utiliser cette option remplacera, si elle existe, la valeur site de votre fichier astro.config.mjs.

`--base <chemin>`

Ajouté à la version : astro@1.4.1

Configure la base de votre projet. Utiliser cette option remplacera, si elle existe, la valeur base de votre fichier astro.config.mjs.

`--port <number>`

Spécifie le port sur lequel le serveur de développement et le serveur de prévisualisation doivent être exécutés. La valeur par défaut est 4321.

`--host [adresse d'hôte optionnelle]`

Définit les adresses IP du réseau sur lesquelles le serveur de développement et le serveur de prévisualisation doivent écouter (c.-à-d. les adresses IP non locales). Cela peut être utile pour tester votre projet sur des appareils locaux comme un téléphone portable pendant le développement.

--host — écoute sur toutes les adresses, y compris les adresses LAN et publiques
--host <adresse personnalisée> - écoute sur une adresse IP du réseau à <adresse personnalisée>.

`--verbose`

Active les journaux verbeux, ce qui est utile pour déboguer un problème.

`--silent`

Active les journaux silencieux, ce qui lance le serveur sans aucune sortie dans la console.

`--open`

Ouvre automatiquement l’application dans le navigateur au démarrage du serveur. Une chaîne d’URL complète (par exemple --open http://example.com) ou un chemin d’accès (par exemple --open /about) peut être transmis pour spécifier l’URL à ouvrir.

Options globales

Utilisez ces options pour obtenir des informations à propos du CLI astro.

`--version`

Affiche le numéro de version d’Astro et quitte.

`--help`

Affiche le message d’aide et quitte.

API avancées (expérimentales)

Si vous avez besoin de plus de contrôle lors de l’exécution d’Astro, le paquet "astro" exporte également des API pour exécuter par programme les commandes CLI.

Ces API sont expérimentales et leur signature peuvent changer. Toute mise à jour sera mentionnée dans le Astro changelog et les informations ci-dessous montreront toujours les informations actuelles et à jour.

`AstroInlineConfig`

Le type AstroInlineConfig est utilisé par toutes les API de commande ci-dessous. Il s’étend à partir du type utilisateur Astro config :

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

`configFile`

Type : string | false
Par défaut : undefined

Un chemin personnalisé vers le fichier de configuration d’Astro.

Si cette valeur est indéfinie (par défaut) ou non définie, Astro recherchera un fichier astro.config.(js,mjs,ts,mts) relatif à la root et chargera le fichier de configuration s’il est trouvé.

Si un chemin relatif est défini, il sera résolu en fonction de l’option root.

Mettre false pour désactiver le chargement de tout fichier de configuration.

La configuration en ligne passée dans cet objet sera prioritaire lors de la fusion avec la configuration utilisateur chargée.

`mode`

Type : "development" | "production"
Par défaut : "development" lors de l’exécution de astro dev, "production" lors de l’exécution de astro build

Le mode utilisé lors de la construction de votre site pour générer du code “developpement” ou “production”.

`logLevel`

Type : "debug" | "info" | "warn" | "error" | "silent"
Par défaut : "info"

Le niveau de journalisation pour filtrer les messages enregistrés par Astro.

"debug": Enregistre tout, y compris les diagnostics de débogage.
"info": Enregistre les messages d’information, les avertissements et les erreurs.
"warn": Enregistre les avertissements et les erreurs.
"error": Ne consigne que les erreurs.
"silent": Pas de journalisation.

`dev()`

Type : (inlineConfig: AstroInlineConfig) => Promise<DevServer>

Similaire à astro dev, il fait tourner le serveur de développement d’Astro.

import { dev } from "astro";

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

// Arrêter le serveur si nécessaire
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`

L’adresse que le serveur de développement écoute.

Cette propriété contient la valeur renvoyée par la méthode net.Server#address() de Node.

`handle()`

Une méthode pour gérer les requêtes HTTP Node brutes. Vous pouvez appeler handle() avec un objet http.IncomingMessage et un objet http.ServerResponse au lieu d’envoyer une requête via le réseau.

`watcher`

L’observateur de fichiers Chokidar tel qu’il est exposé par le serveur de développement de Vite.

`stop()`

Arrête le serveur de développement. Cela ferme toutes les connexions inactives et arrête d’écouter les nouvelles connexions.

Renvoie une promesse (Promise) qui se résout une fois que toutes les demandes en attente ont été satisfaites et que toutes les connexions inactives ont été fermées.

`build()`

Type : (inlineConfig: AstroInlineConfig) => Promise<void>

Similaire à astro build, il construit votre site pour le deploiement.

import { build } from "astro";

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

`preview()`

Type : (inlineConfig: AstroInlineConfig) => Promise<PreviewServer>

Similaire à astro preview, il démarre un serveur local pour servir la sortie de votre construction.

Si aucun adaptateur n’est défini dans la configuration, le serveur d’aperçu ne servira que les fichiers statiques créés. Si un adaptateur est défini dans la configuration, le serveur d’aperçu est fourni par l’adaptateur. Les adaptateurs ne sont pas tenus de fournir un serveur d’aperçu, cette fonctionnalité peut donc ne pas être disponible en fonction de l’adaptateur choisi.

import { preview } from "astro";

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

// Arrêter le serveur si besoin
await previewServer.stop();

`PreviewServer`

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

`host`

L’hôte sur lequel le serveur écoute les connexions.

Les adaptateurs sont autorisés à laisser ce champ non défini. La valeur de host est spécifique à l’implémentation.

`port`

Le port sur lequel le serveur écoute les connexions.

`stop()`

Demande au serveur de prévisualisation de se fermer, de cesser d’accepter les demandes et de supprimer les connexions inactives.

La Promise renvoyée est résolue lorsque la demande de fermeture a été envoyée. Cela ne signifie pas que le serveur est déjà fermé. Utilisez la méthode closed() si vous devez vous assurer que le serveur est complètement fermé.

`closed()`

Renvoie une promesse (Promise) qui se résoudra une fois le serveur fermé et sera rejetée si une erreur se produit sur le serveur.

`sync()`

Type : (inlineConfig: AstroInlineConfig) => Promise<void>

Similaire à astro sync, il génère des types TypeScript pour tous les modules Astro.

import { sync } from "astro";

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

Astro Studio CLI

`astro login`

S’authentifier avec Astro Studio. Cette action est nécessaire pour exécuter toutes les commandes de gestion de base de données, y compris astro link.

`astro link`

Lien vers votre base de données hébergée dans Studio. Ce lien est nécessaire pour exécuter les commandes Astro DB pour la gestion de la base de données. Pour lier une base de données, vous serez invité à sélectionner une base de données existante ou à en créer une nouvelle.

`astro logout`

Déconnectez-vous d’Astro Studio et supprimez toutes les clés d’authentification stockées localement.

Contribuer

Communauté

Commandes CLI

Commandes astro

Scripts package.json

astro dev

astro build

astro preview

astro check

Options

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

Préférences disponibles

astro telemetry

Options courantes

--root <chemin>

--config <chemin>

--outDir <chemin>

--site <url>

--base <chemin>

--port <number>

--host [adresse d'hôte optionnelle]

--verbose

--silent

--open

Options globales

--version

--help

API avancées (expérimentales)

AstroInlineConfig

configFile

mode

logLevel

dev()

DevServer

address

handle()

watcher

stop()

build()

preview()

PreviewServer

host

port

stop()

closed()

sync()

Astro Studio CLI

astro login

astro link

astro logout

Commandes `astro`

Scripts `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 <chemin>`

`--config <chemin>`

`--outDir <chemin>`

`--site <url>`

`--base <chemin>`

`--port <number>`

`--host [adresse d'hôte optionnelle]`

`--verbose`

`--silent`

`--open`

`--version`

`--help`

`AstroInlineConfig`

`configFile`

`mode`

`logLevel`

`dev()`

`DevServer`

`address`

`handle()`

`watcher`

`stop()`

`build()`

`preview()`

`PreviewServer`

`host`

`port`

`stop()`

`closed()`

`sync()`

`astro login`

`astro link`

`astro logout`