Cómo exportar publicaciones del blog de Webflow para una migración usando la API de CMS y Webflow Cloud

Migrar un blog fuera de Webflow rara vez es una tarea rápida. Dado que configurar el sistema de destino suele llevar varias semanas y es posible que se siga publicando contenido nuevo durante ese tiempo, una exportación inicial puede dejarte con datos obsoletos.

La plataforma de destino puede tardar semanas en configurarse. Mientras tanto, el equipo editorial sigue publicando, por lo que una exportación realizada el primer día queda desactualizada para cuando llega el momento del cambio, y una migración basada en ella ignora silenciosamente todo lo que se publicó en el ínterin.

La exportación CSV predeterminada de Webflow convierte las referencias en texto o listas separadas por comas, excluye el contenido multilingüe y requiere una operación manual. En esta guía de rutas de API, resolveremos estas limitaciones conservando los ID de los elementos, las vistas de localización y los indicadores de borrador/archivado, permitiendo además una ejecución repetible bajo demanda durante la transición.

¿Qué necesitas para exportar publicaciones de blog de Webflow en Webflow Cloud?

Debes preparar estos cinco requisitos previos:

• Sitio de Webflow con una colección de blog: Utiliza el sitio que contiene la colección de blog que deseas exportar.
• Node.js y npm: Instálalos localmente y conserva el archivo package-lock.json que genera npm como práctica estándar del proyecto.
• Next.js 15 o superior: Los requisitos mínimos del framework en la página de "bring-your-own-app" también mencionan Astro 6 o 7 y Vite 6.1 o superior.
• Detalles de la solicitud de API: Utiliza la referencia de la API de Webflow para identificar los requisitos de autenticación utilizados para la solicitud.
• ID de la colección de blog y un token del CMS: El ID de la colección, obtenido desde su panel de configuración en el Designer, y un token de API del sitio con el CMS:read alcance necesario, desde Configuración del sitio > Aplicaciones e integraciones > Acceso a la API.

Con estos requisitos previos listos, la construcción depende de configurar la solicitud correctamente y mantener sus credenciales en el servidor.

6 pasos para exportar publicaciones de blog de Webflow en Webflow Cloud

Exportar publicaciones de blog de Webflow requiere seis pasos: preparar la estructura de la aplicación, configurar su entorno, obtener y aplanar los elementos del CMS, serializarlos, proteger la ruta y desplegarla en Webflow Cloud.

Las comprobaciones locales validan cada parte de la construcción antes de desplegar la ruta finalizada.

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

La documentación de Webflow Cloud indica, textualmente: "Actualmente, Webflow Cloud solo admite el gestor de paquetes npm". Fija la versión de create-next-app a la versión principal de Next.js 15 compatible y utiliza npm para la estructura y el archivo de bloqueo de dependencias.

Durante la configuración, elige TypeScript y el App Router. Mantén los archivos del proyecto en la raíz rechazando el directorio src, de modo que el @/ alias predeterminado apunte a la raíz del proyecto, donde residirá la carpeta lib.

Ejecuta el andamiaje y responde a sus indicaciones de configuración con estas opciones:

npx create-next-app@15 blog-export
cd blog-export
npm run dev

Las opciones de Tailwind y ESLint son independientes de la exportación.

El archivo package-lock.json generado registra el árbol de dependencias de npm para instalaciones reproducibles. Mantén los archivos generados sin cambios y coloca el código de exportación en su propia carpeta y en un archivo de ruta.

Con el servidor de desarrollo en marcha, la página predeterminada de Next.js se renderiza en localhost:3000, lo que confirma que la cadena de herramientas funciona antes de que toques Webflow.

2. Configura las variables de entorno

Localmente, los ajustes de solicitud, el secreto de ruta y la ruta de montaje del lado del navegador van en un .env.local archivo en la raíz del proyecto. En Webflow Cloud, se colocan en los ajustes de variables de entorno del entorno, marcando los encabezados de la API y el secreto como confidenciales para que se oculten en los registros de compilación.

