Référence des importations

Astro supporte la plupart des ressources statiques sans aucune configuration requise. Vous pouvez utiliser la directive import n’importe où dans votre projet JavaScript (y compris votre frontmatter d’Astro) et Astro inclura une copie construite et optimisée de cette ressource statique dans votre build final. @import est également prise en charge dans les balises CSS et <style>.

Types de fichiers supportés

Les types de fichiers suivants sont pris en charge par Astro :

Composants Astro (.astro)
Markdown (.md, .markdown, etc.)
JavaScript (.js, .mjs)
TypeScript (.ts)
Paquets NPM
JSON (.json)
CSS (.css)
Modules CSS (.module.css)
Images et actifs (.svg, .jpg, .png, etc.)

De plus, vous pouvez étendre Astro pour ajouter le support de différents Frameworks UI comme React, Svelte et Vue. Vous pouvez également installer l’intégration Astro MDX ou l’intégration Astro Markdoc pour utiliser les fichiers .mdx ou .mdoc dans votre projet.

Les fichiers dans `public/`

Vous pouvez placer n’importe quelle ressource statique dans le répertoire public/ de votre projet, et Astro le copiera directement dans votre version finale sans y toucher. Les fichiers dans le répertoire public/ ne sont pas construits ou regroupés par Astro, ce qui signifie que n’importe quel type de fichier est supporté.

Vous pouvez référencer un fichier public/ par un chemin d’URL directement dans vos modèles HTML.

// Pour faire un lien vers /public/reports/annual/2024.pdf
Télécharger la <a href="/reports/annual/2024.pdf">déclaration annuelle 2024 en PDF</a>.

// Pour afficher /public/assets/cats/ginger.jpg
<img src="/assets/cats/ginger.jpg" alt="Un chat orange dort sur un lit.">

Déclarations d’importation

Astro utilise ESM, la même syntaxe import et export que celle utilisée dans le navigateur.

JavaScript

import { getUser } from './user.js';

JavaScript peut être importé en utilisant la syntaxe normale d’importation et d’exportation d’ESM.

TypeScript

import { getUser } from './user.ts';
import type { UserType } from './user.ts';

