Solución de problemas

Astro provee muchas herramientas diferentes para ayudar a solucionar y debuggear los problemas en tu código.

Consejos y trucos

Depuración con `console.log()`

console.log() es un método sencillo pero popular para depurar tu código de Astro. Donde escribas tu declaración console.log() determinará dónde se imprimirá la salida de depuración:

---
console.log('¡Hola! Soy el servidor. Esto se registra en la terminal donde se está ejecutando Astro.');
---
<script>
console.log('¡Hola! Soy el cliente. Esto se registra en la consola de desarrollo del navegador.');
</script>

Una declaración console.log() en el frontmatter de Astro siempre enviará su salida a la terminal en la que se está ejecutando la CLI de Astro. Esto se debe a que Astro se ejecuta en el servidor y nunca en el navegador.

El código que se escribe o importa dentro de una etiqueta <script> de Astro se ejecuta en el navegador. Cualquier declaración console.log() u otra salida de depuración se imprimirá en la consola de tu navegador.

Depurando componentes de frameworks

Componentes de framework (como React y Svelte) son únicos: se renderizan en el lado del servidor de forma predeterminada, lo que significa que la salida de depuración de console.log() será visible en la terminal. Sin embargo, también pueden ser hidratados para el navegador, lo que puede hacer que tus registros de depuración también aparezcan en el navegador.

Esto puede ser útil para depurar las diferencias entre la salida del SSR y los componentes hidratados en el navegador.

Componente `<Debug />` de Astro

Para ayudarte a depurar tus componentes de Astro, Astro proporciona un componente incorporado <Debug /> que renderiza cualquier valor directamente en la plantilla HTML de tu componente. Esto es útil para depuración rápida en el navegador sin tener que alternar entre tu terminal y tu navegador.

---
import { Debug } from 'astro:components';
const sum = (a, b) => a + b;
---
<!-- Ejemplo: Muestra {answer: 6} en el navegador -->
<Debug answer={sum(2, 4)} />

El componente Debug admite una variedad de opciones de sintaxis para una depuración aún más flexible y concisa:

---
import { Debug } from 'astro:components';
const sum = (a, b) => a + b;
const answer = sum(2, 4);
---
<!-- Ejemplo: Los tres ejemplos son equivalentes. -->
<Debug answer={sum(2, 4)} />
<Debug {{answer: sum(2, 4)}} />
<Debug {answer} />

Mensajes de error comunes

Aquí veremos algunos mensajes de error comunes con los que te puedes llegar a cruzar en la terminal, su significado y qué hacer para solucionarlos. Consulta nuestra guía de referencia de errores completa para obtener una lista completa de los errores de Astro que puedes encontrar.

Cannot use import statement outside a module

En componentes de Astro, las etiquetas <script> son elevadas (hoisted) y cargadas como módulos JS por defecto. Si has incluido la directiva is:inline o cualquier otro atributo en tu tag, este comportamiento por defecto es eliminado.

Solución: Si has añadido atributos a tu tag script, también debes agregar el atributo type="module" para poder usar declaraciones de importación.

Estado: Comportamiento esperado de Astro.

¿No estás seguro de que este sea tu problema? ¡Puedes ver si alguien ya ha reportado este error!

`document` (or `window`) is not defined

Este error ocurre cuando se intenta acceder a document o window en el lado del servidor.

Causas comunes

Los componentes de Astro se ejecutan en el servidor, por lo que no puedes acceder a estos objetos específicos del navegador dentro del frontmatter.

Los componentes de framework se ejecutan en el servidor por defecto, por lo que este error puede ocurrir cuando se accede a document o window durante la renderización.

Solución: Determina el código que llama a document o window. Si no estás usando document o window directamente y aún así recibes este error, revisa si algún paquete que estés importando está pensado para ejecutarse en el cliente.