La página de "bring-your-own-app" de Webflow indica que "tanto las variables de entorno secretas como las no secretas están disponibles para el proceso de compilación de tu aplicación... y permanecen disponibles para la aplicación desplegada en tiempo de ejecución", por lo que un valor configurado una vez sirve tanto para la compilación como para la ruta en ejecución. Genera un secreto aleatorio con openssl rand -hex 32.

Configura estas cuatro variables:

• WEBFLOW_API_TOKEN: El token de la API del sitio con el CMS:read ámbito. Márcalo como secreto en Webflow Cloud para que el registro de compilación lo oculte.
• WEBFLOW_COLLECTION_ID: El ID de la colección del blog que se va a exportar.
• EXPORT_SECRET: Una cadena larga y aleatoria que el emisor envía en un encabezado x-export-secret. Se requiere un valor coincidente; las discrepancias devuelven un 401 antes de que la ruta contacte con Webflow.
• NEXT_PUBLIC_BASE_PATH: La ruta de montaje de la aplicación en tu sitio. Un botón de descarga del lado del navegador la utiliza porque las llamadas fetch del cliente no se reescriben con la ruta base.

Con estos cuatro valores configurados, los entornos local y desplegado pueden ejecutar la misma ruta sin almacenar credenciales en el repositorio. Guarda el archivo local y reinicia el servidor de desarrollo; Next lee los archivos env al iniciarse, por lo que cualquier valor añadido a mitad de la sesión permanecerá indefinido hasta el reinicio.

En Webflow Cloud, confirma que las cuatro variables aparecen en el entorno y que WEBFLOW_API_TOKEN y EXPORT_SECRET están marcadas como secretas.

Mantener las credenciales en el panel de entorno hace que el repositorio sea seguro para una entrega a una agencia: el cliente puede rotar el token en un panel mientras el código permanece intacto.

3. Obtén y aplana las publicaciones

Mantener el extractor en un módulo sencillo te permite verificar los tipos y reutilizarlo sin tener una solicitud a mano. Llama al endpoint list-items de Webflow, GET https://api.webflow.com/v2/collections/{collection_id}/items y tiene que paginar.

Ese endpoint devuelve 25 elementos cuando no pasas ningún limit y 100 como máximo, por lo que una sola solicitud contra un blog de 400 publicaciones devuelve 25 publicaciones con un 200 y sin errores, y una migración basada en esto dejaría silenciosamente la mayor parte del blog atrás.

Paginación y aplanamiento de elementos

El bucle a continuación lee pagination.total y sigue solicitando 100 a la vez hasta obtener cada elemento, esperando un 429 durante el tiempo que indique el encabezado Retry-After. Luego, aplana cada publicación en claves de cadena de un solo nivel. Los objetos anidados se convierten en claves de ruta con puntos y las matrices permanecen como cadenas JSON.

Esto preserva cualquier campo de referencia devuelto como una matriz y evita una cadena de comas ambigua. Esas referencias son IDs de elementos, no nombres, así que exporta las colecciones de autor y categoría de la misma manera y únelas por ID en el destino. El texto enriquecido también puede contener instancias de componentes de Webflow como <wf-component> marcado, que otras plataformas no renderizarán.

Se han integrado dos decisiones de alcance. La ruta lee el /items endpoint de ensayo en lugar del /items/live de producción, por lo que los borradores no publicados y las publicaciones archivadas también se mueven, cada uno con su isDraft y isArchived indicador para que los asignes al campo de estado del destino. Y lee una configuración regional: según la documentación de localización de Webflow, "Si omites el cmsLocaleId parámetro, la API devolverá elementos de la configuración regional principal".

