Consulta de Cloud Firestore con Astro en Cloudflare Workers

En esta guía, aprenderás cómo interactuar con una instancia de Cloud Firestore 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 Cloud Firestore y desplegar la aplicación en Cloudflare Workers.

Requisitos previos

• Node.js 20 o posterior
• Una cuenta de Firebase

Tabla de Contenidos

• Generar un JSON de Cuenta de Servicio de Firebase
• Crear una nueva aplicación Astro
• Integrar el adaptador de Cloudflare en tu proyecto Astro
• Acceder a las Variables de Entorno
• Inicializar la Conexión de Firebase
• Consultar Cloud Firestore desde la aplicación Astro
• Desplegar en Cloudflare Workers

Generar un JSON de Cuenta de Servicio de Firebase

• Ve a la Consola de Firebase y navega por tu proyecto (crea uno si aún no tienes uno).
• En la Consola de Firebase, navega a Configuración del Proyecto haciendo clic en el ícono de engranaje.
• Luego, ve a la pestaña Cuentas de servicio.
• Finalmente, haz clic en Generar nueva clave privada y descarga el archivo JSON. Este archivo contiene las credenciales de tu cuenta de servicio de Firebase.

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 pregunte, elige:

• Usar plantilla mínima (vacía) cuando se te pregunte cómo comenzar el nuevo proyecto.
• Sí cuando se te pregunte si deseas instalar dependencias.
• Sí 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 fireworkers

La siguiente biblioteca está instalada:

• fireworkers: Una biblioteca que facilita la interacción con Cloud Firestore desde Cloudflare Workers.

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 pregunte, elige lo siguiente:

• Y cuando se te pregunte si deseas instalar las dependencias de Cloudflare.
• Y cuando se te pregunte si deseas realizar 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 = "cloud-firestore-astro-workers"
main = "dist/_worker.js"
compatibility_date = "2025-04-01"
compatibility_flags = [ "nodejs_compat" ]

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

[vars]
FIREBASE_PROJECT_ID=""
FIREBASE_PRIVATE_KEY=""
FIREBASE_CLIENT_EMAIL=""
FIREBASE_PRIVATE_KEY_ID=""

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:

// ... Importaciones existentes...
import { defineConfig, envField } from 'astro/config'

export default defineConfig({
  env: {
    schema: {
      FIREBASE_PROJECT_ID: envField.string({ context: 'server', access: 'secret', optional: false }),
      FIREBASE_PRIVATE_KEY: envField.string({ context: 'server', access: 'secret', optional: false }),
      FIREBASE_CLIENT_EMAIL: envField.string({ context: 'server', access: 'secret', optional: false }),
      FIREBASE_PRIVATE_KEY_ID: envField.string({ context: 'server', access: 'secret', optional: false }),
    }
  }
  // adaptador
})

Acceder a las Variables de Entorno

Para acceder de manera segura a las variables de entorno necesarias en tiempo de ejecución, debes usar la función getSecret de astro:env/server. Este enfoque, recomendado desde Astro 5.6 en adelante, asegura que tu aplicación permanezca independiente del proveedor y que la información sensible no esté codificada. Las siguientes variables se recuperarán usando este método:

• FIREBASE_PROJECT_ID
• FIREBASE_PRIVATE_KEY
• FIREBASE_CLIENT_EMAIL
• FIREBASE_PRIVATE_KEY_ID

import { getSecret } from 'astro:env/server'

const project_id = getSecret('FIREBASE_PROJECT_ID')
const private_key = getSecret('FIREBASE_PRIVATE_KEY')
const client_email = getSecret('FIREBASE_CLIENT_EMAIL')
const private_key_id = getSecret('FIREBASE_PRIVATE_KEY_ID')

export default function getFirebaseConfig() {
  return {
    project_id,
    private_key,
    client_email,
    private_key_id,
  }
}

Inicializar la Conexión de Firebase

En tu aplicación Astro, crea un archivo llamado index.ts en el directorio src/storage/firebase para exportar una función que establecerá una conexión con Cloud Firestore. Usa el siguiente código:

import getFirebaseConfig from './config'
import * as Firestore from 'fireworkers'
import { getSecret } from 'astro:env/server'

const firebaseConfig = getFirebaseConfig()

export async function initializeFirebase(): Promise<Firestore.DB> {
  return await Firestore.init({
    uid: 'user1234',
    project_id: firebaseConfig.project_id,
    private_key: firebaseConfig.private_key,
    client_email: firebaseConfig.client_email,
    private_key_id: firebaseConfig.private_key_id,
  })
}

export { Firestore }

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. Luego importa la función getFirebaseConfig para recuperar los detalles de configuración de Firebase. La función initializeFirebase se define para inicializar una conexión de base de datos Firestore usando los detalles de configuración obtenidos de getFirebaseConfig. Finalmente, el módulo Firestore se exporta para su uso en otras partes de la aplicación.

Consultar Cloud Firestore desde la aplicación Astro

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

---
import { initializeFirebase, Firestore } from '../../storage/index'

const firestore = await initializeFirebase()

// Para establecer un documento en la colección `storage`, espera Firestore.set(firestore, 'storage', key, { value }, { merge: true })
// Para eliminar un documento en la colección `storage`, espera Firestore.remove(firestore, 'storage', key)

// Obtén el documento (de clave `productsCount`) y usa su propiedad value (de la colección `storage`)
let count = await Firestore.get(firestore, 'storage', 'productsCount').then((doc) => doc.fields.value).catch(() => null)
if (!count) count = 0
---

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

Este código importa la función initializeFirebase y todo el Firestore exportado y recupera el valor asociado con la clave productsCount de Cloud Firestore usando el método .get().

Desplegar en Cloudflare Workers

Para 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

• fireworkers

Conclusión

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

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