Si el código está en un componente de Astro, muévelo a una etiqueta <script> fuera del frontmatter. Esto le dice a Astro que ejecute este código en el cliente, donde document y window están disponibles.
Si el código está en un componente de framework, intenta acceder a estos objetos después de la renderización usando métodos de ciclo de vida (por ejemplo, useEffect() en React, onMounted() en Vue, y onMount() en Svelte). También puedes evitar que el componente se renderice en el servidor agregando la directiva client:only.

Estado: Comportamiento esperado de Astro.

Expected a default export

Este error puede ser lanzado cuando intentas importar o renderizar un componente inválido, o uno que no funciona de manera correcta. (Este mensaje particular ocurre por la forma en que funciona la importación de componentes de UI en Astro.)

Solución: Intenta buscar errores en los componentes que estás intentando importar y renderizar, y asegúrate que están funcionando correctamente. Considera abrir una plantilla de inicio de Astro desde astro.new para intentar solucionar el problema de tu componente en un entorno mas sencillo

Estado: Comportamiento esperado de Astro.

Refused to execute inline script

Es posible que veas el siguiente error en la consola del navegador:

Refused to execute inline script because it violates the following Content Security Policy directive: …

Esto significa que la política de seguridad de contenido (CSP) de tu sitio web no permite ejecutar etiquetas <script> en línea, las cuales Astro genera por defecto.

Solución: Actualiza tu CSP para incluir script-src: 'unsafe-inline' para permitir que los scripts en línea se ejecuten.

Problemas comunes

Mi componente no se renderiza

Primero, comprueba que has importado el componente en el script del componente .astro o en el frontmatter de .md.

Luego chequea la declaración de importación:

Estás realizando la importación desde el lugar correcto? (Revisa la ruta de importación.)
Tu importación posee el mismo nombre que el del componente? (Chequea el nombre de tu componente y que cumpla con la sintaxis de componentes .astro.)
Has incluido la extensión en la importación? (Chequea que el archivo del cual importas contiene una extensión, ej.: .astro, .md, .jsx, .vue.)

Nota: la extensión no es necesaria solo en los archivos .js(x) y .ts(x).

Mi componente no es interactivo

Si tu componente se renderiza (ver arriba) pero no responde a la interacción del usuario, entonces puede que hayas olvidado utilizar una directiva client:* para hidratar tu componente.

Por defecto, un componente de framework no es hidratado en el cliente. Si no se provee una directiva client:*, su HTML es renderizado en la página sin JavaScript.

Cannot find package ‘X’

Si ves un aviso "Cannot find package 'react'" (o similar) cuando inicializas Astro, significa que necesitas instalar ese paquete en tu proyecto. No todos los gestores de paquetes instalarán las dependencias peer automáticamente. Si estás utilizando Node v16+ y npm, no deberías preocuparte por esta sección.

React, por ejemplo, es una dependencia peer de la integración @astrojs/react. Esto significa que deberías instalar los paquetes oficiales de react y react-dom junto con tu integración. La integración luego utilizará esos paquetes automáticamente.

# Ejemplo: Instala integraciones y frameworks a la vez
npm install @astrojs/react react react-dom

Lee la guía de integraciones de Astro para instrucciones acerca de cómo agregar renderers de frameworks, herramientas de CSS y otros paquetes en Astro.

`Astro.glob()` - no matches found

Cuando utilizas Astro.glob() para importar archivos, asegúrate de usar la sintaxis correcta de glob para que coincida con los archivos que necesitas utilizar.

Rutas de archivos

Por ejemplo, usa ../components/**/*.js en src/pages/index.astro para importar ambos archivos:

src/components/MiComponente.js
src/components/includes/MiOtroComponente.js

Valores compatibles

Astro.glob() no es compatible con variables dinámicas ni interpolación de strings.

Esto no es un bug en Astro. Esto se debe a una limitación de la función import.meta.glob() de Vite la cual solamente soporta strings estáticas.

Una solución alternativa es importar un grupo de archivos que incluya todos los archivos que necesitemos utilizando Astro.glob() y luego filtrarlos:

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

const articulos = await Astro.glob('../pages/blog/*.md');
const miArticuloDestacado = articulos.find(articulo => articulo.file.includes(rutaAMiArticuloDestacado));
---

