Cómo conectar autenticación, base de datos y pagos en Webflow Cloud (Supabase, Auth0 y Stripe)

Durante años, el patrón más común en Webflow era un compromiso de arquitectura dividida: Webflow se encargaba del diseño y una aplicación Next.js independiente alojada en Vercel gestionaba la lógica, comunicándose ambos mediante una API o un iframe.

Funcionaba, pero implicaba dos flujos de despliegue, dos conjuntos de secretos de entorno y una negociación constante en la interfaz de la API entre lo que renderizaba Webflow y lo que servía el backend.

Webflow Cloud cambia ese panorama al ejecutar tu aplicación Astro directamente en la infraestructura de Webflow (respaldada por Cloudflare Workers), de modo que el frontend y la aplicación full-stack conviven bajo el mismo techo.

¿El truco? Cloudflare Workers se ejecuta en el entorno V8 isolate, no en Node.js. Esto significa que los clientes HTTP predeterminados que utilizan la mayoría de los SDK (especialmente Stripe) fallan silenciosamente cuando intentas desplegarlos sin la configuración adecuada.

Esta guía cubre la configuración completa: crear la estructura de un proyecto en Webflow Cloud; integrar Supabase para la capa de base de datos, Auth0 para la autenticación y Stripe para los pagos; y lograr que los tres funcionen correctamente en el entorno edge antes de desplegar.

¿Qué necesitas para crear una aplicación full-stack en Webflow Cloud?

Debes tener cinco cosas listas antes de escribir código de integración: un espacio de trabajo de Webflow con acceso a Cloud, Node.js 18+ con npm, la CLI de Webflow y cuentas activas en Supabase, Auth0 y Stripe. Calcula entre 45 y 60 minutos si vas a configurar cuentas nuevas en los tres servicios.

Aquí te explicamos en qué consiste cada requisito.

Un espacio de trabajo de Webflow con acceso a Cloud

Webflow Cloud está disponible en planes de espacio de trabajo de pago. Necesitarás acceso a la sección Cloud en tu panel de control de Webflow. Si no ves "Cloud" en la barra lateral izquierda cuando estás en tu espacio de trabajo, revisa el nivel de tu plan.

Node.js 18+ y npm

Webflow Cloud solo admite npm; no Yarn, pnpm ni bun. Esto es importante porque la wrangler.jsonc configuración y el flujo de construcción asumen el uso de npm. Si tu proyecto se inició con otro gestor de paquetes, conviértelo antes de inicializar un proyecto Cloud. Ejecuta node -v y npm -v para confirmar que ambos están disponibles.

Además, necesitas Next.js 15+. Webflow Cloud solo admite Next.js 15 o Astro. Si tu proyecto utiliza Next.js 14 o una versión anterior, actualízalo antes de ejecutar webflow cloud init. Ejecuta next --version para confirmar.

Instalación global de la CLI de Webflow

La CLI gestiona la autenticación con la plataforma de Webflow y los comandos de despliegue.

Instálala con:

npm install -g @webflow/webflow-cli

Confirma que está instalada con webflow --version.

Un proyecto de Supabase con una base de datos

Crea un proyecto en supabase.com.

Necesitarás la URL del proyecto y la clave pública (anon) de la configuración de la API. El cliente de JavaScript de Supabase utiliza la API Fetch internamente, lo que significa que funciona en Cloudflare Workers sin necesidad de ninguna configuración especial. Es una de las pocas integraciones de terceros que simplemente funciona.

Una aplicación de Auth0 configurada como Regular Web Application

En tu panel de control de Auth0, crea una aplicación y establece el tipo como "Regular Web Application".

Anota tu dominio, ID de cliente y secreto de cliente. También generarás un secreto hexadecimal de 32 bytes para firmar las sesiones: openssl rand -hex 32 produce el formato correcto. El SDK v4 de Next.js para Auth0 (@auth0/nextjs-auth0) es compatible con el edge por defecto; la ruta de importación /edge de la v3 ya no existe en la v4.

