Referencia de importaciones

Astro admite la mayoría de los activos estáticos sin necesidad de configuración. Puedes usar la sentencia import en cualquier lugar del JavaScript de tu proyecto (incluido tu frontmatter de Astro) y Astro incluirá una copia compilada y optimizada de ese activo estático en tu compilación final. @import también es compatible dentro de CSS y etiquetas <style>.

Tipos de archivos admitidos

Astro admite los siguientes tipos de archivos de forma nativa:

• Componentes de Astro (.astro)
• Markdown (.md, .markdown, etc.)
• JavaScript (.js, .mjs)
• TypeScript (.ts)
• Paquetes NPM
• JSON (.json)
• CSS (.css)
• CSS Modules (.module.css)
• Imágenes y activos (.svg, .jpg, .png, etc.)

Además, puedes extender Astro para añadir compatibilidad con diferentes frameworks de UI como componentes de React, Svelte y Vue. También puedes instalar la integración MDX de Astro o la integración Markdoc de Astro para usar archivos .mdx o .mdoc en tu proyecto.

Archivos en public/

Puedes colocar cualquier activo estático en el directorio public/ de tu proyecto, y Astro lo copiará directamente en tu compilación final sin modificarlo. Los archivos en public/ no son compilados ni empaquetados por Astro, lo que significa que se admite cualquier tipo de archivo.

Puedes hacer referencia a un archivo en public/ mediante una ruta URL directamente en tus plantillas HTML.

// To link to /public/reports/annual/2024.pdf
Download the <a href="/reports/annual/2024.pdf">2024 annual statement as a PDF</a>.

// To display /public/assets/cats/ginger.jpg
<img src="/assets/cats/ginger.jpg" alt="An orange cat sleeping on a bed.">

Sentencias de importación

Astro utiliza ESM, la misma sintaxis de import y export compatible con el navegador.

JavaScript

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

JavaScript se puede importar utilizando la sintaxis estándar de ESM import y export.

Importación de archivos JSX

Se requiere un framework de UI adecuado (React, Preact o Solid) para renderizar archivos JSX/TSX. Utiliza las extensiones .jsx/.tsx donde corresponda, ya que Astro no admite JSX en archivos .js/.ts.

TypeScript

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

Astro incluye soporte incorporado para TypeScript. Puedes importar archivos .ts y .tsx directamente en tu proyecto de Astro, e incluso escribir código TypeScript directamente dentro de tu script de componente de Astro y de cualquier etiqueta script.

Astro no realiza ninguna comprobación de tipos por sí mismo. La comprobación de tipos debe gestionarse fuera de Astro, ya sea mediante tu IDE o a través de un script independiente. Para la comprobación de tipos de archivos de Astro, se proporciona el comando astro check.

TypeScript y extensiones de archivos

Según las reglas de resolución de módulos de TypeScript, las extensiones de archivo .ts y .tsx no deben usarse al importar archivos TypeScript. En su lugar, utiliza las extensiones de archivo .js/.jsx o prescinde por completo de la extensión del archivo.

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

Lee más sobre el soporte de TypeScript en Astro.

Paquetes NPM

Si has instalado un paquete NPM, puedes importarlo en Astro.

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

Si un paquete se publicó utilizando un formato heredado (legacy), Astro intentará convertir el paquete a ESM para que las sentencias import funcionen. En algunos casos, es posible que debas ajustar tu configuración de vite para que funcione.

Precaución

Algunos paquetes dependen de un entorno de navegador. Los componentes de Astro se ejecutan en el servidor, por lo que importar estos paquetes en el frontmatter puede provocar errores.

JSON

// Load the JSON object via the default export
import json from './data.json';

Astro admite la importación de archivos JSON directamente en tu aplicación. Los archivos importados devuelven el objeto JSON completo en la importación predeterminada.

CSS

// Load and inject 'style.css' onto the page
import './style.css';

Astro admite la importación de archivos CSS directamente en tu aplicación. Los estilos importados no exponen exportaciones, pero importar uno agregará automáticamente esos estilos a la página. Esto funciona para todos los archivos CSS por defecto, y puede admitir lenguajes que se compilan a CSS como Sass y Less a través de plugins.

Lee más sobre casos de uso avanzados de importación de CSS, como una referencia de URL directa para un archivo CSS o la importación de CSS como una cadena de texto, en la guía de Estilos.