En un sitio multilingüe, añade un cmsLocaleId parámetro de consulta, que acepta una lista de IDs de configuración regional de CMS separados por comas, o las traducciones se quedarán atrás. El archivo de ruta no tiene una directiva de tiempo de ejecución porque el adaptador OpenNext Cloudflare de Webflow Cloud no puede compilar el destino de tiempo de ejecución edge de Next.js.

Implementación de lib/export.ts

Guarda esto como lib/export.ts:

// lib/export.ts
export type FlatRow = Record<string, string>;

const PAGE_SIZE = 100; // the endpoint's documented maximum

export async function fetchPosts(): Promise<unknown[]> {
  const collectionId = process.env.WEBFLOW_COLLECTION_ID;
  const token = process.env.WEBFLOW_API_TOKEN;
  if (!collectionId || !token) {
    throw new Error('Set WEBFLOW_COLLECTION_ID and WEBFLOW_API_TOKEN');
  }

  const items: unknown[] = [];
  let offset = 0;
  let total = Infinity;

  while (offset < total) {
    const url = new URL(`https://api.webflow.com/v2/collections/${collectionId}/items`);
    url.searchParams.set('offset', String(offset));
    url.searchParams.set('limit', String(PAGE_SIZE));

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
    });

    if (res.status === 429) {
      // Wait as long as the documented Retry-After header says, then retry this page.
      const wait = Number(res.headers.get('Retry-After') ?? '5');
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
      continue;
    }
    if (!res.ok) {
      throw new Error(`CMS API returned ${res.status}`);
    }

    const page = (await res.json()) as { items?: unknown[]; pagination?: { total: number } };
    const batch = page.items ?? [];
    items.push(...batch);
    total = page.pagination?.total ?? items.length;
    if (batch.length === 0) break; // never loop forever on an unexpected response
    offset += batch.length;
  }

  return items;
}

export function flatten(value: unknown, prefix = '', out: FlatRow = {}): FlatRow {
  if (value === null || value === undefined) {
    out[prefix] = '';
  } else if (Array.isArray(value)) {
    out[prefix] = JSON.stringify(value);
  } else if (typeof value === 'object') {
    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
      flatten(child, prefix ? `${prefix}.${key}` : key, out);
    }
  } else {
    out[prefix] = String(value);
  }
  return out;
}

Ejecuta npx tsc --noEmit, y pasará sin problemas. La función de aplanamiento convierte cualquier forma de elemento devuelto en filas planas, por lo que un nuevo tipo de campo añadido a la colección aparece como una nueva clave. El número de elementos que devuelve fetchPosts es el recuento que informa el encabezado X-Export-Count una vez que existe el controlador de ruta.

4. Serializa la exportación con una suma de comprobación

El formato de comillas estilo RFC 4180 y los finales de línea CRLF (retorno de carro más avance de línea) hacen que la salida CSV sea compatible con importadores basados en tablas. Una segunda función pura calcula un resumen hexadecimal SHA-256 de cualquier cuerpo que la ruta esté a punto de enviar.

JSON es el valor predeterminado porque su escape preserva los cuerpos de los blogs en HTML durante la transferencia. CSV permanece disponible detrás de un parámetro de consulta para plataformas de destino cuyo importador solo lee tablas. La suma de comprobación permite al destinatario probar que el archivo que importó coincide con el archivo que produjo la ruta, byte por byte. SHA-256 utiliza crypto.subtle.digest de Web Crypto, que proporcionan los Workers.

Pon el escritor CSV y el resumen en lib/serialize.ts:

// lib/serialize.ts
import type { FlatRow } from './export';

export function toCsv(rows: FlatRow[]): string {
  const columns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
  const escape = (cell: string) => `"${cell.replace(/"/g, '""')}"`;
  const lines = [
    columns.map(escape).join(','),
    ...rows.map((row) => columns.map((col) => escape(row[col] ?? '')).join(',')),
  ];
  return lines.join('\r\n');
}

