Query de Redis con Astro en Cloudflare Workers

En esta guía, aprenderás cómo interactuar con cualquier instancia de Redis desde una aplicación Astro que se ejecuta en Cloudflare Workers. Pasarás por el proceso de configurar un nuevo proyecto Astro, habilitar la renderización del lado del servidor usando el adaptador de Cloudflare, instalar los paquetes necesarios, escribir código para interactuar con Redis y desplegar la aplicación en Cloudflare Workers.

Requisitos previos

• Node.js 20 o posterior
• Cualquier base de datos Redis (puedes usar Upstash para una solución gestionada)

Tabla de Contenidos

• Crear una nueva aplicación Astro
• Integrar el adaptador de Cloudflare en tu proyecto Astro
• Actualizar Definiciones de Tipos
• Crear una Conexión Redis
• Consultar Redis desde la aplicación Astro
• Desplegar en Cloudflare Workers

Crear una nueva aplicación Astro

Comencemos creando un nuevo proyecto Astro. Abre tu terminal y ejecuta el siguiente comando:

npm create astro@latest my-app

npm create astro es la forma recomendada de crear rápidamente un proyecto Astro.

Cuando se te pida, elige:

• Use minimal (empty) template cuando se te pregunte cómo iniciar el nuevo proyecto.
• Yes cuando se te pregunte si deseas instalar las dependencias.
• Yes cuando se te pregunte si deseas inicializar un repositorio git.

Una vez hecho esto, puedes moverte al directorio del proyecto y comenzar la aplicación:

cd my-app
npm run dev

La aplicación debería estar ejecutándose en localhost:4321. A continuación, ejecuta el siguiente comando para instalar la biblioteca necesaria para construir la aplicación:

npm install redis-on-workers
npm install -D tsx

Se instalan las siguientes bibliotecas:

• redis-on-workers: Conéctate a tu servidor Redis usando cloudflare:sockets.
• tsx: Un entorno de ejecución para TypeScript y JavaScript que te permite ejecutar archivos TypeScript directamente sin necesidad de compilarlos primero.

Integrar el adaptador de Cloudflare en tu proyecto Astro

Para desplegar tu proyecto Astro en Cloudflare Workers, necesitas instalar el adaptador correspondiente. Ejecuta el siguiente comando:

npx astro add cloudflare

Cuando se te pida, elige lo siguiente:

• Y cuando se te pregunte si deseas instalar las dependencias de Cloudflare.
• Y cuando se te pregunte si deseas hacer cambios en el archivo de configuración de Astro.

Has habilitado con éxito la renderización del lado del servidor en Astro.

Para asegurarte de que la salida sea desplegable en Cloudflare Workers, crea un archivo wrangler.toml en la raíz del proyecto con el siguiente código:

name = "redis-astro-workers"
main = "dist/_worker.js"
compatibility_date = "2025-04-01"
compatibility_flags = [ "nodejs_compat" ]

[assets]
directory="dist"
binding="ASSETS"

[vars]
REDIS_URL=""

Después de eso, asegúrate de tener tanto un archivo .env como un archivo wrangler.toml con las variables definidas para que puedan ser accedidas durante npm run dev y cuando se despliegue en Cloudflare Workers respectivamente.

Además, actualiza el archivo astro.config.mjs con lo siguiente para poder acceder a estas variables en el código de manera programática:

// ... Existing imports...
import { defineConfig, envField } from 'astro/config'

export default defineConfig({
  env: {
    schema: {
      REDIS_URL: envField.string({ context: 'server', access: 'secret', optional: false }),
    }
  }
  // adapter
})

Actualizar Definiciones de Tipos

Necesitas asegurarte de que las definiciones de tipos para el cliente Redis se apliquen correctamente. Para esto, crea un nuevo archivo llamado apply-patch.tsx en la raíz del proyecto con el siguiente código:

import { existsSync, readFileSync, writeFileSync } from 'fs'
import { join } from 'path'

const redisWorkersType = join('node_modules', 'redis-on-workers', 'dist', 'index.d.ts')

if (existsSync(redisWorkersType)) {
  const content = readFileSync(redisWorkersType, 'utf8')
  if (!content.includes('export declare class RedisInstance')) writeFileSync(redisWorkersType, content.replace('declare class RedisInstance', 'export declare class RedisInstance'))
} else console.log(`Warning: Could not find Redis workers type definition at ${redisWorkersType}`)

Este código verifica si existe un archivo de definición de tipo específico para el cliente Redis. Si existe, el código lee el archivo y verifica la presencia de una exportación específica. Si falta esa exportación, modifica el archivo para agregar la exportación.

Ahora, ejecuta el archivo con el siguiente comando:

npx tsx apply-patch.tsx

Crear una Conexión Redis

En tu aplicación Astro, crea un archivo llamado redis.ts en el directorio src/storage para establecer una conexión con Redis. Usa el siguiente código:

import { getSecret } from 'astro:env/server'
import { createRedis } from 'redis-on-workers'

const connectionString = getSecret('REDIS_URL')
if (!connectionString) throw new Error('REDIS_URL is not defined in the environment variables')

export default createRedis(connectionString)

El código anterior importa la función getSecret de astro:env/server para acceder a las variables de entorno dinámicamente durante el tiempo de ejecución, y define una variable redis de tipo RedisInstance. Recupera la cadena de conexión de Redis de los secretos del entorno usando getSecret, y establece una conexión Redis usando createRedis() si la cadena de conexión está disponible. Finalmente, exporta la instancia de redis.

Consultar Redis desde la aplicación Astro

Ahora, estás listo para ejecutar comandos en Redis usando la instancia redis. En tu página Astro, escribe el siguiente código para interactuar con Redis:

---
import redis from '../storage/redis'

let productsCount = await redis.sendOnce('GET', 'productsCount')
if (!productsCount) productsCount = 0
---

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
    {productsCount}
</body>
</html>

Este código importa la instancia redis creada anteriormente y recupera el valor asociado con la clave productsCount de Redis usando el método sendOnce().

Desplegar en Cloudflare Workers

Para hacer que tu aplicación sea desplegable en Cloudflare Workers, crea un archivo llamado .assetsignore en el directorio public con el siguiente contenido:

_routes.json
_worker.js

A continuación, necesitarás usar la CLI de Wrangler para desplegar tu aplicación en Cloudflare Workers. Ejecuta el siguiente comando para desplegar:

npm run build && npx wrangler@latest deploy

Referencias

• redis-on-workers

Conclusión

En esta publicación de blog, aprendiste cómo consultar una instancia de Redis desde una aplicación Astro que se ejecuta en Cloudflare Workers. Pasaste por los pasos de configurar el cliente Redis, establecer una conexión y ejecutar comandos para recuperar datos de Redis dentro de la aplicación Astro.

Si deseas explorar secciones específicas con más detalle, ampliar ciertos conceptos o cubrir temas adicionales relacionados, por favor házmelo saber y estaré encantado de ayudarte.