Skip to content

Latest commit

 

History

History
374 lines (253 loc) · 11.3 KB

programmatic-reference.mdx

File metadata and controls

374 lines (253 loc) · 11.3 KB
title i18nReady
API programmatique d'Astro (expérimentale)
true

import Since from '~/components/Since.astro';

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

Ces API sont expérimentales et leur signature API peut changer. Toutes les mises à jour seront mentionnées dans le journal des modifications d'Astro et les informations ci-dessous afficheront 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 de configuration Astro de l'utilisateur :

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

configFile

Type : string | false
Par défaut : undefined

Un chemin personnalisé vers le fichier de configuration Astro.

Si cette valeur est indéfinie (par défaut) ou non définie, Astro recherchera un fichier astro.config.(js,mjs,ts,mts) par rapport à la racine (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.

Définissez la valeur sur false pour désactiver le chargement des fichiers de configuration.

La configuration en ligne transmise dans cet objet aura la priorité la plus élevée lors de la fusion avec la configuration utilisateur chargée.

mode

Type : string
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 du développement ou de la construction de votre site (par exemple "production", "test").

Cette valeur est transmise à Vite à l'aide de l'option --mode lorsque les commandes astro build ou astro dev sont exécutées pour déterminer la valeur de import.meta.env.MODE. Cela détermine également quels fichiers .env sont chargés, et donc les valeurs de astro:env. Consultez la page des variables d'environnement pour plus de détails.

Pour générer une version basée sur le développement, vous pouvez exécuter astro build avec l'option --devOutput.

logLevel

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

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

  • "debug" : Enregistrer tout, y compris les diagnostics de débogage bruyants.
  • "info" : Enregistrer les messages d'information, les avertissements et les erreurs.
  • "warn" : Enregistrer les avertissements et les erreurs.
  • "error" : Enregistrer uniquement les erreurs.
  • "silent" : Aucune journalisation.

dev()

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

Similaire à astro dev, il exécute le serveur de développement d'Astro.

import { dev } from "astro";

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

// Arrête 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

Type : AddressInfo

L'adresse sur laquelle le serveur de développement écoute.

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

handle()

Type : (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void

Un gestionnaire pour les requêtes HTTP brutes de Node. Vous pouvez appeler handle() avec un http.IncomingMessage et un http.ServerResponse au lieu d'envoyer une requête via le réseau.

watcher

Type : vite.FSWatcher

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

stop()

Type : Promise<void>

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

Renvoie une 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, options?: BuildOptions) => Promise<void>

Similaire à astro build, il construit votre site pour le déploiement.

import { build } from "astro";

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

BuildOptions

export interface BuildOptions {
	devOutput?: boolean;
	teardownCompiler?: boolean;
}

devOutput

Type : boolean
Par défaut : false

Génère une version basée sur le développement similaire au code transformé avec astro dev. Cela peut être utile pour tester les problèmes de version uniquement avec des informations de débogage supplémentaires incluses.

teardownCompiler

Type : boolean
Par défaut : true

Supprime l'instance WASM du compilateur après la construction. Cela peut améliorer les performances lors d'une construction unique, mais peut entraîner une baisse des performances en cas de construction plusieurs fois de suite.

Lors de la création de plusieurs projets dans la même exécution (par exemple pendant les tests), la désactivation de cette option peut augmenter considérablement les performances et réduire l'utilisation maximale de la mémoire au détriment d'une utilisation soutenue de la mémoire plus élevée.

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: "./mon-projet",
});

// Arrête le serveur si nécessaire
await previewServer.stop();

PreviewServer

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

host

Type : string

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

Type : number

Le port sur lequel le serveur écoute les connexions.

stop()

Type : Promise<void>

Demande au serveur d'aperçu de fermer, d'arrêter 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()

Type : Promise<void>

Renvoie une Promise qui sera résolue une fois le serveur fermé et 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: "./mon-projet",
});

mergeConfig()

Type : <T extends AstroConfig | AstroInlineConfig>(config: T, overrides: DeepPartial<T>) => T

Importé depuis astro/config, fusionne une configuration Astro partielle avec une configuration Astro existante et valide.

mergeConfig() accepte un objet de configuration Astro et une configuration partielle (tout ensemble d'options de configuration Astro valides) et renvoie une configuration Astro valide combinant les deux valeurs telles que :

  • Les tableaux sont concaténés (y compris les intégrations et les plugins Remark).
  • Les objets sont fusionnés de manière récursive.
  • Les options de Vite sont fusionnées à l'aide de la fonction mergeConfig de Vite avec l'option isRoot par défaut.
  • Les options qui peuvent être fournies sous forme de fonctions sont encapsulées dans de nouvelles fonctions qui fusionnent de manière récursive les valeurs de retour des deux configurations avec ces mêmes règles.
  • Toutes les autres options remplacent la configuration existante.
import { mergeConfig } from "astro/config";

mergeConfig(
  {
    output: 'static',
    site: 'https://example.com',
    integrations: [tailwind()],
    server: ({command}) => ({
      port: command === 'dev' ? 4321 : 1234,
    }),
	  build: {
		  client: './custom-client',
	  },
  },
  {
    output: 'server',
    base: '/astro',
    integrations: [mdx()],
    server: ({command}) => ({
      host: command === 'dev' ? 'localhost' : 'site.localhost',
    }),
	  build: {
		  server: './custom-server',
	  },
  }
);

// Le résultat est équivalent à :
{
  output: 'server',
  site: 'https://example.com',
  base: '/astro',
  integrations: [tailwind(), mdx()],
  server: ({command}) => ({
    port: command === 'dev' ? 4321 : 1234,
    host: command === 'dev' ? 'localhost' : 'site.localhost',
  }),
	build: {
		client: './custom-client',
		server: './custom-server',
	},
}

validateConfig()

Type : (userConfig: any, root: string, cmd: string): Promise<AstroConfig>

Importé depuis astro/config, valide un objet comme s'il était exporté depuis astro.config.mjs et importé par Astro.

Il accepte les arguments suivants :

  • La configuration à valider.
  • Le répertoire racine du projet.
  • La commande Astro en cours d'exécution (build, dev, sync, etc.)

La promesse renvoyée correspond à la configuration validée, remplie avec toutes les valeurs par défaut appropriées pour la commande Astro donnée.

import { validateConfig } from "astro/config";

const config = await validateConfig({
  integrations: [tailwind()],
}, "./my-project", "build");

// les valeurs par défaut sont appliquées
await rm(config.outDir, { recursive: true, force: true });