export async function sha256Hex(text: string): Promise<string> {
  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
  return Array.from(new Uint8Array(digest))
    .map((byte) => byte.toString(16).padStart(2, '0'))
    .join('');
}

Web Crypto es la única dependencia de tiempo de ejecución. Vuelve a comprobar los tipos y los dos módulos estarán listos para el controlador de ruta.

5. Protege la ruta y conéctalo todo

Una ruta de exportación expone credenciales que pueden solicitar datos del CMS, por lo que una versión sin autenticar es un riesgo en el momento en que se despliega, especialmente en el sitio de un cliente. El filtro compara el encabezado x-export-secret con EXPORT_SECRET usando un bucle de comparación manual. Esto mantiene la misma ruta de código bajo next dev local y en el tiempo de ejecución de Workers desplegado.

Esta ruta de migración no incluye un limitador de tasa, por lo que cualquiera que obtenga el secreto de la ruta puede invocar solicitudes repetidas al CMS.

Mantén el secreto fuera de los paquetes del navegador, compártelo solo con el operador de la migración, rótalo después de usarlo y elimina o desactiva la ruta cuando la migración esté completa. NEXT_PUBLIC_BASE_PATH contiene solo la ruta de montaje pública; mantén EXPORT_SECRET y las credenciales de solicitud del CMS en variables del lado del servidor.

Pon la comparación en lib/auth.ts para que el controlador se mantenga breve:

// lib/auth.ts
export function secretMatches(header: string | null): boolean {
  const expected = process.env.EXPORT_SECRET ?? '';
  const given = header ?? '';
  if (expected.length === 0 || expected.length !== given.length) {
    return false;
  }
  let diff = 0;
  for (let i = 0; i < expected.length; i++) {
    diff |= expected.charCodeAt(i) ^ given.charCodeAt(i);
  }
  return diff === 0;
}

El controlador de ruta verifica el encabezado, obtiene y aplana las publicaciones, serializa las filas, calcula el resumen y devuelve la respuesta.

Implementación: app/api/export/route.ts

Crea app/api/export/route.ts para componer los tres módulos:

// app/api/export/route.ts
import { fetchPosts, flatten, type FlatRow } from '@/lib/export';
import { toCsv, sha256Hex } from '@/lib/serialize';
import { secretMatches } from '@/lib/auth';

export async function GET(request: Request) {
  if (!secretMatches(request.headers.get('x-export-secret'))) {
    return new Response('Unauthorized', { status: 401 });
  }

  const format = new URL(request.url).searchParams.get('format') === 'csv' ? 'csv' : 'json';

  let rows: FlatRow[];
  try {
    rows = (await fetchPosts()).map((item) => flatten(item));
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Export failed';
    return new Response(message, { status: 502 });
  }

  const body = format === 'csv' ? toCsv(rows) : JSON.stringify(rows, null, 2);
  const checksum = await sha256Hex(body);

  return new Response(body, {
    headers: {
      'Content-Type':
        format === 'csv' ? 'text/csv; charset=utf-8' : 'application/json; charset=utf-8',
      'Content-Disposition': `attachment; filename="blog-posts.${format}"`,
      'X-Export-Sha256': checksum,
      'X-Export-Count': String(rows.length),
    },
  });
}

Las solicitudes exitosas llevan la exportación y sus encabezados de verificación. Las solicitudes fallidas devuelven un 401 o 502 con un motivo.

Inicia el servidor de desarrollo, carga el secreto desde .env.local y solicita la ruta desde una segunda terminal:

: "${EXPORT_SECRET:?Load EXPORT_SECRET from .env.local}"
curl -i -H "x-export-secret: $EXPORT_SECRET" http://localhost:3000/api/export

Esa solicitud devuelve un código 200 con un cuerpo JSON de filas planas. Una solicitud que omita la bandera -H devuelve un 401 antes de que se llame a la API de CMS. Un error 502 con un mensaje indica que el proceso de obtención falló, y el mensaje especifica qué configuración o estado lo provocó.

