@astrojs/ react

v6.0.0 GitHub npm Registro de cambios

Esta integración de Astro permite el renderizado y la hidratación del lado del cliente para tus componentes de React.

Instalación

Astro incluye un comando astro add para automatizar la configuración de las integraciones oficiales. Si lo prefieres, puedes instalar las integraciones manualmente en su lugar.

Para instalar @astrojs/react, ejecuta lo siguiente desde el directorio de tu proyecto y sigue las instrucciones:

npx astro add react

pnpm astro add react

yarn astro add react

Si tienes algún problema, no dudes en informarnos en GitHub e intenta los pasos de instalación manual a continuación.

Instalación manual

Primero, instala el paquete @astrojs/react:

npm install @astrojs/react

pnpm add @astrojs/react

yarn add @astrojs/react

La mayoría de los gestores de paquetes también instalarán las dependencias del mismo nivel asociadas. Si ves una advertencia de Cannot find package 'react' (o similar) al iniciar Astro, tendrás que instalar react y react-dom con sus definiciones de tipos:

npm install react react-dom @types/react @types/react-dom

pnpm add react react-dom @types/react @types/react-dom

yarn add react react-dom @types/react @types/react-dom

Luego, aplica la integración a tu archivo astro.config.* usando la propiedad integrations:

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

export default defineConfig({
  // ...
  integrations: [react()],
});

Y añade el siguiente código al archivo tsconfig.json.

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "react"
  }
}

Primeros pasos

Para usar tu primer componente de React en Astro, dirígete a nuestra documentación sobre frameworks de interfaz de usuario. Explorarás:

📦 cómo se cargan los componentes del framework,
💧 opciones de hidratación del lado del cliente, y
🤝 oportunidades para mezclar y anidar frameworks juntos

Integrar acciones con `useActionState()`

La integración @astrojs/react proporciona dos funciones para usar con Astro Actions: withState() y getActionState().

Estas se utilizan con el hook useActionState() de React para leer y actualizar el estado del lado del cliente al activar acciones durante el envío de formularios.

`withState()`

Tipo: (action: FormFn<T>) => (state: T, formData: FormData) => FormFn<T>

Agregado en: @astrojs/react@4.4.0

Puedes pasar withState() y la acción que deseas activar al hook useActionState() de React como la función de acción del formulario. El siguiente ejemplo pasa una acción like para incrementar un contador junto con un estado inicial de 0 likes.

import { actions } from 'astro:actions';
import { withState } from '@astrojs/react/actions';
import { useActionState } from "react";

export function Like({ postId }: { postId: string }) {
  const [state, action, pending] = useActionState(
    withState(actions.like),
    { data: 0, error: undefined }, // initial likes and errors
  );

  return (
    <form action={action}>
      <input type="hidden" name="postId" value={postId} />
      <button disabled={pending}>{state.data} ❤️</button>
    </form>
  );
}

La función withState() adaptará los tipos de la acción a lo que espera React y preservará los metadatos utilizados para la mejora progresiva, permitiendo que funcione incluso cuando JavaScript está deshabilitado en el dispositivo del usuario.

`getActionState()`

Type: (context: ActionAPIContext) => Promise<T>

Agregado en: @astrojs/react@4.4.0

Puedes acceder al estado almacenado por useActionState() en el servidor en tu handler de acción con getActionState(). Acepta el contexto de la API de Astro y, opcionalmente, puedes aplicar un tipo al resultado.

El siguiente ejemplo obtiene el valor actual de likes de un contador, tipado como número, para crear una acción like que incremente el valor:

import { defineAction, type SafeResult } from 'astro:actions';
import { z } from 'astro/zod';
import { getActionState } from '@astrojs/react/actions';

export const server = {
  like: defineAction({
    input: z.object({
      postId: z.string(),
    }),
    handler: async ({ postId }, ctx) => {
      const { data: currentLikes = 0, error } = await getActionState<SafeResult<any, number>>(ctx);

      // handle errors
      if (error) throw error;

      // write to database
      return currentLikes + 1;
    },
  })
};

Opciones

Combinar múltiples frameworks JSX

Cuando estás utilizando múltiples frameworks JSX (React, Preact, Solid) en el mismo proyecto, Astro necesita determinar qué transformaciones específicas de cada framework JSX deben utilizarse para cada uno de tus componentes. Si solo has añadido una integración de interfaz de usuario de framework JSX a tu proyecto, no se necesita configuración adicional.

Usa las opciones de configuración include (obligatoria) y exclude (opcional) para especificar qué archivos pertenecen a qué framework. Proporciona un array de archivos y/o carpetas a include para cada framework que estés utilizando. Se pueden utilizar comodines para incluir múltiples rutas de archivos.

Recomendamos colocar los componentes comunes del framework en la misma carpeta (por ejemplo, /components/react/ y /components/solid/) para facilitar la especificación de tus inclusiones, pero esto no es obligatorio:

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';

export default defineConfig({
  // Enable many frameworks to support all different kinds of components.
  // No `include` is needed if you are only using a single JSX framework!
  integrations: [
    preact({
      include: ['**/preact/*'],
    }),
    react({
      include: ['**/react/*'],
    }),
    solid({
      include: ['**/solid/*'],
    }),
  ],
});

Análisis de hijos

Los elementos hijos pasados a un componente de React desde un componente de Astro se analizan como cadenas de texto plano, no como nodos de React.

Por ejemplo, el componente <ReactComponent /> a continuación solo recibirá un único elemento hijo:

---
import ReactComponent from './ReactComponent';
---

<ReactComponent>
  <div>one</div>
  <div>two</div>
</ReactComponent>

Si estás utilizando una biblioteca que espera que se pase más de un elemento hijo, por ejemplo, para que pueda ubicar ciertos elementos en diferentes lugares, es posible que encuentres esto como un impedimento.

Puedes establecer la bandera experimental experimentalReactChildren para indicarle a Astro que pase siempre los elementos hijos a React como nodos de DOM virtuales de React. Esto tiene un costo de rendimiento en el tiempo de ejecución, pero puede ayudar con la compatibilidad.

Puedes habilitar esta opción en la configuración de la integración de React:

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

export default defineConfig({
  // ...
  integrations: [
    react({
      experimentalReactChildren: true,
    }),
  ],
});

Deshabilitar transmisión (experimental)

Astro transmite la salida de los componentes de React de forma predeterminada. Sin embargo, puedes deshabilitar este comportamiento habilitando la opción experimentalDisableStreaming. Esto es particularmente útil para dar soporte a bibliotecas que no funcionan bien con la transmisión, como algunas soluciones de CSS-in-JS.

Para deshabilitar la transmisión de todos los componentes de React en tu proyecto, configura @astrojs/react con experimentalDisableStreaming: true:

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

export default defineConfig({
  // ...
  integrations: [
    react({
      experimentalDisableStreaming: true,
    })
  ]
});