Astro comprend un support intégré pour [TypeScript] (https://www.typescriptlang.org/). Vous pouvez importer des fichiers .ts et .tsx directement dans votre projet Astro, et même écrire du code TypeScript directement dans votre script de composant Astro et dans n’importe quelle balise de scripts.

Astro n’effectue aucune vérification de type lui-même. La vérification de type doit être prise en charge en dehors d’Astro, soit par votre IDE, soit par un script séparé. Pour vérifier le type des fichiers Astro, la commande astro check est fournie.

Selon les règles de résolution des modules TypeScript, les extensions de fichiers .ts et .tsx ne doivent pas être utilisées lors de l’importation de fichiers TypeScript. À la place, utilisez les extensions de fichiers .js/.jsx ou omettez complètement l’extension de fichier.

import { getUser } from './user.js'; // user.ts
import MyComponent from "./MyComponent"; // MyComponent.tsx

Lire la suite Prise en charge de TypeScript dans Astro.

Paquets NPM

Si vous avez installé un paquet NPM, vous pouvez l’importer dans Astro.

---
import { Icon } from 'astro-icon';
---

Si un paquet a été publié en utilisant un ancien format, Astro essaiera de convertir le paquet en ESM pour que les déclarations import fonctionnent. Dans certains cas, vous devrez ajuster votre config vite pour que cela fonctionne.

JSON

// Charge l'objet JSON via l'export par défaut
import json from './data.json';

Astro prend en charge l’importation de fichiers JSON directement dans votre application. Les fichiers importés retournent l’objet JSON complet dans l’importation par défaut.

CSS

// Charge et intègre 'style.css' sur la page
import './style.css';

Astro prend en charge l’importation de fichiers CSS directement dans votre application. Les styles importés ne nécessitent pas d’exportations, mais l’importation d’un style ajoutera automatiquement ce style à la page. Cela fonctionne pour tous les fichiers CSS par défaut, et peut prendre en charge les langages CSS compilés comme Sass et Less via des plugins.

En savoir plus sur les cas d’utilisation avancés d’importation CSS tels qu’une référence d’URL directe pour un fichier CSS ou l’importation de CSS sous forme de chaîne de caractères dans le Guide de style

Modules CSS

// 1. Convertit les noms de classes './style.module.css' en valeurs uniques, portées.
// 2. Retourne un objet qui associe les noms de classes d'origine à leur valeur portée finale.
import styles from './style.module.css';

// Cet exemple utilise JSX, mais vous pouvez utiliser les modules CSS avec n'importe quel Framework.
return <div className={styles.error}>Votre message d'erreur</div>;

Astro supporte les modules CSS en utilisant la convention de dénomination [nom].module.css. Comme tout fichier CSS, l’importation d’un module CSS l’appliquera automatiquement à la page. Cependant, les modules CSS exportent un objet spécial par défaut styles qui fait correspondre vos noms de classe originaux à des identifiants uniques.

Les modules CSS vous aident à renforcer le cadrage et l’isolation des composants sur le frontend grâce à des noms de classe générés de manière unique pour vos feuilles de style.

Autres ressources

import imgReference from './image.png'; // imgReference === '/src/image.png'
import svgReference from './image.svg'; // svgReference === '/src/image.svg'
import txtReference from './words.txt'; // txtReference === '/src/words.txt'

// Cet exemple utilise JSX, mais vous pouvez utiliser des références d'importation avec n'importe quel Framework.
<img src={imgReference.src} alt="image description" />;

Toutes les autres ressources qui ne sont pas explicitement mentionnés ci-dessus peuvent être importés via l’import ESM et renverront une référence URL à la ressource finale construite. Cela peut être utile pour référencer des ressources non-JS par URL, comme créer un élément image avec un attribut src pointant vers cette image.

Il peut également être utile de placer des images dans le dossier public/ comme expliqué sur la page de structure du projet.

Découvrez comment ajouter des paramètres d’importation Vite (par exemple ?url ou ?raw) dans le guide de gestion des ressources statiques de Vite

Alias

Un alias est une façon de créer des raccourcis pour vos imports.

Les alias peuvent aider à améliorer l’expérience de développement dans les codebases avec de nombreux dossiers ou importations relatives.

---
import Button from '../../components/controls/Button.astro';
import logoUrl from '../../assets/logo.png?url';
---

Dans cet exemple, un développeur devra comprendre la relation de l’arborescente entre src/pages/about/company.astro, src/components/controls/Button.astro, et src/assets/logo.png. Et si le fichier company.astro devait être déplacé, ces importations devraient également être mises à jour.

Vous pouvez ajouter des alias d’importation dans tsconfig.json.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@assets/*": ["src/assets/*"]
    }
  }
}

Le serveur de développement redémarrera automatiquement après ce changement de configuration. Vous pouvez maintenant importer en utilisant les alias n’importe où dans votre projet :

---
import Button from '@components/controls/Button.astro';
import logoUrl from '@assets/logo.png?url';
---

Ces alias sont également intégrés automatiquement dans VS Code et d’autres éditeurs de code.

`import.meta.glob()`

L’utilitaire import.meta.glob() de Vite est un moyen d’importer plusieurs fichiers à la fois en utilisant des modèles glob pour trouver des chemins de fichiers correspondants.

import.meta.glob() prend un modèle glob relatif correspondant aux fichiers locaux que vous souhaitez importer comme paramètre. Il renvoie un tableau des exportations de chaque fichier correspondant. Pour charger tous les modules correspondants à l’avance, passez { eager: true } comme deuxième argument :

---
// importe tous les fichiers qui se terminent par `.md` dans `./src/pages/post/`
const matches = import.meta.glob('../pages/post/*.md', { eager: true });
const posts = Object.values(matches);
---
<!-- Rend un <article> pour les 5 premiers articles du blog -->
<div>
{posts.slice(0, 4).map((post) => (
  <article>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
    <a href={post.url}>Lire la suite</a>
  </article>
))}
</div>

Les composants Astro importés avec import.meta.glob sont de type AstroInstance. Vous pouvez effectuer le rendu de chaque instance de composant en utilisant sa propriété default :

---
// importe tous les fichiers qui se terminent par `.astro` dans `./src/components/`
const components = Object.values(import.meta.glob('../components/*.astro', { eager: true }));
---
<!-- Affiche tous nos composants -->
{components.map((component) => (
  <div>
    <component.default size={24} />
  </div>
))}

Valeurs prises en charge

La fonction import.meta.glob() de Vite ne prend en charge que les chaînes littérales statiques. Elle ne prend pas en charge les variables dynamiques ni l’interpolation de chaîne de caractères.

Une solution de contournement courante consiste à importer un ensemble de fichiers plus grand qui inclut tous les fichiers dont vous avez besoin, puis à les filtrer :

---
const { postSlug } = Astro.props;
const pathToMyFeaturedPost = `src/pages/blog/${postSlug}.md`;

const posts = Object.values(import.meta.glob("../pages/blog/*.md", { eager: true }));
const myFeaturedPost = posts.find(post => post.file.includes(pathToMyFeaturedPost));
---

<p>
  Jetez un oeil à mon article préféré, <a href={myFeaturedPost.url}>{myFeaturedPost.frontmatter.title}</a>!
</p>

Utilitaires de type d’importation

Fichiers Markdown

Les fichiers Markdown chargés avec import.meta.glob() renvoient l’interface MarkdownInstance suivante :

export interface MarkdownInstance<T extends Record<string, any>> {
  /* Toutes les données spécifiées dans le frontmatter YAML de ce fichier */
  frontmatter: T;
  /* Le chemin d'accès absolu de ce fichier */
  file: string;
  /* Le chemin rendu de ce fichier */
  url: string | undefined;
  /* Composant Astro qui restitue le contenu de ce fichier */
  Content: AstroComponentFactory;
  /** (Markdown seulement) Contenu du fichier Markdown brut, à l'exclusion de la mise en page HTML et du frontmat YAML */
  rawContent(): string;
  /** (Markdown seulement) Fichier Markdown compilé en HTML, à l'exclusion de la mise en page HTML */
  compiledContent(): string;
  /* Fonction qui renvoie un tableau des éléments h1...h6 dans ce fichier */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
  default: AstroComponentFactory;
}

