Cómo añadir autocompletado de Webflow basado en una base de datos externa

La mayoría de los campos de búsqueda en sitios de marketing apuntan a ubicaciones de tiendas, SKUs, nombres de socios e IDs de cuenta almacenados en un sistema de registro con su propia API. El equipo de marketing quiere un campo en una página de Webflow que sugiera coincidencias a medida que el visitante escribe.

La entrada es un elemento de Webflow; las respuestas viven en otro lugar. Un pequeño servicio backend ejecutándose en Webflow Cloud sirve de puente entre ambos.

La construcción consiste en un Route Handler de Next.js desplegado en Webflow Cloud y montado en una ruta de tu sitio, además de un breve script de página que lo invoca con cada pulsación de tecla. Como el manejador está montado en el mismo dominio que la página, la solicitud del navegador es un fetch relativo sencillo sin configuración CORS, y el token de la base de datos permanece en una variable de entorno en el Worker.

¿Qué necesitas para añadir autocompletado desde una base de datos externa en Webflow?

Necesitas seis componentes, incluyendo Webflow Cloud (incluido en el plan Starter gratuito), o Premium o superior si la aplicación debe montarse en un dominio personalizado.

Prepara el sitio, el acceso a la base de datos, las herramientas locales y el proyecto de la aplicación antes de escribir el manejador de sugerencias:

• Webflow Cloud: Utiliza Webflow Cloud, que está incluido desde el plan de sitio Starter gratuito en adelante.
• Un plan que permita publicar código personalizado: El manejador de sugerencias funciona en cualquier plan, pero el script de página del paso 6 no. Publicar código personalizado, ya sea a través de un elemento Code Embed o de la configuración de código personalizado del sitio, requiere un plan de sitio de pago o un Workspace Core, Growth, Agency o Freelancer.
• Plan con dominio personalizado: Usa Premium o superior si necesitas montar la aplicación en un dominio personalizado.
• Sitio de Webflow: Prepara el elemento de entrada y una forma de cargar el script de la página después de los elementos de la misma.
• Base de datos externa: Proporciona un endpoint de consulta HTTP que acepte un término de búsqueda y devuelva JSON, con un token o clave de acceso de lectura.
• Herramientas locales: Instala Node.js y npm para el desarrollo local y los despliegues.
• Proyecto Next.js: Usa la versión 15 o superior, ya sea en un proyecto existente o en una estructura nueva.

Con estos requisitos listos, la construcción depende de un contrato de base de datos probado, un manejador montado y el código de página que llame a la ruta correcta.

6 pasos para añadir autocompletado desde una base de datos externa en Webflow Cloud

Una pulsación de tecla comienza en un script sencillo en la página de Webflow, llega a un Route Handler montado que actúa como proxy de una consulta restringida y devuelve resultados normalizados para que el script los muestre.

La construcción avanza desde el contrato de la base de datos a través del manejador desplegado y finaliza con la entrada de Webflow y la lista de resultados.

1. Define el contrato de consulta con tu base de datos

Escribe el contrato exacto de solicitud y respuesta antes de tocar nada de TypeScript. El autocompletado necesita una coincidencia de prefijo o de contenido en una columna de texto, limitada a un número pequeño de filas, y un identificador estable para cada fila, de modo que puedas publicar el valor seleccionado más adelante.

La mayoría de las bases de datos alojadas exponen esto a través de un endpoint de consulta REST o una consulta guardada que se invoca con un parámetro; si la tuya requiere SQL, envuelve la consulta en el lado del servidor dentro del endpoint para que el manejador nunca componga SQL a partir de la entrada del usuario.

Escribo el contrato como una URL y una estructura de respuesta para que puedas probarlo con antes de que Webflow Cloud entre en juego.curl

El manejador asume la siguiente estructura, y las líneas marcadas en el manejador son el único lugar donde se requieren cambios:

GET {DATABASE_QUERY_URL}?q=<term>&limit=8
Authorization: Bearer {DATABASE_API_TOKEN}

