Cómo añadir datos de Airtable en tiempo real a una aplicación de Webflow Cloud

Los equipos de marketing que dependen de operaciones suelen enfrentarse a un reto común: mantener el inventario o las fechas de eventos tanto en Airtable como en el CMS de Webflow provoca discrepancias en los datos cuando los registros se vuelven a introducir manualmente.

Aunque incrustar una vista de Airtable mediante un iframe evita esta falta de sincronización, se sacrifican las opciones de tipografía y estilo personalizadas de tu sitio.

Webflow Cloud cambia las reglas del juego. Puedes montar una aplicación de Next.js bajo una ruta en el mismo sitio, mantener el token de Airtable en una variable de entorno del lado del servidor y renderizar los registros con tus propios componentes.

El CMS sigue siendo el lugar donde los editores de contenido escriben en Webflow; Airtable sigue siendo el lugar para los datos operativos; no es necesario copiar nada de uno a otro. En esta guía, recorremos cinco pasos prácticos para crear y desplegar una aplicación de Next.js en Webflow Cloud que lea y renderice de forma segura datos de Airtable en tiempo real con cada solicitud.

¿Qué necesitas para añadir datos de Airtable en Webflow?

Necesitas cinco requisitos previos:

• Base de Airtable: Utiliza la base que contiene la tabla que quieres mostrar y limita la aplicación a esos datos operativos.
• Token de acceso personal: Tu cuenta de Airtable debe tener permiso para crear un token con alcance limitado para leer registros de esa única base.
• Sitio de Webflow: Utiliza el sitio donde crearás y montarás el entorno de Webflow Cloud para la aplicación desplegada.
• Node y Next.js: Instala Node.js 22 o superior y Next.js 15 o superior, tal como se indica en los requisitos de "bring-your-own-app".
• npm: Utiliza npm, ya que es el único gestor de paquetes compatible; los pasos para pnpm o yarn no funcionan aquí.

Webflow Cloud está disponible desde el plan gratuito Starter en adelante, mientras que montar la aplicación en un dominio personalizado requiere el plan Premium o superior. Antes de crear la ruta, prepara el acceso a Airtable, tu sitio de Webflow, el entorno de ejecución, el framework y el gestor de paquetes compatible.

Con estos elementos listos, las credenciales de Airtable pueden permanecer en las variables de entorno de Webflow Cloud, mientras que el navegador solo se comunica con tu/api/records ruta.

5 pasos para añadir datos de Airtable en Webflow Cloud

Añadir datos de Airtable en tiempo real requiere un token con alcance limitado, una aplicación de Next.js, un módulo de obtención (fetch) del lado del servidor, una página renderizada y un entorno de Webflow Cloud configurado para su ruta de montaje.

Completa las cinco partes en orden para que la misma aplicación funcione tanto localmente como después del despliegue.

1. Crea el token de acceso personal de Airtable

Crea un token de acceso personal con un único ámbito de lectura y acceso a una base. En Airtable, abre el menú de tu cuenta, elige Developer hub, luego Personal access tokens y haz clic en Create token. En Scopes, añade data.records:read; en Access, selecciona solo la base que contiene tu tabla.

Airtable cambió las claves de API de toda la cuenta por estos tokens; el ámbito y el permiso de base son lo que evita que una credencial filtrada exponga todas tus bases. Copia el token cuando Airtable lo muestre, ya que solo aparece una vez. Empieza por pat; mantenlo fuera del repositorio.

Registra los identificadores que usará la aplicación:

• ID de la base: El segmento de ruta que empieza por app, que identifica la base independientemente de cómo la cambien de nombre más adelante. Mantenlo fuera del repositorio.
• ID de la tabla: El segmento que empieza por tbl; su nombre visible también funciona, pero el ID sobrevive a cualquier cambio de nombre. Mantenlo fuera del repositorio.
• ID de la vista (opcional): El segmento que empieza por viw, útil más adelante si quieres que Airtable filtre y ordene los registros antes de que lleguen a tu aplicación.
• IDs de registro: Empiezan por rec y llegan en cada respuesta de la API. Más adelante se convertirán en tus claves de React, así que no hace falta copiar ninguno ahora.

Ahora ya tienes un token de ámbito limitado junto con los identificadores estables de la base y la tabla que necesita la aplicación.

2. Prepara la estructura de la aplicación Next.js con npm

Prepara el proyecto airtable-on-webflow con Next.js 15 o superior, TypeScript, el App Router y ESLint.