6. Despliega en Webflow Cloud y extrae la exportación

El archivo package-lock.json debe incluirse en el proyecto enviado. Configura la aplicación de Webflow Cloud y su ruta de montaje tal como se describe en la página de "bring-your-own-app", luego añade WEBFLOW_API_TOKEN, WEBFLOW_COLLECTION_ID, EXPORT_SECRET y NEXT_PUBLIC_BASE_PATH al entorno.

Deja next.config sin cambios para la ruta base. Webflow Cloud inyecta la ruta de montaje durante la compilación; la página de "bring-your-own-app" la define como "Sin adaptador, sin ruta base, sin wrangler.json".

Una vez que el registro de despliegue indique que la compilación ha finalizado, la ruta responderá en tu dominio más la ruta de montaje y /api/export. Carga el secreto de Webflow Cloud en EXPORT_SECRET, y establece WEBFLOW_APP_URL en el dominio desplegado más la ruta de montaje de la aplicación.

Extrae la exportación y verifícala:

: "${EXPORT_SECRET:?Load EXPORT_SECRET from Webflow Cloud}"
: "${WEBFLOW_APP_URL:?Set WEBFLOW_APP_URL to the deployed domain and mount path}"
curl -sS -D export-headers.txt \
  -H "x-export-secret: $EXPORT_SECRET" \
  "${WEBFLOW_APP_URL}/api/export?format=json" \
  -o blog-posts.json
grep -i 'x-export' export-headers.txt
shasum -a 256 blog-posts.json

El comando grep muestra X-Export-Count y X-Export-Sha256, y la salida de shasum coincide con la cabecera de suma de verificación. En Linux, ejecuta sha256sum blog-posts.json en su lugar.

El comando guarda blog-posts.json en el disco. Vuelve a ejecutar el mismo comando la mañana del cambio para que el archivo refleje la colección actual.

¿Qué causa que falle una exportación de blog de Webflow?

Una exportación de blog de Webflow suele fallar debido a un objetivo de tiempo de ejecución de Workers incompatible, una ruta de montaje incorrecta, APIs de sistema de archivos no disponibles o configuraciones de solicitud de CMS desplegadas que no son válidas.

El estado visible o el error de compilación te indicará qué categoría revisar primero.

La compilación de Webflow Cloud falla tras el despliegue aunque la compilación siguiente funcione localmente

Causa: Una compilación local de Next.js puede funcionar antes de que el adaptador OpenNext Cloudflare de Webflow Cloud rechace el objetivo de tiempo de ejecución "edge" de Next.js. La confusión surge porque la palabra "edge" significa dos cosas distintas en la misma página de documentación.

La página de "bring-your-own-app" indica que Webflow Cloud "despliega tu aplicación usando el tiempo de ejecución Edge" y que esta configuración permite un "alojamiento rápido y distribuido globalmente". Esto describe la plataforma: Cloudflare Workers, una red de borde (edge network).

La misma página también te indica que añadas la directiva de tiempo de ejecución edge de Next.js a las rutas de la API, lo cual nombra al objetivo de tiempo de ejecución de Next.js, algo distinto que OpenNext no puede compilar. Un desarrollador que siga esa instrucción al pie de la letra enviará una compilación rota.

Solución: Elimina la línea export const runtime = 'edge' de cada archivo de ruta y diseño. La plataforma ya ejecuta el controlador en Workers. Vuelve a desplegar y la ruta de exportación se compilará.

Una solicitud fetch del lado del cliente a la ruta de exportación devuelve un 404 en la aplicación desplegada, pero funciona con next dev