<p>
    ¡Mira mi artículo favorito, <a href={miArticuloDestacado.url}>{miArticuloDestacado.frontmatter.title}</a>!
</p>

Utilizando Astro con Yarn 2+ (Berry)

Yarn 2+, también conocido como Berry, utiliza una técnica llamada Plug’n’Play (PnP) para guardar y manipular módulos de Node, lo cual puede causar problemas al inicializar un proyecto nuevo de Astro utilizando create astro o al trabajar con Astro. Una solución alternativa es configurar la propiedad nodeLinker en .yarnrc.yml con el valor node-modules:

nodeLinker: "node-modules"

Agregar dependencias a Astro en un monorepo

Cuando trabajas con Astro en una configuración de monorepo, las dependencias del proyecto deben agregarse en el archivo package.json de cada proyecto por separado.

Sin embargo, es posible que también desees utilizar Astro en la raíz del monorepo (p. ej. los proyectos Nx recomiendan instalar las dependencias en la raíz). En este caso, agrega manualmente las dependencias relacionadas con Astro (p. ej. @astrojs/vue, astro-component-lib) a la sección vite.ssr.noExternal de la configuración de Astro para asegurarte de que estas dependencias se instalen y se incluyan correctamente:

import { defineConfig } from 'astro/config'
export default defineConfig({
  vite: {
    ssr: {
      noExternal: [
        '@astrojs/vue',
        'astro-component-lib',
      ]
    }
  }
})

Usando `<head>` en un componente

En Astro, usar una etiqueta <head> funciona de igual manera que cualquier otra etiqueta HTML: no es movida a la parte superior de la página ni se fusiona con la etiqueta <head> existente. Por este motivo es que seguramente desees incluir una sola etiqueta <head> por página. Recomendamos escribir esta única etiqueta <head> y su contenido en un componente de plantilla.

An unexpected `<script>` or `<style>` is included

Quizás observes que se importan las etiquetas <script> o <style> de un componente en tu código HTML incluso si dicho componente no aparece en el resultado final. Esto puede suceder, por ejemplo, cuando componentes renderizados condicionalmente no son mostrados.

El proceso de construcción de Astro funciona en el gráfico de módulos: una vez que un componente se incluye en la plantilla, se procesan, optimizan y empaquetan sus etiquetas <script> y <style>, ya sea que aparezcan en el resultado final o no. Esto no se aplica a los scripts cuando se aplica la directiva is:inline.

Creando reproducciones mínimas

Cuando estés resolviendo problemas en tu código, puede ser útil crear una reproducción mínima del problema que puedas compartir. Se trata de un proyecto de Astro más pequeño y simplificado que demuestra el problema que estás experimentando. Contar con una reproducción funcional en un nuevo proyecto ayuda a confirmar que se trata de un problema repetible y no causado por algo más en tu entorno personal o proyecto existente.

Compartir una reproducción mínima es útil cuando solicitas ayuda en nuestros hilos de soporte y a menudo es necesario al presentar un informe de error a Astro.

Crea un StackBlitz a través de astro.new.

Puedes utilizar astro.new para crear un nuevo proyecto de Astro con un solo clic. Para reproducciones mínimas, recomendamos encarecidamente comenzar desde el ejemplo mínimo (vacío) que se ejecuta en StackBlitz, con la menor cantidad de código adicional posible.

StackBlitz ejecutará este proyecto de Astro en el navegador, fuera de tu entorno local. También te proporcionará un enlace compartible para que cualquier mantenedor de Astro o miembro del equipo de soporte pueda ver tu reproducción mínima fuera de su propio entorno local. Esto significa que todos están viendo el mismo proyecto, con la misma configuración y dependencias. Esto facilita que otra persona te ayude a solucionar problemas en tu código. Si el problema es reproducible, te permite verificar que el problema reside en el propio código de Astro y puedes sentirte seguro al enviar un informe de error.