200 OK
[
  { "id": "location-1", "name": "Location One" },
  { "id": "location-2", "name": "Location Two" }
]

Ahora tienes una solicitud que puedes ejecutar desde una terminal y que devuelve una matriz JSON de y pares para un término de longitud mínima, que el resto de la compilación verifica como fuente de verdad.idname

2. Prepara la estructura de la aplicación Next.js para Webflow Cloud

Mantén la configuración predeterminada del App Router para esta compilación. La plataforma proporciona la ruta base montada durante el despliegue, así que no toques la configuración.

Usa las opciones actuales de y una versión del paquete Next.js 15 o superior desde el directorio donde guardas tus proyectos:create-next-app

npx create-next-app@latest webflow-autocomplete --typescript --app --use-npm
cd webflow-autocomplete
npm run dev

Acepta los valores predeterminados para ESLint y el alias de importación; ninguno afecta al manejador. Omite Tailwind a menos que planees crear la interfaz de usuario dentro de la aplicación, ya que la interfaz de autocompletado en esta compilación reside en la página de Webflow.

Guarda el proyecto recién creado en el control de versiones una vez que se inicie el servidor de desarrollo. Cuando imprima su URL local y la página predeterminada de Next.js se cargue en el navegador, el andamiaje estará listo para el manejador.npm run dev

3. Escribe el Route Handler de sugerencias

Un Route Handler en lee , rechaza los términos por debajo del mínimo configurado, llama a la base de datos con el token del entorno y devuelve una matriz normalizada de .app/api/suggest/route.tsqsuggestions

Normalizar en el servidor es importante porque el script del Diseñador nunca debería conocer los nombres de las columnas de la base de datos; si el esquema cambia, el manejador cambia, pero la página no.

Deja el destino del tiempo de ejecución de Next.js sin configurar en este archivo. Webflow Cloud se ejecuta en Cloudflare Workers, una plataforma edge. El destino del tiempo de ejecución de Next.js es independiente, y el adaptador OpenNext Cloudflare a través del cual se despliega Webflow Cloud no lo admite, por lo que apuntar a ese tiempo de ejecución generará una compilación defectuosa.edgeedge

Ejecuta el manejador localmente con tu versión instalada de Next.js. Confirma que la API del módulo y generan las llamadas y los encabezados de respuesta esperados antes de pasar a producción.next/serverNextResponse.json

Pega este manejador y luego ajusta las líneas marcadas para la API específica de tu base de datos:

// app/api/suggest/route.ts
import { NextResponse } from 'next/server';

const MIN_LENGTH = 2;
const MAX_RESULTS = 8;

type Suggestion = { label: string; value: string };

export async function GET(request: Request) {
  const url = new URL(request.url);
  const q = (url.searchParams.get('q') ?? '').trim();

  if (q.length < MIN_LENGTH) {
    return NextResponse.json({ suggestions: [] });
  }

  const endpoint = process.env.DATABASE_QUERY_URL;
  const token = process.env.DATABASE_API_TOKEN;
  if (!endpoint || !token) {
    return NextResponse.json({ error: 'Database is not configured' }, { status: 500 });
  }

  // Adjust these two lines to match your database's HTTP API.
  const dbUrl = `${endpoint}?q=${encodeURIComponent(q)}&limit=${MAX_RESULTS}`;
  const dbResponse = await fetch(dbUrl, {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
  });

  if (!dbResponse.ok) {
    return NextResponse.json({ error: 'Lookup failed' }, { status: 502 });
  }

  const rows = (await dbResponse.json()) as Array<{ id: string; name: string }>;
  const suggestions: Suggestion[] = rows.slice(0, MAX_RESULTS).map((row) => ({
    label: row.name,
    value: row.id,
  }));

  return NextResponse.json({ suggestions });
}

La longitud mínima y el límite de resultados restringen las consultas individuales. La ruta pública sigue expuesta al volumen de solicitudes, ya que alguien podría saltarse el debounce del navegador llamando al endpoint directamente.

