Recursos estáticos

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

Tipos de archivos compatibles

Sección titulada Tipos de archivos compatibles

Los siguientes tipos de archivos son compatibles por defecto en Astro:

• Componentes de Astro (.astro)
• Markdown (.md, .markdown, etc.)
• JavaScript (.js, .mjs)
• TypeScript (.ts)
• Paquetes NPM
• JSON (.json)
• CSS (.css)
• Módulos CSS (.module.css)
• Imágenes & otros archivos (.svg, .jpg, .png, etc.)

Adicionalmente, puedes extender la lista de tipos de archivos soportados por los diferentes UI Frameworks que soporta Astro, como React, Svelte y Vue. También puedes instalar la integración de Astro MDX y usar archivos .mdx en tu proyecto.

Archivos en public/

Sección titulada Archivos en public/

Puedes poner cualquier recurso estático en el directorio public/ de tu proyecto, y Astro lo copiará directamente en la compilación final sin ningún cambio. Los archivos de public/ no se construyen ni empaquetan con Astro, lo que significa que cualquier tipo de archivo es compatible. Puedes referenciar un archivo de public/ por una ruta de URL directamente en tus plantillas HTML.

Declaraciones de importación

Sección titulada Declaraciones de importación

Astro usa ESM, la misma sintaxis import y export soportada en el navegador.

JavaScript

Sección titulada JavaScript

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

Se puede importar JavaScript usando la sintaxis normal ESM import & export.

Importando archivos JSX

Un UI framework apropiado (React, Preact, o Solid) es necesario para renderizar archivos JSX/TSX. Utiliza las extensiones .jsx/.tsx donde sea apropiado, ya que Astro no soporta JSX en archivos .js/.ts.

TypeScript

Sección titulada TypeScript

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

Astro incluye compatibilidad con TypeScript. Puedes importar archivos .ts y .tsx directamente a tu proyecto de Astro, e incluso escribir código TypeScript directamente dentro del script del componente de Astro y en cualquier etiqueta de script hoisted.

Astro no realiza ninguna verificación de tipos por sí mismo. La verificación de tipos debe realizarse al margen Astro, ya sea mediante el IDE o un script separado. Para chequeo de tipos en archivos Astro, puedes usar el comando astro check.

TypeScript y extensiones de archivos

Según las reglas de resolución de módulos de TypeScript, las extensiones .ts y .tsx no deben utilizarse a la hora de importar archivos de TypeScript. En su lugar, utiliza las extensiones .js/.jsx, o bien puedes omitir la extensión del archivo completamente.

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

Lee más sobre la compatibilidad de TypeScript en Astro.

Paquetes NPM

Sección titulada Paquetes NPM

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

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

Si un paquete fue publicado usando un formato antiguo, Astro convertirá el paquete a ESM para que las declaraciones import funcionen. En algunos casos, necesitarás ajustar la 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 llevarte a errores.

JSON

Sección titulada JSON

// Importa el objeto JSON mediante el export por defecto
import json from './data.json';

Astro puede importar archivos JSON directamente a su aplicación. Los archivos importados devuelven el objeto JSON completo mediante una importación por defecto.

CSS

Sección titulada CSS

// Importa e inyecta 'style.css' en la página
import './style.css';

Astro es compatible con la importación de CSS directamente en su 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 de forma predeterminada y es compatible con lenguajes de compilación a CSS como Sass & Less a través de plugins.

CSS Modules

Sección titulada CSS Modules

// 1. Convierte las clases de './style.module.css' en valores únicos con
//    alcance solo para este componente.
// 2. Devuelve un objeto que mapea los nombres de clase originales a sus
//    valores finales, con alcance solo para este componente.
import styles from './style.module.css';

// Este ejemplo usa JSX, pero puedes usar módulos CSS con cualquier framework.
return <div className={styles.error}>Tu mensaje de error</div>;

Astro es compatible con módulos CSS utilizando la nomenclatura [nombre].module.css. Como cualquier archivo CSS, al importar el archivo se aplicará automáticamente los estilos a la página. Sin embargo, los módulos CSS exportan un objeto styles que mapea los nombres de clase originales con los identificadores únicos generados.

CSS Modules te ayuda a limitar el alcance de los estilos y aislarlos de otros mediante nombres de clase únicos que son generados para tus hojas de estilo.

Otros recursos

Sección titulada Otros recursos

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

// Este ejemplo utiliza JSX, pero puedes usar módulos CSS con cualquier framework.
<img src={imgReference.src} alt="descripción de la imagen"/>;