Ten en cuenta que no todos los problemas se pueden reproducir en StackBlitz. Por ejemplo, tu problema podría depender de un entorno o administrador de paquetes específicos, o podría involucrar la transmisión de HTML, que no está admitida en StackBlitz. En este caso, crea un nuevo proyecto de Astro mínimo (vacío) utilizando la CLI, reproduce el problema y cárgalo en un repositorio de GitHub. En lugar de compartir una URL de StackBlitz, proporciona un enlace al repositorio de GitHub de tu reproducción mínima.

Código mínimo

Una vez que tu proyecto vacío esté configurado, sigue los pasos para reproducir el problema.

Esto puede incluir la adición de paquetes, cambios en la configuración y la escritura de código.

Solo debes agregar la cantidad mínima de código necesaria para reproducir el problema. No reproduzcas otros elementos de tu proyecto existente y elimina todo el código que no esté directamente relacionado con el problema.

Crea un issue

Si puedes reproducir el problema, ¡entonces es el momento de crear un issue y presentar un informe de error!

Ve al repositorio de Astro correspondiente en GitHub y abre un nuevo issue.

La mayoría de los repositorios tienen una plantilla de issues que hará preguntas o requerirá información para poder presentar el informe. Es importante que sigas estas plantillas, ya que si no proporcionas la información que necesitamos, tendremos que pedírtela… ¡y nadie estará trabajando en tu issue!

Incluye el enlace a tu reproducción mínima en StackBlitz (o al repositorio de GitHub, si es necesario).

Comienza con una descripción del comportamiento esperado en comparación con el comportamiento actual para proporcionar contexto sobre el problema. Luego, incluye instrucciones claras y paso a paso sobre cómo replicar el problema en un proyecto de Astro.

¿Necesitas más ayuda?

Ven a conversar con nosotros en Discord y explícanos tu problema en el canal #support. ¡Estaremos felices de ayudarte!

Visita los Issues abiertos en Astro para ver si encuentras un problema conocido o para crear un reporte de bug.

También puedes visitar las Discusiones de RFC para ver si has alcanzado una limitación conocida de Astro, y para chequear si existen propuestas relacionadas con tu caso de uso.

Crear un problema en GitHub

Envíanos comentarios

Solución de problemas

Consejos y trucos

Depuración con `console.log()`

Depurando componentes de frameworks

Componente `<Debug />` de Astro

Mensajes de error comunes

Cannot use import statement outside a module

`document` (or `window`) is not defined

Causas comunes

Expected a default export

Refused to execute inline script

Problemas comunes

Mi componente no se renderiza

Mi componente no es interactivo

Cannot find package ‘X’

`Astro.glob()` - no matches found

Rutas de archivos

Valores compatibles

Utilizando Astro con Yarn 2+ (Berry)

Agregar dependencias a Astro en un monorepo

Usando `<head>` en un componente

An unexpected `<script>` or `<style>` is included

Creando reproducciones mínimas

Crea un StackBlitz a través de astro.new.

Código mínimo

Crea un issue

¿Necesitas más ayuda?

Solución de problemas

Consejos y trucos

Depuración con console.log()

Depurando componentes de frameworks

Componente <Debug /> de Astro

Mensajes de error comunes

Cannot use import statement outside a module

document (or window) is not defined

Causas comunes

Expected a default export

Refused to execute inline script

Problemas comunes

Mi componente no se renderiza

Mi componente no es interactivo

Cannot find package ‘X’

Astro.glob() - no matches found

Rutas de archivos

Valores compatibles

Utilizando Astro con Yarn 2+ (Berry)

Agregar dependencias a Astro en un monorepo

Usando <head> en un componente

An unexpected <script> or <style> is included

Creando reproducciones mínimas

Crea un StackBlitz a través de astro.new.

Código mínimo

Crea un issue

¿Necesitas más ayuda?

Depuración con `console.log()`

Componente `<Debug />` de Astro

`document` (or `window`) is not defined

`Astro.glob()` - no matches found

Usando `<head>` en un componente

An unexpected `<script>` or `<style>` is included