Causa: Esto ocurre una vez que añades una interfaz a la aplicación. El controlador de ruta desplegado utiliza tu dominio seguido de la ruta de montaje de la aplicación y /api/export. La página de "bring-your-own-app" establece que "las llamadas fetch del lado del cliente deben incluir manualmente la ruta base", por lo que un componente que llame a fetch('/api/export') solicita la raíz del sitio; la solicitud no encuentra la aplicación montada y devuelve un 404. Es probable que la llamada funcione en tu equipo porque next dev sirve la aplicación en la raíz.

Solución: Antepón a las llamadas del lado del navegador la variable NEXT_PUBLIC_BASE_PATH definida en el entorno. Antes de lanzar un disparador desde el navegador, evalúa qué expone: cualquier secreto utilizado en el código del navegador es visible para quien cargue la página, por lo que un disparador de navegador solo es adecuado para una herramienta interna protegida por su propio inicio de sesión, que suministra el secreto tras autenticarse. Para una migración, el comando curl con el secreto en una variable de shell es la opción más segura por defecto.

Antepón la llamada dentro de una función que invoque la herramienta interna:

export async function downloadExport(secret: string): Promise<Blob> {
  const base = process.env.NEXT_PUBLIC_BASE_PATH ?? '';
  const res = await fetch(`${base}/api/export?format=json`, {
    headers: { 'x-export-secret': secret },
  });
  if (!res.ok) {
    throw new Error(`Export request returned ${res.status}`);
  }
  return res.blob();
}

Llama a downloadExport después del paso de inicio de sesión de la herramienta y luego pasa el Blob resultante a un enlace de descarga.

La compilación o la primera solicitud fallan porque no se encuentra node:fs

Causa: Una escritura de archivo, generalmente para dejar la exportación en un directorio temporal antes de servirla, provoca este error. En Webflow Cloud, la aplicación se ejecuta en Workers con una fecha de compatibilidad fija y requiere una fecha de compatibilidad más reciente que la que establece Webflow Cloud.fs.writeFilenode:fs

La fecha de compatibilidad fija crea un comportamiento aparentemente inconsistente: se resuelve en el mismo tiempo de ejecución.node:path

Solución: Elimina la escritura y devuelve la exportación directamente como cuerpo de la respuesta, tal como lo hace app/api/export/route.ts. El encabezado Content-Disposition le indica al navegador o a curl que lo guarde como un archivo. Si necesitas que la exportación persista entre solicitudes, ese almacenamiento debe residir fuera del Worker, en lo que ya proporcione tu destino de migración o almacén de objetos.

La ruta desplegada devuelve un 502 con "CMS API returned 401" o "CMS API returned 404"

Causa: fetchPosts genera un error cuando la API de CMS responde con un estado que no es OK, y la ruta transmite ese mensaje como un 502. En términos HTTP estándar, un 401 o 403 generalmente indica que el WEBFLOW_API_TOKEN es incorrecto o carece del alcance necesario. La falta de configuración produce el mensaje "Set WEBFLOW_COLLECTION_ID and WEBFLOW_API_TOKEN".CMS:read

Un 404 generalmente indica que el WEBFLOW_COLLECTION_ID es incorrecto o pertenece a un sitio diferente al del token. Localmente, el mismo código puede funcionar porque .env.local contiene valores distintos a los del entorno de Webflow Cloud.

Solución: Restaura la configuración de solicitud desplegada a los valores validados por el comando curl local, vuelve a desplegar y ejecuta el comando desplegado nuevamente. Una respuesta exitosa devuelve la exportación con los encabezados X-Export-Count y X-Export-Sha256 en lugar del mensaje 502.

Qué puedes construir a continuación con la API de CMS de Webflow y Webflow Cloud

Una migración se ejecuta en una sola dirección, pero una ruta que lee la colección bajo demanda es útil mucho después de la transición: el mismo patrón alimenta un índice de búsqueda o produce una copia de seguridad nocturna que alguien puede comparar.

Si el objetivo resulta ser mantener otro sistema actualizado en lugar de abandonar Webflow, el patrón de sincronización de CMS es el mismo buscador con una inserción o actualización al final.