Una cuenta de Stripe con un endpoint de webhook

Necesitarás una clave pública y una clave secreta de tu panel de control de Stripe.

Para pruebas locales, la CLI de Stripe genera un secreto de firma de webhook que añadirás a tu entorno. Para producción, configurarás el endpoint del webhook en el panel de control de Stripe apuntando a tu dominio desplegado.

Una vez que todo esté listo, la integración completa lleva unos seis pasos. Aquí te explico cómo.

6 pasos para crear una aplicación full-stack en Webflow Cloud con Supabase, Auth0 y Stripe

Los seis pasos a continuación cubren la integración completa: preparar el proyecto y los archivos de configuración, declarar el edge runtime para cada ruta de API, conectar Supabase, Auth0 y Stripe, y realizar el despliegue.

Los pasos 1 y 2 son fundamentales. Si te equivocas en ellos, las integraciones posteriores no funcionarán como esperas. Te señalaré los puntos críticos de cada servicio a medida que avancemos.

1. Inicializa tu proyecto de Webflow Cloud y verifica los archivos de configuración

Antes de tocar cualquier código de integración, la estructura de Webflow Cloud debe ser correcta. Cada error de configuración que he visto en proyectos de clientes se debía a un webflow.json mal formado, un open-next.config.ts faltante o variables de entorno configuradas en .env.local en lugar del panel de control de Webflow Cloud.

Hacer bien la estructura desde el principio garantiza que todo lo demás se despliegue correctamente al primer intento.

Comienza autenticándote con la CLI de Webflow e inicializando tu proyecto en la nube:

webflow auth login
webflow cloud init

Aquí:

• webflow auth login abre una ventana del navegador para autenticar tu sesión de la CLI con tu espacio de trabajo de Webflow
• webflow cloud init ejecuta una configuración interactiva que crea los archivos necesarios y vincula tu proyecto local a un proyecto de Webflow Cloud en tu panel de control

Si estás trabajando en un proyecto de Next.js existente, ejecuta webflow cloud init desde la raíz del proyecto.

Tras la inicialización, confirma que estos cuatro archivos existen y coinciden exactamente.

webflow.json

El selector de framework que le indica a Webflow Cloud qué adaptador de tiempo de ejecución utilizar:

{
  "cloud": {
    "framework": "nextjs"
  }
}

Si el archivo no existe después de webflow cloud init, créalo manualmente en la raíz del proyecto. Este es el único archivo de configuración específico de Webflow. Todo lo demás es estándar de Next.js o Cloudflare.

wrangler.jsonc

Esta es la configuración de Cloudflare Workers. La nodejs_compat bandera es lo que habilita el subconjunto de APIs de Node.js disponibles en el tiempo de ejecución edge.

Sin ella, incluso operaciones básicas como Buffer arrojarán un error:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "nextjs",
  "main": ".open-next/worker.js",
  "compatibility_date": "2025-03-01",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "binding": "ASSETS",
    "directory": ".open-next/assets"
  },
  "observability": { "enabled": true }
}

Este archivo es solo para desarrollo local. Wrangler lo lee cuando ejecutas npm run preview, lo cual simula el entorno de Cloudflare Workers de forma local.

open-next.config.ts

Esta es la configuración del adaptador de OpenNext para Cloudflare.

Para la mayoría de los proyectos, esto es una exportación única:

import { defineCloudflareConfig } from "@opennextjs/cloudflare";
export default defineCloudflareConfig({});

La mayoría de los proyectos no necesitan modificar este archivo más allá de la exportación predeterminada. Se vuelve relevante cuando añades funciones avanzadas de OpenNext como ISR o adaptadores de caché personalizados, pero para esta arquitectura se queda tal cual.

cloudflare-env.d.ts

Aquí están las definiciones de tipo de TypeScript para los bindings de Cloudflare.

Esto comienza vacío, pero añadirás entradas aquí cuando incorpores almacenamiento D1, KV o R2 más adelante:

interface CloudflareEnv {}

