Sesiones

Agregado en: astro@5.7.0

Las sesiones se utilizan para compartir datos entre solicitudes para páginas renderizadas bajo demanda.

En tercera persona y en español:

A diferencia de las cookies, las sesiones se almacenan en el servidor, por lo que es posible guardar cantidades mayores de datos sin preocuparse por los límites de tamaño o problemas de seguridad. Son útiles para almacenar cosas como datos de usuario, carritos de compra y el estado de formularios, y funcionan sin necesidad de JavaScript del lado del cliente:

src/components/CartButton.astro

---
export const prerender = false; // No es necesario con la salida `'server'`

const cart = await Astro.session?.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} artículos</a>

Configurando de sesiones

Las sesiones requieren un controlador de almacenamiento para guardar los datos de la sesión. Los adaptadores de Node, Cloudflare y Netlify configuran automáticamente un controlador predeterminado para ti, pero otros adaptadores actualmente requieren que especifiques un controlador manualmente.

astro.config.mjs

  {
    adapter: vercel(),
    session: {
      driver: "redis",
    },
  }

Consulta las opciones de configuración de session para más detalles sobre cómo establecer un controlador de almacenamiento y otras opciones configurables.

Interactuando con los datos de la sesión

El objeto session te permite interactuar con el estado almacenado del usuario (por ejemplo, agregar artículos a un carrito de compras) y con el ID de la sesión (por ejemplo, eliminar la cookie del ID de sesión al cerrar sesión). El objeto es accesible como Astro.session en tus componentes y páginas de Astro, y como context.session en endpoints API, middleware y acciones.

La sesión se genera automáticamente cuando se usa por primera vez y puede regenerarse en cualquier momento con session.regenerate() o destruirse con session.destroy().

Para muchos casos de uso, solo necesitarás usar session.get() y session.set().

Consulta la referencia de la API de Sesiones para más detalles.

Componentes y páginas de Astro

En los componentes y páginas .astro, puedes acceder al objeto sesión a través del objeto global Astro. Por ejemplo, para mostrar el número de artículos en un carrito de compras:

src/components/CartButton.astro

---
export const prerender = false; // No es necesario con la salida 'server'
const cart = await Astro.session?.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} artículos</a>

Endpoints API

En los endpoints de la API, el objeto sesión está disponible en el objeto context. Por ejemplo, para agregar un artículo a un carrito de compras:

src/pages/api/addToCart.ts

export async function POST(context: APIContext) {
  const cart = await context.session?.get('cart') || [];
  const data = await context.request.json<{ item: string }>();
  if(!data?.item) {
    return new Response('Item is required', { status: 400 });
  }
  cart.push(data.item);
  await context.session?.set('cart', cart);
  return Response.json(cart);
}

Acciones

En las acciones, el objeto sesión está disponible en el objeto context. Por ejemplo, para agregar un artículo a un carrito de compras:

src/actions/addToCart.ts

import { defineAction } from 'astro:actions';
import { z } from 'astro:schema';

export const server = {
  addToCart: defineAction({
    input: z.object({ productId: z.string() }),
    handler: async (input, context) => {
      const cart = await context.session?.get('cart');
      cart.push(input.productId);
      await context.session?.set('cart', cart);
      return cart;
    },
  }),
};

Middleware

Nota

Las sesiones no son compatibles con middleware en el edge.

En el middleware, el objeto sesión está disponible en el objeto context. Por ejemplo, para establecer la hora de la última visita en la sesión:

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
  context.session?.set('lastVisit', new Date());
  return next();
});

Tipos de datos de la sesión

Por defecto, los datos de la sesión no tienen un tipo específico, y puedes almacenar datos arbitrarios en cualquier clave. Los valores se serializan y deserializan usando devalue, que es la misma biblioteca utilizada en colecciones de contenido y acciones. Esto significa que los tipos compatibles son los mismos, e incluyen cadenas, números, Date, Map, Set, URL, arreglos y objetos simples.

Opcionalmente, puedes definir tipos TypeScript para tus datos de sesión creando un archivo src/env.d.ts y agregando una declaración para el tipo App.SessionData:

src/env.d.ts

declare namespace App {
  interface SessionData {
    user: {
      id: string;
      name: string;
    };
    cart: string[];
  }
}

Esto te permitirá acceder a los datos de la sesión con verificación de tipos y autocompletado en tu editor:

src/components/CartButton.astro

---
const cart = await Astro.session?.get('cart');
// const cart: string[] | undefined

const something = await Astro.session?.get('something');
// const something: any

Astro.session?.set('user', { id: 1, name: 'Houston' });
// Error: Argument of type '{ id: number; name: string }' is not assignable to parameter of type '{ id: string; name: string; }'.
---

Precaución

Esto solo se utiliza para la verificación de tipos y no afecta el comportamiento en tiempo de ejecución de la sesión. Ten especial cuidado si cambias el tipo cuando los usuarios ya han almacenado datos en la sesión, ya que esto podría causar errores en tiempo de ejecución.