ApisKit

Instalacion y despliegue

De la descarga a produccion: requisitos, Firebase, Stripe y el despliegue, en orden.

De la descarga a produccion. El orden importa: si configuras Stripe antes de tener Firebase, no puedes probar nada de punta a punta.

Requisitos

  • Node.js 22 o superior. No es capricho: firebase-admin 14 lo exige en su propio package.json. Con Node 20 la instalacion avisa y algo acabara fallando.
  • Un proyecto de Firebase con Authentication, Firestore y Storage.
  • Una cuenta de Stripe.
  • Un proveedor de correo transaccional.

1. Instalar

npm install
cp .env.example .env.local

Rellena .env.local siguiendo los comentarios de .env.example. Cada clave esta explicada una por una en Variables de entorno.

Solo las variables que empiezan por NEXT_PUBLIC_ llegan al navegador. Todas las demas se quedan en el servidor. Si dudas de una, esa es la regla.

2. Firebase

  1. Crea el proyecto y una aplicacion web, y copia su configuracion a las variables NEXT_PUBLIC_FIREBASE_*.
  2. Activa Authentication (correo y contrasena, mas los proveedores que quieras).
  3. Crea Firestore y Storage.
  4. Genera una clave de cuenta de servicio y rellena las variables de administrador.
  5. Despliega las reglas y los indices que vienen con la plantilla.

No tienes que escribir las reglas desde cero: firestore.rules, storage.rules y firestore.indexes.json estan en la raiz del repositorio, enlazados desde firebase.json.

npm i -g firebase-tools
firebase login
firebase use <id-de-tu-proyecto>
firebase deploy --only firestore:rules,firestore:indexes,storage

Los indices compuestos no son opcionales. Sin ellos, el panel de administracion y la bandeja de soporte fallan al consultar, y el error aparece en produccion, no al compilar. Para comprobarlo contra tu proyecto de verdad:

npm run verify:indexes

Ese comando no se fia del fichero: lanza las consultas reales y te dice cuales rechaza la base de datos.

Que abren las reglas que vienen

Las reglas niegan todo por defecto y luego abren al navegador dos cosas: el documento del propio usuario en users/{uid}, y leer y crear sus propias compras en credit_purchases. Todo lo demas (registros de webhook, limites de peticiones, registro de borrados RGPD, auditoria de seguridad, documentacion) es solo de servidor, a traves del SDK de administrador, que se salta las reglas por diseno.

Cuando anadas colecciones para tu producto, escribe sus reglas. Lo que anadas sin regla cae en la negacion final: es seguro, pero no se leera desde el navegador hasta que la escribas.

3. Stripe

  1. Crea tus productos y precios (los packs de creditos) y conecta sus identificadores al flujo de compra.
  2. Pon la clave publicable y la secreta en .env.local.
  3. Crea un webhook apuntando a /api/webhook y copia su secreto de firma a .env.local.

Esa es la ruta que expone la plantilla (src/app/api/webhook/route.ts). Verifica la firma y es idempotente. Un webhook apuntado a otra direccion devuelve 404, y entonces el cliente paga y no recibe sus creditos. Comprueba la ruta antes de abrir al publico.

4. Arrancar en local

npm run dev            # http://localhost:3000
npm run verify:all     # la verificacion del dia a dia
npm run build          # compilacion de produccion

verify:all no levanta ningun servidor. Antes de publicar, usa la completa, que anade las pruebas de navegador:

npm run verify:release

5. Desplegar

  1. Sube el repositorio a tu proveedor de Git e importalo en tu plataforma de despliegue (framework: Next.js).
  2. Anade todas las variables de .env.local como variables de entorno, en produccion y en vista previa. Pon NEXT_PUBLIC_BASE_URL con tu URL real.
  3. Despliega. Despues cambia el webhook de Stripe a la URL de produccion y pon el secreto de firma de produccion.
  4. Apunta tu dominio y comprueba que NEXT_PUBLIC_BASE_URL coincide con el. De esa variable dependen el posicionamiento, el sitemap, los correos y los enlaces legales.

Vale cualquier alojamiento con Node.

6. Antes de abrir al publico

  • [ ] Ningun secreto en el repositorio; .env.local esta ignorado por git.
  • [ ] Reglas de Firestore y Storage desplegadas y ampliadas con las colecciones de tu producto.
  • [ ] Indices desplegados; npm run verify:indexes en verde contra el proyecto de produccion.
  • [ ] El webhook de Stripe apunta a /api/webhook en el dominio de produccion, con el secreto de produccion, y un evento de prueba llega.
  • [ ] Textos legales revisados por un profesional y datos de empresa rellenados.
  • [ ] Marca, colores, textos e imagenes sustituidos.
  • [ ] npm run verify:release y npm run build en verde.