Vous pouvez éventuellement fournir un type pour la variable frontmatter à l’aide d’un générique TypeScript.

---
import type { MarkdownInstance } from 'astro';
interface Frontmatter {
    title: string;
    description?: string;
}

const posts = Object.values(import.meta.glob<MarkdownInstance<Frontmatter>>('./posts/**/*.md', { eager: true }));
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
</ul>

Fichiers Astro

Les fichiers Astro ont l’interface suivante :

export interface AstroInstance {
  /* Le chemin d'accès de ce fichier */
  file: string;
  /* L'URL de ce fichier (s'il se trouve dans le répertoire des pages) */
  url: string | undefined;
  default: AstroComponentFactory;
}

Autres fichiers

D’autres fichiers peuvent avoir différentes interfaces, mais import.meta.glob() accepte un générique TypeScript si vous savez exactement ce que contient un type de fichier non reconnu.

---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = import.meta.glob<CustomDataFile>('../data/**/*.js');
---

Patterns globaux

Un pattern global est un chemin d’accès à un fichier qui prend en charge les caractères génériques spéciaux. Il est utilisé pour référencer plusieurs fichiers dans votre projet en même temps.

Par exemple, le pattern global ./pages/**/*.{md,mdx} commence dans le sous-répertoire pages, et regarde dans tous ses sous-répertoires (/**), et correspond à tous les noms de fichier (/*) qui finissent soit par .md ou .mdx (.{md,mdx}).

Patterns globaux dans Astro

Pour être utilisé avec import.meta.glob(), le modèle glob doit être une chaîne littérale et ne peut contenir aucune variable.

En outre, les motifs globaux doivent commencer par l’un des éléments suivants :

./ (pour commencer dans le répertoire actuel)
../ (pour démarrer dans le répertoire parent)
/ (pour démarrer à la racine du projet)

En savoir plus sur la syntaxe des motifs globaux.

`import.meta.glob()` vs `getCollection()`

Les collections de contenu fournissent une API getCollection() pour charger plusieurs fichiers au lieu de import.meta.glob(). Si vos fichiers de contenu (par exemple Markdown, MDX, Markdoc) sont situés dans des collections dans le répertoire src/content/, utilisez getCollection() pour interroger une collection et retourner les entrées de la collection.

WASM

// Charge et initialise le fichier WASM demandé
const wasm = await WebAssembly.instantiateStreaming(fetch('/example.wasm'));

Astro permet de charger des fichiers WASM directement dans votre application en utilisant l’API WebAssembly du navigateur.

Node Builtins

Nous encourageons les utilisateurs d’Astro à éviter les “Built-in” Node.js (fs, path, etc.) dans la mesure du possible. Astro est compatible avec de nombreux moteurs d’exécution utilisant des adaptateurs. Cela inclut Deno et Cloudflare Workers qui ne supportent pas les modules intégrés de Node tels que fs.

Notre objectif est de fournir des alternatives Astro aux composants Node.js les plus courants. Cependant, aucune alternative de ce type n’existe aujourd’hui. Donc, si vous avez vraiment besoin d’utiliser ces modules Built-in, nous ne voulons pas vous en empêcher. Astro supporte les modules Built-in de Node.js en utilisant le préfixe node: de Node. Si vous voulez lire un fichier, par exemple, vous pouvez le faire comme ceci :

---
// Exemple : importation de l'intégration "fs/promises" de Node.js
import fs from 'node:fs/promises';

const url = new URL('../../package.json', import.meta.url);
const json = await fs.readFile(url, 'utf-8');
const data = JSON.parse(json);
---

<span>Version : {data.version}</span>

Extension de la prise en charge des types de fichiers

Avec Vite et les plugins Rollup compatibles, vous pouvez importer des types de fichiers qui ne sont pas pris en charge nativement par Astro. Pour savoir où trouver les plugins dont vous avez besoin, consultez la section Finding Plugins de la documentation Vite.

Méthode associée : Installation d'un plugin Vite ou Rollup

Contribuer

Communauté

Référence des importations

Types de fichiers supportés

Les fichiers dans `public/`

Déclarations d’importation

JavaScript

TypeScript

Paquets NPM

JSON

CSS

Modules CSS

Autres ressources

Alias

`import.meta.glob()`

Valeurs prises en charge

Utilitaires de type d’importation

Fichiers Markdown

Fichiers Astro

Autres fichiers

Patterns globaux

Patterns globaux dans Astro

`import.meta.glob()` vs `getCollection()`

WASM

Node Builtins

Extension de la prise en charge des types de fichiers

Comment pouvons-nous vous aider ?

Créer une issue GitHub

Envoyez-nous un commentaire

Envoyez-nous un commentaire

Référence des importations

Types de fichiers supportés

Les fichiers dans public/

Déclarations d’importation

JavaScript

TypeScript

Paquets NPM

JSON

CSS

Modules CSS

Autres ressources

Alias

import.meta.glob()

Valeurs prises en charge

Utilitaires de type d’importation

Fichiers Markdown

Fichiers Astro

Autres fichiers

Patterns globaux

Patterns globaux dans Astro

import.meta.glob() vs getCollection()

WASM

Node Builtins

Extension de la prise en charge des types de fichiers

Les fichiers dans `public/`

`import.meta.glob()`

`import.meta.glob()` vs `getCollection()`