Todos los archivos que no se mencionan explícitamente en el ejemplo anterior, se pueden importar a través de ESM import y devolverán una URL con referencia al archivo creado. Esto puede ser útil para hacer referencia por URL a archivos que no son JS, como crear un elemento img con el atributo src que apunte a esa imagen.

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

Nota

¡Agrega alt text a las etiquetas <img> para mejorar la accesibilidad! No olvides agregar un atributo alt="una buena descripción" a tus elementos de imagen. Puedes dejar el atributo vacío si la imagen es puramente decorativa.

Alias

Sección titulada Alias

Un alias es una forma de crear atajos para tus imports.

Los alias ayudan a mejorar la experiencia de desarrollo en repositorios con muchas carpetas 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 necesitaría comprender la relación de archivos entre src/pages/about/company.astro, src/components/controls/Button.astro y src/assets/logo.png?url. Y luego, si se moviera el archivo company.astro, estas importaciones también tendrían que actualizarse.

Puedes agregar alias de importación en tsconfig.json.

tsconfig.json

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

Nota

Asegúrate de que compilerOptions.baseUrl esté configurado para que las rutas con alias se puedan resolver.

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

src/pages/about/company.astro

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

Estos alias también se integran automáticamente a VSCode y otros editores.

Astro.glob()

Sección titulada Astro.glob()

Astro.glob() es una forma de importar muchos archivos a la vez.

Astro.glob() solo toma un parámetro: un patrón de glob relativo que coincida con los archivos locales que desea importar. Es asíncrono y devuelve una array de las exportaciones de cada archivo que coincida.

src/components/my-component.astro

---
// importa todos los archivos que terminan en `.md` en `./src/pages/post/`
const posts = await Astro.glob('../pages/post/*.md');
---
<!-- Renderiza un <article> para los primeros 5 posts del blog -->
<div>
{posts.slice(0, 4).map((post) => (
  <article>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
    <a href={post.url}>Leer más</a>
  </article>
))}
</div>

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

src/pages/component-library.astro

---
// importa todos los archivos que terminan en `.astro` en `./src/components/`
const components = await Astro.glob('../components/*.astro');
---
<!-- Muestra todos tus componentes -->
{components.map((component) => (
  <div>
    <component.default size={24} />
  </div>
))}

Patrones Glob

Sección titulada Patrones Glob

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

Por ejemplo, el patrón de 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

Sección titulada Patrones Glob en Astro

Para usar con Astro.glob(), el patrón de glob debe ser una cadena literal y no puede contener variables. Consulta la guía de solución de problemas para una solución alternativa.

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)

Leer más sobre la sintaxis de patrones glob.

Astro.glob() vs getCollection()

Sección titulada Astro.glob() vs getCollection()

Las colecciones de contenido proporcionan una API getCollection() para cargar varios archivos en lugar de Astro.glob(). Si tus archivos de contenido (p. ej. Markdown, MDX, Markdoc) se encuentran dentro del directorio src/content/, utiliza getCollection() para consultar una colección y obtener las entradas de contenido.

WASM

Sección titulada WASM

// Importa e inicializa el archivo WASM solicitado
const wasm = await WebAssembly.instantiateStreaming(fetch('/example.wasm'));

Astro es compatible con la carga de archivos WASM directamente en tu aplicación mediante la API WebAssembly del navegador.

Módulos integrados de Node

Sección titulada Módulos integrados de Node

Recomendamos a los usuarios de Astro que eviten usar los módulos integrados de Node.js (fs, path, etc.) siempre que sea posible. Astro es compatible con múltiples motores de ejecución usando adaptadores. Esto incluye Deno y Cloudflare Workers que no son compatibles con los módulos integrados de Node como fs.

El objetivo de Astro es proporcionar alternativas a los módulos integrados comunes de Node.js. Sin embargo, estas alternativas aún no existen. Si realmente necesitas utilizar estos módulos, no queremos detenerlo. Astro es compatible con los módulos integrados de Node.js utilizando el nuevo prefijo node:. Si por ejemplo quieres leer un archivo, puedes hacerlo así:

src/components/MyComponent.astro

---
// Ejemplo: importa el módulo "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>

Extendiendo el soporte de tipos de archivo

Sección titulada Extendiendo el soporte de tipos de archivo

Con Vite y los plugin Rollup compatibles, puedes importar tipos de archivo que no son compatibles nativamente con Astro. Aprende dónde encontrar los plugins que necesitas en la sección Finding Plugins de la documentación de Vite.

Configuración de plugin

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

Receta relacionada: Instalando un plugin de Vite o Rollup