Genera el proyecto con npm y luego entra en su directorio:

npx create-next-app@latest airtable-on-webflow --typescript --eslint --app
cd airtable-on-webflow

Confirma que el proyecto tiene un directorio package-lock.json y uno app/.

Crea .env.local en la raíz del proyecto, introduce tus valores reales de Airtable y deja vacía la ruta de la base local:

• AIRTABLE_TOKEN: Introduce el token de acceso personal que mostró Airtable después de crear la credencial con ámbito.
• AIRTABLE_BASE_ID: Introduce el ID real de la base de Airtable que contiene tu tabla.
• AIRTABLE_TABLE_ID: Introduce el ID real de la tabla de Airtable que leerá la aplicación.
• NEXT_PUBLIC_BASE_PATH: Añade la variable sin valor para el desarrollo local en la raíz del sitio.

NEXT_PUBLIC_BASE_PATH se queda vacío localmente porque next dev sirve la aplicación en la raíz; en Webflow Cloud se convierte en la ruta de montaje que elijas. Confirma que .gitignore excluye los archivos .env* para que el token nunca llegue a tu repositorio. Ejecuta npm run dev, y http://localhost:3000 debería mostrar la página predeterminada de Next.js sin errores en la terminal.

3. Escribe el Route Handler que lee la tabla de Airtable

Pon la lógica de obtención (fetch) en un módulo que tanto el Route Handler como la página puedan importar, así el token se lee en un solo lugar y la paginación se gestiona una vez. Cada registro devuelve un objeto id, un createdTime y un fields , que es lo que reflejan los tipos.

Crea lib/airtable.ts para que lea las tres variables una vez y haga un bucle hasta que Airtable deje de enviar un desplazamiento (offset):

export type AirtableRecord = {
  id: string;
  createdTime: string;
  fields: Record<string, unknown>;
};

type AirtableResponse = {
  records: AirtableRecord[];
  offset?: string;
};