CSS Modules

// 1. Converts './style.module.css' classnames to unique, scoped values.
// 2. Returns an object mapping the original classnames to their final, scoped value.
import styles from './style.module.css';

// This example uses JSX, but you can use CSS Modules with any framework.
return <div className={styles.error}>Your Error Message</div>;

Astro admite CSS Modules utilizando la convención de nomenclatura [name].module.css. Al igual que cualquier archivo CSS, importar uno aplicará automáticamente ese CSS a la página. Sin embargo, CSS Modules exportan un objeto de styles predeterminado especial que asigna tus nombres de clase originales a identificadores únicos.

CSS Modules te ayudan a aplicar el alcance y el aislamiento de componentes en el frontend con nombres de clase generados de forma única para tus hojas de estilo.

Otros activos

// Returns an object with `src` and other properties
import imgReference from './image.png';
import svgReference from './image.svg';

// HTML or UI Framework components use this to render the image
<img src={imgReference.src} alt="image description" />;

// The Astro `<Image />` and `<Picture />` components access `src` by default
<Image src={imgReference} alt="image description">

Todos los demás activos no mencionados explícitamente anteriormente se pueden importar a través de ESM import y devolverán una referencia de URL al activo compilado final (p. ej., /_astro/my-video.C7vXpQtF.mp4) en lugar de un objeto.

Esto puede ser útil para hacer referencia a activos que no son de JS mediante URL, como la creación de un elemento de video con un atributo src que apunte a esa imagen.

También puede ser útil colocar imágenes y otros activos en la carpeta public/ como se explica en la página de estructura del proyecto.

Lee más sobre cómo añadir parámetros de importación de Vite (p. ej., ?url, ?raw) en la guía de manejo de activos estáticos de Vite.

Nota

¡Se recomienda añadir texto alternativo (alt) a las etiquetas <img> por accesibilidad! No olvides añadir un atributo alt="una descripción útil" a tus elementos de imagen. Puedes dejar el atributo vacío si la imagen es puramente decorativa.

Alias

Un alias es una forma de crear accesos directos para tus importaciones.

Los alias pueden ayudar a mejorar la experiencia de desarrollo en bases de código con muchos directorios o importaciones relativas.

src/pages/about/company.astro

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

En este ejemplo, un desarrollador tendría que entender la relación de árbol entre src/pages/about/company.astro, src/components/controls/Button.astro y src/assets/logo.png. Y luego, si el archivo company.astro se moviera, estas importaciones también tendrían que actualizarse.

Puedes añadir alias de importación en tsconfig.json.

tsconfig.json

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

El servidor de desarrollo se reiniciará automáticamente después de este cambio de configuración. Ahora puedes importar usando los alias en cualquier lugar de tu proyecto:

src/pages/about/company.astro

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

import.meta.glob()

El import.meta.glob() de Vite es una forma de importar muchos archivos a la vez usando patrones glob para encontrar rutas de archivos coincidentes.

import.meta.glob() toma un patrón glob relativo que coincide con los archivos locales que deseas importar como parámetro. Devuelve un array con las exportaciones de cada archivo coincidente. Para cargar todos los módulos coincidentes por adelantado, pasa { eager: true } como segundo argumento:

src/components/my-component.astro

---
// imports all files that end with `.md` in `./src/pages/post/`
const matches = import.meta.glob('../pages/post/*.md', { eager: true });
const posts = Object.values(matches);
---
<!-- Renders an <article> for the first 5 blog posts -->
<div>
{posts.slice(0, 4).map((post) => (
  <article>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
    <a href={post.url}>Read more</a>
  </article>
))}
</div>

Los componentes de Astro importados usando import.meta.glob son del tipo AstroInstance. Puedes renderizar cada instancia de componente usando su propiedad default:

src/pages/component-library.astro

---
// imports all files that end with `.astro` in `./src/components/`
const components = Object.values(import.meta.glob('../components/*.astro', { eager: true }));
---
<!-- Display all of our components -->
{components.map((component) => (
  <div>
    <component.default size={24} />
  </div>
))}

Valores admitidos

La función import.meta.glob() de Vite solo admite literales de cadena estáticos. No admite variables dinámicas ni interpolación de cadenas.

Una alternativa común es importar en su lugar un conjunto más grande de archivos que incluya todos los archivos que necesitas y luego filtrarlos:

src/components/featured.astro

---
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>
  Take a look at my favorite post, <a href={myFeaturedPost.url}>{myFeaturedPost.frontmatter.title}</a>!
</p>

Utilidades de tipo de importación

Archivos Markdown

Los archivos Markdown cargados con import.meta.glob() devuelven la siguiente interfaz MarkdownInstance:

export interface MarkdownInstance<T extends Record<string, any>> {
  /* Any data specified in this file's YAML/TOML frontmatter */
  frontmatter: T;
  /* The absolute file path of this file */
  file: string;
  /* The rendered path of this file */
  url: string | undefined;
  /* Astro Component that renders the contents of this file */
  Content: AstroComponentFactory;
  /** (Markdown only) Raw Markdown file content, excluding layout HTML and YAML/TOML frontmatter */
  rawContent(): string;
  /** (Markdown only) Markdown file compiled to HTML, excluding layout HTML */
  compiledContent(): string;
  /* Function that returns an array of the h1...h6 elements in this file */
  getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
  default: AstroComponentFactory;
}

Opcionalmente, puedes proporcionar un tipo para la variable frontmatter utilizando un genérico de 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>

Archivos de Astro

Los archivos de Astro tienen la siguiente interfaz:

export interface AstroInstance {
  /* The file path of this file */
  file: string;
  /* The URL for this file (if it is in the pages directory) */
  url: string | undefined;
  default: AstroComponentFactory;
}

Otros archivos

Otros archivos pueden tener varias interfaces diferentes, pero import.meta.glob() acepta un genérico de TypeScript si sabes exactamente qué contiene un tipo de archivo no reconocido.

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

Patrones glob

Un patrón glob es una ruta de archivo que admite caracteres comodín especiales. Esto se utiliza para hacer referencia a varios archivos en tu proyecto a la vez.

Por ejemplo, el patrón glob ./pages/**/*.{md,mdx} comienza dentro del subdirectorio pages, busca en todos sus subdirectorios (/**) y coincide con cualquier nombre de archivo (/*) que termine en .md o .mdx (.{md,mdx}).

Patrones glob en Astro

Para usar con import.meta.glob(), el patrón glob debe ser un literal de cadena y no puede contener ninguna variable.

Además, los patrones glob deben comenzar con uno de los siguientes:

• ./ (para comenzar en el directorio actual)
• ../ (para comenzar en el directorio padre)
• / (para comenzar en la raíz del proyecto)

Lee más sobre la sintaxis de los patrones glob.

import.meta.glob() vs getCollection()

Las colecciones de contenido proporcionan APIs de alto rendimiento y centradas en el contenido para cargar múltiples archivos en lugar de import.meta.glob(). Utiliza getCollection() y getLiveCollection() para consultar tus colecciones y devolver entradas de contenido.

WASM

// Loads and initializes the requested WASM file
const wasm = await WebAssembly.instantiateStreaming(fetch('/example.wasm'));

Astro admite la carga de archivos WASM directamente en tu aplicación utilizando la API WebAssembly del navegador.

Módulos nativos de Node

Astro admite los módulos integrados de Node.js, con algunas limitaciones, utilizando el prefijo más nuevo node: de Node. Puede haber diferencias entre desarrollo y producción, y algunas características pueden ser incompatibles con el renderizado bajo demanda. Algunos adaptadores también pueden ser incompatibles con estos módulos integrados o requerir configuración para admitir un subconjunto (p. ej., Cloudflare Workers o Deno).

El siguiente ejemplo importa el módulo util de Node para analizar un tipo de medio (MIME):

src/components/MyComponent.astro

---
// Example: import the "util" built-in from Node.js
import util from 'node:util';

export interface Props {
  mimeType: string,
}

const mime = new util.MIMEType(Astro.props.mimeType)
---

<span>Type: {mime.type}</span>
<span>SubType: {mime.subtype}</span>

Extensión del soporte de tipos de archivos

Con Vite y plugins compatibles con Rollup, puedes importar tipos de archivos que no son compatibles de forma nativa con Astro. Obtén información sobre dónde encontrar los plugins que necesitas en la sección Búsqueda de plugins de la documentación de Vite.

Configuración del plugin

Consulta la documentación de tu plugin para conocer las opciones de configuración y cómo instalarlo correctamente.

Related recipe: Instalación de un plugin de Vite o Rollup