Antes de pasar a producción, añade autenticación cuando la audiencia lo permita, aplica un límite de tasa por cliente en el lado del servidor y configura una cuota de solicitud ascendente o un límite de gasto que detenga el tráfico excesivo. Trata el script de la página y las restricciones de consulta como controles de formato de consulta, no como controles contra abusos.

Crea un con y configurados con los valores de base de datos probados, reinicia el servidor de desarrollo y abre . Deberías ver un objeto JSON con una matriz de y pares..env.localDATABASE_QUERY_URLDATABASE_API_TOKENhttp://localhost:3000/api/suggest?q=ausuggestionslabelvalue

4. Crea la aplicación de Webflow Cloud y elige una ruta de montaje

La ruta de montaje forma parte de cada solicitud de la página, así que elige un valor corto y estable al configurar el proyecto de Webflow Cloud en tu sitio.

Yo monto los servicios de búsqueda en una ruta como /app, porque esa cadena está a punto de ser codificada en un script de la página de Webflow y es más fácil de mantener sincronizada si alguien decide más adelante usar un nombre más descriptivo.

El desarrollo local utiliza next dev sin ruta de montaje, mientras que la aplicación desplegada solo responde bajo la ruta de montaje. El controlador no se ve afectado porque la plataforma inyecta la ruta durante la compilación, pero la página de "bring-your-own-app" indica que las llamadas fetch del lado del cliente deben incluir manualmente la ruta base.

El código dentro de la aplicación Next.js puede leer NEXT_PUBLIC_BASE_PATH; el script de la página utiliza el endpoint montado en /app/api/suggest.

Confirma el valor seleccionado en la configuración del proyecto de Webflow Cloud:

Anota la ruta de montaje. Una vez que el proyecto existe y muestra la ruta de montaje que elegiste, el sitio reserva una subruta para el primer despliegue.

5. Añade las credenciales de la base de datos y despliega

En el momento de la solicitud, el controlador lee DATABASE_QUERY_URL y DATABASE_API_TOKEN desde el entorno de Webflow Cloud, con el token marcado como secreto. No se necesita nada extra en next.config.

Las variables requeridas cubren la conexión a la base de datos, mientras que la ruta base pública solo se aplica si más adelante realizas consultas desde dentro de la aplicación:

Limita el token de la base de datos a solo lectura en la tabla o vista específica que toca la consulta. En un sitio de cliente, la agencia posee esta credencial, y una clave de solo lectura filtrada en una única vista es un incidente mucho menor que una clave de administrador filtrada.

Despliega el proyecto y observa el registro de compilación. Cuando termine, abre https://your-site.webflow.io/app/api/suggest?q=au tras sustituir tu dominio de pruebas y la ruta de montaje. Deberías obtener el mismo JSON que devolvió tu servidor local.

6. Conecta la entrada en el Webflow Designer

Dos IDs renderizados conectan los elementos de la página con el controlador montado. Añade un campo de texto, o un bloque de formulario con una sola entrada, a la página y usa lookup-input como el ID de la entrada renderizada. Añade un bloque Div vacío justo debajo y usa lookup-results como su ID renderizado. Deja el Div vacío; el script lo rellenará.

Prueba este código de página en los navegadores objetivo y con el controlador publicado antes de pasar a producción.

Añade lo siguiente como un elemento Code Embed en la página, o en el código personalizado before-</body> de la página, después de los elementos de la página, reemplazando /app con tu ruta de montaje:

<style>
  #lookup-results { position: relative; }
  .lookup-item { padding: 8px 12px; cursor: pointer; border: 1px solid #ddd; border-top: 0; background: #fff; }
  .lookup-item:hover { background: #f3f3f3; }
</style>
<script>
(function () {
  var input = document.getElementById('lookup-input');
  var list = document.getElementById('lookup-results');
  if (!input || !list) return;

  var timer = null;
  var controller = null;

  function render(items) {
    list.innerHTML = '';
    items.forEach(function (item) {
      var row = document.createElement('div');
      row.className = 'lookup-item';
      row.textContent = item.label;
      row.addEventListener('click', function () {
        input.value = item.label;
        input.dataset.selectedValue = item.value;
        list.innerHTML = '';
      });
      list.appendChild(row);
    });
  }

  input.addEventListener('input', function () {
    var q = input.value.trim();
    delete input.dataset.selectedValue;
    clearTimeout(timer);
    if (controller) controller.abort();
    if (q.length < 2) { list.innerHTML = ''; return; }

    timer = setTimeout(function () {
      controller = new AbortController();
      fetch('/app/api/suggest?q=' + encodeURIComponent(q), { signal: controller.signal })
        .then(function (r) { return r.json(); })
        .then(function (data) { render(data.suggestions || []); })
        .catch(function (err) { if (err.name !== 'AbortError') list.innerHTML = ''; });
    }, 150);
  });
})();
</script>

El debounce y el AbortController reducen el número de consultas a la base de datos mientras el visitante escribe; el abort también evita que una respuesta lenta anterior sobrescriba una más reciente.

El valor de la fila seleccionada value se coloca en data-selected-value el campo de entrada, que es lo que se lee al enviar el formulario. Al editar el campo visible, se borra ese valor seleccionado para que el formulario no envíe un ID de registro antiguo con una etiqueta recién escrita.

Revisa el código de autocompletado y su ubicación después de los elementos de la página:

Publica el sitio en el entorno de pruebas y escribe suficientes letras para cumplir con el mínimo configurado. Debería aparecer una lista de filas coincidentes debajo del campo de entrada; al hacer clic en una, se debería rellenar el campo y la pestaña de red del navegador debería mostrar solicitudes a /app/api/suggest que devuelven JSON.

¿Qué causa que el autocompletado de base de datos externa falle en Webflow Cloud?

Los fallos suelen deberse a un destino de ejecución no compatible, una ruta de montaje incorrecta en Webflow Cloud, variables de entorno desplegadas que faltan o código en la página que envía demasiadas solicitudes a la base de datos.

Utiliza los síntomas de compilación, respuesta y solicitud que se indican a continuación para identificar qué capa necesita atención.

La compilación de Webflow Cloud falla con una configuración de ejecución no compatible

Causa: La ruta establece el destino de ejecución edge de Next.js, a pesar de que Webflow Cloud despliega la aplicación a través del adaptador OpenNext Cloudflare. Ese destino es independiente de la plataforma Cloudflare Workers y no es compatible con el adaptador desplegado, por lo que la aplicación no puede enviarse correctamente.

Solución: Elimina el destino de ejecución de app/api/suggest/route.ts y vuelve a desplegar. La plataforma asigna el entorno de ejecución de Workers para el controlador. Si también cambiaste next.config, restaura la configuración predeterminada creada con la estructura del App Router.

Un next.config limpio y un controlador sin un destino de ejecución explícito son la configuración que espera esta compilación. Observa el siguiente registro de compilación para confirmar que el controlador de ruta se compila, luego carga la URL de sugerencia montada directamente y verifica que devuelva JSON en lugar de un error de despliegue o enrutamiento.

La obtención desde la página de Webflow devuelve HTML en lugar de JSON

Causa: El script está llamando a una URL fuera de la ruta de montaje configurada de la aplicación, por lo que Webflow sirve su página de no encontrado. La llamada r.json() falla entonces en el cuerpo HTML, y la rama catch borra la lista de resultados.

El síntoma visible es un campo de entrada que nunca muestra sugerencias, mientras que la pestaña de red muestra una respuesta exitosa o de no encontrado con un tipo de contenido HTML.

Solución: Utiliza la URL del controlador montado configurada para la aplicación de Webflow Cloud en el script de la página. Si más adelante creas un componente de sugerencia dentro de la propia aplicación Next.js, lee la ruta desde NEXT_PUBLIC_BASE_PATH y añádela como prefijo a tu solicitud fetch.

Confirma el cambio cargando la URL del controlador directamente en una nueva pestaña en el sitio publicado. Debería devolver JSON, y esa es exactamente la URL montada que el script debe llamar.

Confirma también que el dominio de pruebas o el dominio personalizado tenga realmente la aplicación montada en la ruta utilizada por la solicitud relativa.

Las sugerencias funcionan en next dev, pero la ruta desplegada devuelve un error del servidor

Causa: El controlador no puede encontrar DATABASE_QUERY_URL o DATABASE_API_TOKEN en el entorno desplegado y devuelve la respuesta "Database is not configured" escrita en el controlador.

El servidor de desarrollo local lee los valores no confirmados en .env.local, mientras que las variables de entorno de Webflow Cloud suministran la aplicación desplegada. Por lo tanto, los valores desplegados que faltan o están mal nombrados afectan a la producción sin afectar al desarrollo local.

Solución: Confirma que ambas variables existen con los nombres exactos que lee el controlador en el entorno de Webflow Cloud utilizado por la aplicación, luego vuelve a probar la ruta. No es necesario realizar ningún cambio en next.config .

Si el error del servidor persiste, verifica el token en la base de datos con curl, ya que un token caducado o con un alcance incorrecto también genera una respuesta de error desde la base de datos.

El controlador distingue entre una configuración faltante y un error en la búsqueda upstream, así que inspecciona el estado y el cuerpo de la respuesta para determinar si debes corregir la configuración de la aplicación o la autorización de la base de datos.

Los registros de la base de datos muestran ráfagas de consultas casi idénticas por cada visitante

Causa: El debounce o la cancelación en la página no están activos, por lo que cada pulsación de tecla llega a la base de datos. El retorno anticipado se activa si el script se ejecuta antes de que existan los elementos. Una copia duplicada del script o un retraso de debounce eliminado durante las pruebas pueden causar la misma ráfaga.

Cada solicitud también consume tiempo de Worker del presupuesto de la plataforma, que es de 20 segundos de tiempo real y 30 segundos de CPU por solicitud.

Solución: Mantén una sola copia del script y asegúrate de que se cargue después de los elementos de la página. Conserva el debounce y luego verifica en la pestaña de red que las solicitudes se agrupen en lugar de enviarse con cada pulsación de tecla.

Por separado, aplica el límite de velocidad del servidor y la cuota o tope de gasto upstream descritos para el controlador público, ya que los controles de la página no detienen las solicitudes directas. No intentes usar un Cache-Control encabezado para absorber la ráfaga: Webflow Cloud siempre reemplaza ese encabezado de respuesta con private, no-cache, por lo que no tiene efecto.

El almacenamiento en caché de consultas repetidas debe pasar por el almacén de clave-valor, cuyo TTL mínimo de caché es de 60 segundos. Antes de prometer un volumen de solicitudes a un cliente, consulta la información actual de límites de Webflow Cloud en developers.webflow.com para conocer la capacidad asignada al sitio en lugar de confiar en una cifra de otro plan.

Qué puedes construir a continuación con una base de datos externa y Webflow

Un ID seleccionado le da al formulario una clave de registro estable. El mismo patrón de controlador de ruta puede validar el ID seleccionado al enviar o escribir la respuesta en la base de datos desde un segundo controlador. El equipo de marketing sigue diseñando la página en el Designer; el desarrollador gestiona una pequeña aplicación en Webflow Cloud.

Para una opción de búsqueda alojada, explora la integración con Algolia. Para un índice autohospedado con el mismo patrón de controlador, consulta autocompletado con Elasticsearch.

El controlador también puede apuntar a Webflow. El CMS estructurado de Webflow es accesible a través de la Data API, por lo que una segunda ruta puede sugerir elementos del CMS junto con filas de la base de datos en la misma lista; así es como gestionaría una búsqueda que abarque productos en el CMS e inventario en un sistema de almacén.