export async function getRecords(): Promise<AirtableRecord[]> {
  const token = process.env.AIRTABLE_TOKEN;
  const baseId = process.env.AIRTABLE_BASE_ID;
  const tableId = process.env.AIRTABLE_TABLE_ID;

  if (!token || !baseId || !tableId) {
    throw new Error('AIRTABLE_TOKEN, AIRTABLE_BASE_ID and AIRTABLE_TABLE_ID must be set');
  }

  const records: AirtableRecord[] = [];
  let offset: string | undefined;

  do {
    const url = new URL(`https://api.airtable.com/v0/${baseId}/${tableId}`);
    if (offset) url.searchParams.set('offset', offset);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${token}` },
    });

    if (!res.ok) {
      throw new Error(`Airtable responded with ${res.status}`);
    }

    const data = (await res.json()) as AirtableResponse;
    records.push(...data.records);
    offset = data.offset;
  } while (offset);

  return records;
}

El bucle sigue el offset token de Airtable hasta que una respuesta lo omite, por lo que una tabla de más de una página se devuelve completa en lugar de truncarse en la primera página.

Luego, añade el Route Handler en app/api/records/route.ts:

import { NextResponse } from 'next/server';
import { getRecords } from '@/lib/airtable';

export async function GET() {
  try {
    const records = await getRecords();
    return NextResponse.json({ records });
  } catch {
    return NextResponse.json(
      { error: 'Unable to load records' },
      { status: 502 },
    );
  }
}

Webflow Cloud ejecuta el controlador en Cloudflare Workers mediante el adaptador OpenNext Cloudflare. Omite la línea export const runtime = 'edge' porque el adaptador no admite el destino de tiempo de ejecución edge independiente de Next.js. Añadir esa directiva rompe la compilación.

El controlador devuelve un 502 ante cualquier error detectado al cargar los registros, sin exponer el mensaje de excepción interno en la respuesta pública. Ejecuta curl http://localhost:3000/api/records, y deberías obtener un cuerpo JSON con una matriz records.

4. Renderiza los registros en una página

Llama a getRecords() directamente desde un componente de servidor. En Webflow Cloud, esto ahorra un viaje de ida y vuelta HTTP y evita construir una URL absoluta que deba conocer la ruta de montaje.

Reemplaza app/page.tsx con un componente de servidor que asigne los registros a tu marcado.

Una línea aquí hace el trabajo que promete el título, y dejarla fuera es la forma más común en que esta compilación decepciona. Next.js prerrenderiza estáticamente una ruta que espera una función del lado del servidor sin entrada en tiempo de solicitud, lo que significa que Airtable se llama una vez, en next build, y cada visitante posterior obtiene esa instantánea.

export const dynamic = 'force-dynamic' permite que la página se renderice por solicitud, lo que hace que los datos estén en vivo en lugar de estar simplemente frescos al momento de la implementación:

import { getRecords } from '@/lib/airtable';

// Without this the route is prerendered and Airtable is read once,
// at build time. Editors then change a row and nothing moves.
export const dynamic = 'force-dynamic';

export default async function Page() {
  const records = await getRecords();

  return (
    <main>
      <h1>Inventory</h1>
      <ul>
        {records.map((record) => (
          <li key={record.id}>
            {String(record.fields['Name'] ?? 'Untitled')}
          </li>
        ))}
      </ul>
    </main>
  );
}

fields está codificado exactamente por los nombres de tus columnas de Airtable tal como están escritos, incluidos espacios y mayúsculas, por lo que record.fields['Name'] coincide con una columna titulada Name. Reduce cada valor antes de renderizar: Airtable devuelve los archivos adjuntos como matrices de objetos y los registros vinculados como matrices de ID de registro, y un objeto vacío dentro de JSX genera un error en tiempo de renderizado. Las celdas vacías se omiten de fields por completo, razón por la cual existe la alternativa a 'Untitled'.

Un componente de cliente, como un filtro o un cuadro de búsqueda, a veces necesita la ruta. Webflow Cloud inyecta basePath en tiempo de compilación y deja las llamadas de obtención del lado del cliente sin cambios, por lo que debes añadir el prefijo a la URL tú mismo.

Usa esta línea única tanto en next dev como en la ruta de montaje implementada:

const res = await fetch(`${process.env.NEXT_PUBLIC_BASE_PATH ?? ''}/api/records`);

El prefijo NEXT_PUBLIC_ hace que esa variable esté disponible en el paquete del navegador. AIRTABLE_TOKEN permanece en el servidor porque carece del prefijo. Recarga http://localhost:3000 y deberías ver un elemento de lista por cada registro de Airtable, extraído en vivo de la base.

5. Implementa la aplicación en Webflow Cloud

Crea un entorno de Webflow Cloud para la aplicación y asígnale una ruta de montaje, por ejemplo, /inventory. La ruta de montaje es el valor que lee tu código de cliente, por lo que se incluye en el entorno como una variable junto con los valores de Airtable.

En la configuración del entorno, añade estas cuatro variables:

La documentación de las variables de entorno de Webflow establece que "tanto las variables de entorno secretas como las no secretas están disponibles para el proceso de compilación de su aplicación (por ejemplo, para la configuración del marco de autenticación) y siguen estando disponibles para la aplicación implementada en tiempo de ejecución".

Ese simple hecho es la razón por la que basta con un solo conjunto de valores: se integra en el paquete del cliente durante la compilación, y es legible por el Worker en el momento de la solicitud. Los secretos se ocultan en los registros de compilación, así que asegúrese de marcar el token como tal.NEXT_PUBLIC_BASE_PATHAIRTABLE_TOKEN

Implemente el entorno y espere a que finalice la compilación. Abra la ruta de montaje configurada, , y debería ver la misma lista que vio localmente./inventory

¿Qué provoca que una recuperación de Airtable falle en Webflow Cloud?

Las recuperaciones de Airtable suelen fallar debido a una directiva de tiempo de ejecución no compatible, una URL de ruta de montaje incorrecta, credenciales implementadas que no coinciden o suficientes solicitudes simultáneas como para activar el límite de velocidad de Airtable.

Identifique el síntoma visible y su causa, y aplique la solución a continuación antes de cambiar la implementación de la recuperación.

La compilación de Webflow Cloud falla durante la implementación mientras la misma ruta se compila localmente

Causa: Webflow Cloud ejecuta el controlador de ruta en Cloudflare Workers a través del adaptador OpenNext Cloudflare, que no admite el destino de tiempo de ejecución de Next.js por separado. La compilación local puede tener éxito incluso cuando interrumpe la compilación de Webflow Cloud más adelante.edgeexport const runtime = 'edge'

La misma distinción de tiempo de ejecución rige el middleware. La página de personalización del marco de trabajo de Webflow indica que el middleware utiliza el tiempo de ejecución Edge en los Workers. Un al estilo de Next 16 se ejecuta en el tiempo de ejecución de Node, no puede optar por Edge y genera un archivo que nunca se ejecuta.proxy.ts

Solución: Busque en cada controlador de ruta y página y elimine todas las apariciones. Si más adelante coloca la autenticación delante de , mantenga el nombre de archivo en lugar de reemplazarlo por .export const runtime = 'edge'/api/recordsmiddleware.tsproxy.ts

La ruta debería compilarse entonces para el tiempo de ejecución del Worker utilizado por Webflow Cloud.

/api/recordsdevuelve JSON localmente, pero el navegador recibe un 404 en Webflow Cloud

Causa: Una URL que comienza con se dirige a la raíz del sitio en lugar de a la aplicación montada porque las llamadas de recuperación del lado del cliente no se modifican. Bajo , la ruta de montaje está vacía, por lo que el código idéntico funciona localmente y el problema solo aparece después de la implementación./api/recordsnext dev

Inspeccione la URL de la solicitud fallida para confirmar si incluye la ruta de montaje configurada, como ./inventory/api/records

Solución: Añada como prefijo a la URL del lado del cliente y verifique que la variable de entorno coincida con la ruta de montaje. Evite leer desde ; la página de personalización de Next.js dice: "No es necesario añadir un adaptador, una ruta base o un modo de salida", y el valor no está disponible para que su código lo importe.process.env.NEXT_PUBLIC_BASE_PATH ?? ''basePathnext.config

Un componente de servidor puede llamar a directamente, eliminando la recuperación del cliente para ese componente.getRecords()

Airtable devuelve un 401 o 403 en Webflow Cloud, pero el mismo código funciona bajonpm run dev

.env.localCausa: permanece en su máquina, por lo que una solicitud local exitosa no confirma que el Worker implementado tenga el mismo token, ID de base, ID de tabla o ruta de montaje.

Utilice la respuesta y su origen para aislar el problema implementado:

Solución: Abre las variables del entorno, confirma que las cuatro existen con los nombres exactos que lee el código y vuelve a desplegar. En Airtable, abre el token en el Developer Hub y confirma que tiene el data.records:read ámbito y acceso solo a la base requerida; si no puedes verificar el valor almacenado, vuelve a generarlo.

Un registro temporal de res.status dentro de getRecords(), nunca el token en sí, confirma qué respuesta de Airtable has recibido.

Airtable empieza a devolver errores 429 cuando la página recibe tráfico real

Causa: Cada renderizado del componente del servidor y cada acceso al Route Handler llaman a Airtable, y el bucle de paginación multiplica eso: una tabla que abarca varias páginas supone varias solicitudes por renderizado.

Airtable limita la API a 5 solicitudes por segundo por base, con un tope adicional de 50 solicitudes por segundo para todo el tráfico de un mismo token. Si lo superas, recibirás un 429 y tendrás que esperar 30 segundos para que las solicitudes vuelvan a funcionar.

He visto cómo esto da problemas el día del lanzamiento, cuando el enlace de un boletín convierte una página interna tranquila en una ráfaga de renderizados simultáneos que llegan a Airtable a la vez. El patrón de tráfico activa el límite.

Solución: Aplica un límite de solicitudes o de concurrencia a nivel de aplicación antes de la llamada a Airtable. El almacenamiento en caché del navegador o compartido puede reducir las solicitudes repetidas, pero el tráfico directo que evita la caché sigue necesitando una limitación de tasa.

Pide menos: usa un view parámetro de consulta para que Airtable filtre y ordene desde el servidor, y un fields[] parámetro para que solo recibas las columnas que vas a mostrar.

Si tienes una página pública con mucho tráfico, considera servir datos sincronizados desde un CMS en lugar de llamar a Airtable en cada solicitud; así podrás consultar Airtable según el horario que tú decidas.

Qué puedes construir a continuación con Airtable y Webflow

Cuando necesites mostrar registros que cambian cada hora y que no requieren aparecer en los resultados de búsqueda, te recomiendo usar el patrón de Route Handler en vivo. Una vez que los registros de Airtable se integran en el diseño de tu sitio, la pregunta clave es qué datos deben ir en cada lugar.

Todo lo que los editores deban gestionar en Webflow, indexar para SEO o traducir, debe ir al CMS. El CMS componible de Webflow ofrece APIs REST para integraciones más avanzadas.

Para una personalización más profunda de lo que permite una simple consulta de Route Handler, empieza por las secciones de Webflow Cloud y la API del CMS en la documentación para desarrolladores de Webflow.