Un comportamiento crítico de las variables de entorno que debes entender antes de continuar: en Webflow Cloud, las variables de entorno son solo para el tiempo de ejecución. No están disponibles durante el paso de compilación.

En un despliegue estándar de Next.js, NEXT_PUBLIC_las variables se integran en el paquete del cliente durante la compilación, pero en Webflow Cloud, las variables de entorno no están disponibles durante ese paso, por lo que esta integración no puede ocurrir.

En Webflow Cloud, configuras todas las variables en la sección de Ajustes de tu proyecto en el panel de control de Webflow, y se inyectan en el momento de la solicitud. Esto significa que no puedes usar variables de entorno en next.config.ts ni en ningún código que se ejecute durante next build. Mantén todos los secretos y valores de configuración dentro de los manejadores de rutas y funciones de API.

Una vez que los archivos de configuración estén en su lugar y hayas confirmado la estructura, instala el adaptador de OpenNext si no se añadió automáticamente:

npm install @opennextjs/cloudflare

Luego, añade un script de vista previa a package.json para realizar pruebas locales antes del despliegue:

{
  "scripts": {
    "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview"
  }
}

npm run previewnpm run dev ejecuta una simulación local de Cloudflare Workers a través de Wrangler, que es mucho más cercana al entorno de producción que preview. Yo ejecuto next dev antes de cada despliegue. Detecta incompatibilidades del tiempo de ejecución edge que  pasa por alto silenciosamente.

2. Declara el entorno de ejecución edge en cada ruta de la API

Toda ruta de API que interactúe con Supabase, Auth0 o Stripe debe declarar explícitamente el entorno de ejecución edge de Cloudflare Workers. Sin esta declaración, Next.js asume por defecto un entorno Node.js; la compilación podría completarse con éxito, pero el worker desplegado fallará silenciosamente al encontrar importaciones de módulos incompatibles.

Añade esta exportación al principio de cada archivo en :app/api/

export const runtime = 'edge';

Es solo una línea, pero cambia la forma en que el compilador de Next.js procesa el archivo. Con declarado, el compilador aplica el empaquetado edge. Elimina los polyfills de Node.js y espera únicamente código compatible con la Web API.runtime = 'edge'

Cualquier importación que requiera un módulo exclusivo de Node.js (, , , ) provocará ahora un error de compilación inmediato en lugar de fallar silenciosamente durante la ejecución. Este es el comportamiento ideal: detectar errores rápido y de forma clara durante la compilación, no después del despliegue.httphttpsnetchild_process

Por experiencia, hay un matiz importante sobre la configuración de los segmentos de ruta: la declaración del entorno de ejecución edge solo se aplica al archivo de esa ruta, no a las utilidades o bibliotecas compartidas que importe.

Si utilizas un cliente de base de datos compartido definido en , ese archivo no necesita la declaración, pero la ruta de la API que lo importa sí. La regla es declarar a nivel de ruta y asegurarse de que todo lo que se importe desde ella sea compatible con el entorno edge.lib/supabase.tsruntime = 'edge'

El patrón completo para una ruta de API en este stack es el siguiente:

// app/api/user/route.ts
export const runtime = 'edge';

import { createClient } from '@supabase/supabase-js';
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  // Route handler logic here
}

3. Conecta Supabase como tu capa de base de datos

Supabase es la integración más limpia en este stack para Webflow Cloud. El cliente utiliza la Fetch API para todas las peticiones de red, lo que significa que funciona en Cloudflare Workers sin necesidad de configuraciones especiales, a diferencia de Stripe, que requiere un cambio específico de cliente HTTP.@supabase/supabase-js

El principal inconveniente con Supabase es el nombre de las variables de entorno: la clave pública ahora se llama (no , que era la convención antigua).SUPABASE_PUBLISHABLE_KEYSUPABASE_ANON_KEY

Usar el nombre de variable antiguo no rompe nada de inmediato; simplemente inicializa el cliente sin una clave, lo que genera confusos errores 401 al realizar consultas.

Así que, instala el cliente de Supabase:

npm install @supabase/supabase-js

Luego, crea un cliente de Supabase compartido en .lib/supabase.ts

Crea un cliente de Supabase compartido

Debido a que las variables de entorno en Webflow Cloud solo están disponibles durante la ejecución, este cliente debe instanciarse dentro de una función (no al inicializar el módulo) para garantizar que los valores del entorno estén disponibles cuando se ejecute la función:

// lib/supabase.ts
import { createClient } from '@supabase/supabase-js';

export function getSupabaseClient() {
  const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
  const supabaseKey = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY;

  if (!supabaseUrl || !supabaseKey) {
    throw new Error('Missing Supabase environment variables');
  }

  return createClient(supabaseUrl, supabaseKey);
}

¿Por qué envolverlo en una función? En Next.js sobre Webflow Cloud, las lecturas de process.env en el nivel superior del módulo pueden devolver undefined, ya que las variables de entorno se inyectan al realizar la petición, no al cargar el módulo. Envolver el cliente en una función asegura que los valores se lean en el momento de la llamada, cuando se garantiza su disponibilidad.

Añade las siguientes variables en la sección Configuración → Variables de tu proyecto en Webflow Cloud:

NEXT_PUBLIC_SUPABASE_URL=https://[your-project-ref].supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=[your-anon-key]

Obtén ambos valores desde el panel de control de Supabase en Configuración del proyecto → API. La "URL del proyecto" corresponde a , y la clave / corresponde a .NEXT_PUBLIC_SUPABASE_URLanonpublicNEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

Con el cliente listo, aquí tienes una ruta de API completa con entorno edge que consulta una tabla de Supabase:

// app/api/products/route.ts
export const runtime = 'edge';

import { getSupabaseClient } from '@/lib/supabase';
import { NextResponse } from 'next/server';

export async function GET() {
  const supabase = getSupabaseClient();

  const { data, error } = await supabase
    .from('products')
    .select('id, name, price, stripe_price_id')
    .order('created_at', { ascending: false });

  if (error) {
    return NextResponse.json({ error: error.message }, { status: 500 });
  }

  return NextResponse.json(data);
}

La data respuesta se escribe automáticamente si has generado tipos de TypeScript para Supabase usando supabase gen types typescript.

Recomiendo encarecidamente hacer esto, ya que detecta discrepancias en el esquema durante la compilación en lugar de en tiempo de ejecución, y es una de las mejoras de calidad de vida más importantes al trabajar en un proyecto de Webflow Cloud donde no es fácil recargar una sesión de depuración.

Nota sobre la seguridad a nivel de fila (RLS): Si tu consulta no devuelve filas ni errores, la seguridad a nivel de fila (RLS) es casi con seguridad la causa. Para un catálogo de productos público, necesitarás una SELECT política que permita al rol anon leer. Para datos específicos de usuario, pasarás un JWT en el encabezado de autorización.

4. Añadir autenticación de Auth0 con el SDK v4 de Next.js

El SDK v4 de Auth0 (@auth0/nextjs-auth0) representa un cambio arquitectónico significativo respecto a la v3, y la migración pilla desprevenidos a muchos desarrolladores, especialmente a los que siguen tutoriales antiguos.

En la v3, creabas una ruta comodín en app/api/auth/[auth0]/route.ts.

