Ir al contenido

Sesiones

Agregado en: astro@5.7.0

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

A diferencia de las cookies, las sesiones se almacenan en el servidor, por lo que puedes guardar cantidades mayores de datos sin preocuparte 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>

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

astro.config.mjs
import { defineConfig, sessionDrivers } from 'astro/config'
import vercel from '@astrojs/vercel'
export default defineConfig({
adapter: vercel(),
session: {
driver: sessionDrivers.lruCache({
max: 800,
}),
}
})

Consulta la opción de configuración session (EN) para más detalles sobre cómo establecer un controlador de almacenamiento y otras opciones configurables.

Sobrescribir la configuración en tiempo de ejecución

Sección titulada «Sobrescribir la configuración en tiempo de ejecución»

Por defecto, los controladores de sesiones se configuran en el momento de la compilación, y cualquier variable de entorno utilizada se incluirá directamente en la compilación. Esto significa que no puedes sobrescribir la configuración en tiempo de ejecución.

Cuando necesites una configuración diferente (por ejemplo, para conectarte a un servicio externo), defínela en un archivo separado. Luego, usa ese archivo como el punto de entrada del controlador (EN).

El siguiente ejemplo aprovecha la compatibilidad con Unstorage (EN) para configurar el controlador de Redis en su propio punto de entrada:

  1. Instala los paquetes unstorage y ioredis:

    Ventana de terminal
    npm install unstorage ioredis
  2. Crea un archivo para la configuración del controlador (por ejemplo, src/session-driver.ts) y exporta una función por defecto que devuelva la instancia del controlador:

    src/session-driver.ts
    import type { SessionDriver } from "astro";
    import redisDriver from "unstorage/drivers/redis";
    import { REDIS_HOST, REDIS_PORT } from "astro:env/server";
    export default function (): SessionDriver {
    const driver = redisDriver({
    host: REDIS_HOST,
    port: REDIS_PORT,
    });
    return {
    async getItem(key) {
    return await driver.getItem(key);
    },
    async setItem(key, value) {
    await driver.setItem?.(key, value, {});
    },
    async removeItem(key) {
    await driver.removeItem?.(key, {});
    },
    };
    }
  3. Usa este archivo como el punto de entrada del controlador en tu configuración de Astro:

    astro.config.mjs
    import { defineConfig, envField, sessionDrivers } from "astro/config";
    import vercel from "@astrojs/vercel";
    export default defineConfig({
    adapter: vercel(),
    env: {
    schema: {
    REDIS_HOST: envField.string({
    context: "server",
    access: "public",
    default: "localhost",
    }),
    REDIS_PORT: envField.number({
    context: "server",
    access: "public",
    default: 6379,
    }),
    },
    },
    session: {
    driver: {
    entrypoint: new URL("./src/session-driver.ts", import.meta.url),
    },
    },
    });

Agregado en: astro@7.2.0

El runtime de sesiones se excluye automáticamente de tu bundle del servidor siempre que no se configure ningún controlador de sesiones. Configurar session: false le indica además a tu adaptador que no proporcione su controlador predeterminado, deshabilitando completamente el soporte de sesiones en tu proyecto:

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
session: false,
});

Los adaptadores que normalmente proporcionan un controlador de sesiones predeterminado (por ejemplo, Node (EN), Cloudflare (EN) y Netlify (EN)) no configurarán ninguno. Esto puede ser útil para runtimes serverless y edge, donde un bundle más pequeño reduce el tiempo de arranque en frío.

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

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

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

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

En componentes y páginas .astro, puedes acceder al objeto de 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>

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

src/pages/api/addToCart.ts
import type { APIContext } from "astro";
export async function POST(context: APIContext) {
const cart = await context.session?.get('cart') || [];
const data = await context.request.json();
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);
}

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

src/actions/addToCart.ts
import { defineAction } from 'astro:actions';
import { z } from 'astro/zod';
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;
},
}),
};

En middleware, el objeto de 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();
});

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

Opcionalmente, puedes definir tipos de 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; }'.
---
Contribuir Comunidad Patrocinador