Sin embargo, en la v4 no hay un manejador de rutas. La autenticación se gestiona completamente a través de la capa de middleware de Next.js, y las rutas se montan automáticamente en /auth/* (no en /api/auth/*). Si estás actualizando desde la v3 o siguiendo un tutorial antiguo, esto es lo primero que debes corregir. Las rutas de autenticación devuelven un error 404 silencioso si usas el patrón de la v3 con la v4 instalada.

Aquí tienes cómo instalar el SDK:

npm install @auth0/nextjs-auth0

Crea el cliente de Auth0 en lib/auth0.ts. Esta es una instancia compartida que se utiliza en tu middleware y en los componentes del servidor:

// lib/auth0.ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client();

El Auth0Client lee automáticamente toda la configuración necesaria de las variables de entorno.

Crearmiddleware.ts

Crea middleware.ts en la raíz de tu proyecto (o src/middleware.ts si estás usando un directorio src/ ):

// middleware.ts
import type { NextRequest } from "next/server";
import { auth0 } from "./lib/auth0";

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
  ],
};

El patrón de coincidencia (matcher) no es opcional. Asegura que el middleware de Auth0 se ejecute en cada solicitud, excepto en los activos estáticos. Omitirlo o restringirlo demasiado hace que la renovación de la sesión falle, lo que provoca que los usuarios cierren sesión inesperadamente durante sesiones largas.

Añadir variables de entorno

Añade las cinco variables de entorno necesarias en la sección Configuración → Variables de tu proyecto de Webflow Cloud:

AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret
AUTH0_SECRET=your-64-char-hex-secret
APP_BASE_URL=https://your-deployed-domain.com

Genera AUTH0_SECRET con openssl rand -hex 32. Debe tener exactamente 64 caracteres hexadecimales (32 bytes). En tu panel de control de Auth0, establece la URL de devolución de llamada permitida en ${APP_BASE_URL}/auth/callback y la URL de cierre de sesión permitida en ${APP_BASE_URL}.

Para el desarrollo local, añádelas a .env.local con APP_BASE_URL=http://localhost:3000. No subas .env.local al control de versiones.

Además, actualiza la configuración de tu aplicación Auth0 en el panel de control para el desarrollo local. En la pestaña Configuración de tu aplicación, añade http://localhost:3000/auth/callback a las URLs de devolución de llamada permitidas y http://localhost:3000 a las URLs de cierre de sesión permitidas.

Auth0 valida la URL de devolución de llamada completa en cada intento de inicio de sesión. Sin esto, el desarrollo local arroja un error de discrepancia en la URL de devolución de llamada que parece un problema de configuración del SDK en lugar de un problema de configuración del panel de control.

Con el middleware configurado, acceder a los datos del usuario en un componente de servidor utiliza getSession():

// app/dashboard/page.tsx
import { auth0 } from "@/lib/auth0";
import { redirect } from "next/navigation";

export default async function DashboardPage() {
  const session = await auth0.getSession();

  if (!session) {
    redirect("/auth/login");
  }

  const { user } = session;

  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      <p>Email: {user.email}</p>
      <a href="/auth/logout">Log out</a>
    </div>
  );
}

Para proteger las rutas de la API, verifica la sesión dentro del manejador de rutas:

// app/api/protected/route.ts
export const runtime = 'edge';

import { auth0 } from "@/lib/auth0";
import { NextResponse } from "next/server";

export async function GET() {
  const session = await auth0.getSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  return NextResponse.json({ user: session.user });
}

El SDK v4 es compatible con el edge por defecto. Ya no existe una ruta de importación separada. Si ves esa importación en cualquier parte de tu código, elimínala; importar desde esa ruta en la v4 arroja un error de módulo no encontrado.@auth0/nextjs-auth0/edge

5. Integra los pagos de Stripe para el entorno de ejecución edge

Stripe es la integración más complicada en este stack, y su modo de fallo es sutil: el SDK predeterminado de Stripe utiliza el módulo de Node.js para las solicitudes HTTP. Ese módulo no está disponible en Cloudflare Workers, ni siquiera con la bandera.node:httpsnodejs_compat

El SDK se inicializa sin arrojar errores, pero la primera llamada real a la API (crear una sesión de pago, obtener un producto, verificar un webhook) falla con un error de red en tiempo de ejecución que no identifica claramente a Stripe como la causa.

La solución es una sola línea de configuración que cambia el cliente HTTP del de Node por la API Fetch. Esto es lo que hace que Stripe funcione en Webflow Cloud.https

Aquí tienes cómo instalar ambos paquetes:

npm install stripe @stripe/stripe-js

Luego, crea un cliente de Stripe compartido en :lib/stripe.ts

// lib/stripe.ts
import Stripe from "stripe";

export function getStripeClient() {
  const secretKey = process.env.STRIPE_SECRET_KEY;

  if (!secretKey) {
    throw new Error("Missing STRIPE_SECRET_KEY environment variable");
  }

  return new Stripe(secretKey, {
    // Required for Cloudflare Workers: swap Node.js https for the Fetch API
    httpClient: Stripe.createFetchHttpClient(),
  });
}

La opción es la línea crítica. Sin ella, Stripe intentará usar , que no está disponible en el entorno de ejecución V8 isolate, y tus rutas de API fallarán en la primera llamada a Stripe con un error de red.httpClient: Stripe.createFetchHttpClient()node:https

Con ella, Stripe utiliza la función disponible globalmente , que Cloudflare Workers proporciona de forma nativa.fetch

Añade estas variables a la configuración de tu proyecto en Webflow Cloud → Variables:

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

Usa / para tu entorno de desarrollo, y / para producción. Mantén tu clave secreta y el secreto del webhook fuera de cualquier código del lado del cliente y fuera del control de versiones.pk_test_sk_test_pk_live_sk_live_

Una distinción importante: el generado por durante el desarrollo local es diferente al secreto del endpoint del webhook en tu panel de control de Stripe.STRIPE_WEBHOOK_SECRETstripe listen

Ambos comienzan con , pero no son intercambiables. Usa el secreto generado por la CLI en para las pruebas locales, y reemplázalo con el secreto del endpoint del panel de control en las variables de entorno de tu Webflow Cloud antes de desplegar.whsec_.env.local

Completa la sesión de Stripe Checkout

Aquí tienes una ruta completa para crear una sesión de Stripe Checkout, compatible con el edge:

// app/api/checkout/route.ts
export const runtime = 'edge';

import { getStripeClient } from "@/lib/stripe";
import { auth0 } from "@/lib/auth0";
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const session = await auth0.getSession();

  if (!session) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  const { priceId } = await request.json();
  const stripe = getStripeClient();

  const checkoutSession = await stripe.checkout.sessions.create({
    mode: "payment",
    payment_method_types: ["card"],
    line_items: [
      {
        price: priceId,
        quantity: 1,
      },
    ],
    customer_email: session.user.email,
    success_url: `${process.env.APP_BASE_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.APP_BASE_URL}/pricing`,
  });

  return NextResponse.json({ url: checkoutSession.url });
}

La verificación de webhooks en el entorno de ejecución edge requiere una consideración adicional. El método de Stripe para verificar la firma del webhook utiliza el módulo . La bandera hace que esté disponible en el entorno de ejecución edge de Webflow Cloud, por lo que la verificación de webhooks funciona, pero solo si pasas el cuerpo de la solicitud original como un o , no como un objeto JSON analizado.constructEventcryptonodejs_compatcryptostringUint8Array

Debes analizar el cuerpo original antes de verificar:

// app/api/webhooks/stripe/route.ts
export const runtime = 'edge';

import { getStripeClient } from "@/lib/stripe";
import { NextRequest, NextResponse } from "next/server";

export async function POST(request: NextRequest) {
  const body = await request.text();
  const signature = request.headers.get("stripe-signature");

  if (!signature) {
    return NextResponse.json({ error: "Missing signature" }, { status: 400 });
  }

  const stripe = getStripeClient();

  let event;
  try {
    event = await stripe.webhooks.constructEventAsync(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
  }

  // Handle the event
  switch (event.type) {
    case "checkout.session.completed":
      const completedSession = event.data.object;
      // Fulfill the order in Supabase
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }

  return NextResponse.json({ received: true });
}

Observa el uso de en lugar de . La versión asíncrona utiliza (la Web Crypto API) para la verificación de la firma, la cual está disponible en el entorno de ejecución edge. La versión síncrona utiliza el módulo nativo de Node y fallará en Webflow Cloud.stripe.webhooks.constructEventAsyncconstructEventcrypto.subtleconstructEventcrypto

6. Despliega en Webflow Cloud y configura las variables de entorno de producción

Una vez que las tres integraciones funcionen localmente mediante npm run preview, despliega a producción con un solo comando de la CLI:

webflow cloud deploy

Esto inicia una compilación completa y despliega el worker compilado en Webflow Cloud. La CLI muestra una URL de despliegue al finalizar el proceso. El primer despliegue tarda un poco más porque los artefactos de compilación deben subirse y distribuirse. Los despliegues posteriores son más rápidos porque solo se vuelven a subir los archivos modificados.

Antes de desplegar, verifica que todas las variables de entorno estén configuradas en Ajustes → Variables de tu proyecto en Webflow Cloud, no en .env.local, que solo se aplica al desarrollo local y no es leído por el proceso de compilación de Webflow Cloud.

Aquí tienes las variables que necesitas para este stack completo:

# Supabase
NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

# Auth0
AUTH0_DOMAIN
AUTH0_CLIENT_ID
AUTH0_CLIENT_SECRET
AUTH0_SECRET
APP_BASE_URL

# Stripe
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET

Tras el despliegue, actualiza los ajustes de tu aplicación Auth0 para añadir el dominio de producción a las URLs de callback y cierre de sesión permitidas. Actualiza tu endpoint de webhook de Stripe para que apunte a https://your-deployed-domain.com/api/webhooks/stripe.

Es muy fácil pasar por alto estos dos pasos. Si los olvidas, la autenticación y la confirmación de pagos fallarán en producción, aunque funcionen perfectamente en local.

Para supervisar tu aplicación desplegada, Webflow Cloud incluye observabilidad integrada (activada mediante "observability": { "enabled": true } en wrangler.jsonc). Los registros están disponibles desde el panel de control de Webflow.

Para un seguimiento de errores estructurado, puedes añadirSentry como integración de Cloudflare Worker, pero la observabilidad básica integrada en la plataforma es suficiente para la depuración inicial.

¿Qué causa fallos en las aplicaciones full-stack de Webflow Cloud?

La mayoría de los fallos en proyectos full-stack de Webflow Cloud se agrupan en cuatro categorías: incompatibilidades del entorno de ejecución edge causadas por librerías dependientes de Node.js; errores de configuración en las variables de entorno específicos del modelo de ejecución de Webflow Cloud; regresiones en el enrutamiento de Auth0 al usar patrones de la v3 con la v4 instalada; y fallos en la verificación de webhooks de Stripe debido a un análisis incorrecto del cuerpo de la petición.

Aquí tienes el diagnóstico completo para cada uno.

Las llamadas a la API de Stripe fallan con un error de red tras el despliegue, a pesar de quenpm run devfunciona

Causa: El SDK de Stripe se inicializa sin httpClient: Stripe.createFetchHttpClient(), por lo que intenta usar el módulo node:https de Node.js. Ese módulo no está disponible en Cloudflare Workers (el entorno de ejecución V8 sobre el que corre Webflow Cloud), incluso con la bandera nodejs_compat activada.

El SDK se inicializa silenciosamente, por lo que no verás errores al arrancar. El fallo solo aparece en la primera llamada real a la API, lo que hace que parezca un problema de credenciales o de red en lugar de un problema de configuración.

Solución: Inicializa Stripe con el cliente HTTP basado en fetch como se muestra en el Paso 5. Cada instancia del cliente de Stripe necesita esta opción. Si tienes varios lugares en tu código que inicializan new Stripe(key), todos necesitan la anulación de httpClient . El patrón de lib/stripe.ts compartido (usando una función de fábrica) asegura que esto se aplique de forma consistente.

Las rutas de autenticación de Auth0 devuelven un 404 en producción

Causa: Esto casi siempre se debe a (a) usar el patrón de manejador de rutas catch-all de la v3 (app/api/auth/[auth0]/route.ts) con la v4 instalada, o (b) tener un matcher de middleware incorrecto que excluye las rutas /auth/* .

En la v4, no hay manejador de rutas. El middleware monta las rutas de autenticación. Si el archivo middleware.ts no existe o su matcher excluye /auth/, las rutas de inicio de sesión y callback devolverán un 404.

Solución: Confirma que middleware.ts existe en la raíz del proyecto (o en src/middleware.ts) y que la llamada a auth0.middleware(request) está presente. Confirma que el patrón del matcher incluye las rutas /auth/* . El patrón del Paso 4 está diseñado para cubrir esto correctamente. Elimina cualquier archivo de ruta app/api/auth/ que haya quedado de una configuración v3.

Las variables de entorno devuelvenundefineden las rutas de la API tras el despliegue

Causa: Las variables están definidas en .env.local pero no en Configuración → Variables del proyecto en Webflow Cloud. En Webflow Cloud, .env.local solo se lee durante el desarrollo local. No está disponible en el entorno desplegado. Si configuras variables de entorno solo en .env.local, undefined en producción, incluso si la compilación se realiza correctamente.

Solución: Configura todas las variables de entorno necesarias en el panel de control de Webflow Cloud, en Configuración → Variables, para tu proyecto. Luego, vuelve a desplegar. La comprobación undefined al inicio de cada función de fábrica (if (!supabaseUrl || !supabaseKey) throw new Error(...)) hace que este fallo sea evidente e inmediato, en lugar de generar un error sutil más adelante.

La verificación del webhook de Stripe falla con el mensaje "No signatures found matching the expected signature for payload"

Causa: El controlador del webhook utiliza request.json() para analizar el cuerpo antes de pasarlo a stripe.webhooks.constructEventAsync. La verificación de firma de Stripe calcula un hash sobre los bytes exactos del cuerpo de la solicitud.

Una vez que el cuerpo se analiza como JSON y se vuelve a serializar, la secuencia de bytes cambia (aunque los datos sean idénticos), lo que provoca que la comparación HMAC falle.

Solución: Usa request.text() para leer la cadena del cuerpo sin procesar, como se muestra en el controlador del webhook en el paso 5. Pasa la cadena sin procesar directamente a constructEventAsync. Además, confirma que estás usando constructEventAsync (la versión asíncrona) en lugar de constructEvent. La versión síncrona utiliza crypto nativo de Node.js, que no es totalmente compatible con el entorno de ejecución edge.

Las consultas de Supabase devuelven matrices vacías sin errores

Causa: La seguridad a nivel de fila (RLS) de Supabase está habilitada en la tabla y el rol anon no tiene una política de SELECT . La RLS está habilitada por defecto en todas las tablas de Supabase. Sin una política explícita, las consultas desde la clave anon no devuelven filas ni errores, un comportamiento que parece idéntico al de una tabla vacía.

Solución: En tu panel de control de Supabase, ve a la tabla → Políticas → Nueva política. Para acceso de lectura pública, crea una política que permita SELECT para el rol anon con una condición de true. Para datos de usuarios autenticados, crea una política que filtre por auth.uid() = user_id.

Si estás pasando JWT de Auth0 a Supabase para autorizar consultas específicas de usuario, deberás configurar la integración de autenticación de terceros de Supabase para que confíe en los tokens de Auth0.

Conecta tu aplicación full-stack de Webflow Cloud con el ecosistema general

En esta guía, cubrimos la configuración completa de una aplicación Next.js full-stack en Webflow Cloud, utilizando Supabase para la capa de base de datos, Auth0 para la autenticación y Stripe para el procesamiento de pagos.

Explora Webflow + Supabase si estás trabajando con ambos y quieres ver una configuración canónica y una referencia de conexión.

Para Stripe, la página de integración de Webflow + Stripe cubre el contexto del proveedor de pagos, y la página de integración de Webflow + Auth0 cubre la configuración de autenticación.

Explora la documentación para desarrolladores de Webflow para obtener una personalización más profunda, enlaces personalizados de Cloudflare, configuración de bases de datos D1 o rutas de API que interactúen directamente con la API de datos de Webflow.