Cómo integrar Owl Carousel con Webflow Cloud para un slider basado en API

Owl Carousel es un plugin de jQuery, y la mayoría de los problemas que surgen al integrarlo en una aplicación React se deben a la sincronización: el archivo fuente del plugin captura window.jQuery en el momento en que se evalúa, por lo que jQuery debe existir en la ventana antes de que se cargue el módulo de Owl, y ambos deben estar totalmente fuera del renderizado del servidor.

En Webflow Cloud, surge un segundo inconveniente. Tu aplicación Next.js reside bajo una ruta de montaje en el sitio de Webflow (algo como /showcase), y las llamadas fetch del lado del cliente necesitan ese prefijo. Un carrusel que solo se colapsa en una columna apilada después de la implementación casi siempre es porque le falta este prefijo.

En esta versión, implementamos una aplicación Next.js en Webflow Cloud con un componente de cliente que inicializa Owl Carousel sobre diapositivas servidas por un Route Handler en la misma aplicación. Las diapositivas provienen de un archivo JSON incluido en el momento de la compilación, el cargador lee la ruta de montaje desde una variable de entorno pública y todo se monta en /showcase en el sitio.

¿Qué necesitas para integrar Owl Carousel en Webflow?

Esta configuración tiene cuatro requisitos previos. Webflow Cloud está incluido desde el plan de sitio Starter gratuito en adelante, y montar la aplicación en un dominio personalizado requiere el plan Premium o superior.

Todo lo demás es el conjunto de herramientas local estándar para un proyecto de Next.js:

• Un sitio de Webflow en cualquier plan actual: Los sitios Starter, Basic y Premium pueden alojar la aplicación, y puedes montarla en una ruta de un sitio que puedas editar.
• Una versión compatible de Node.js: Instálala localmente antes de empezar, ya que Webflow Cloud documenta los requisitos generales de Node para las compilaciones de aplicaciones.
• Una versión compatible de Next.js: La página de bring your own app de Webflow Cloud enumera los requisitos de Node y del framework, además del requisito exclusivo de npm.
• Recursos de imagen con URLs públicas: Un puñado es suficiente para las diapositivas, y los marcadores de posición de stock funcionan bien mientras conectas el carrusel.

Configura jQuery en la ventana y expón la ruta de montaje antes de escribir el slider. Cada requisito moldea el componente de cliente.

6 pasos para integrar Owl Carousel en Webflow Cloud

El navegador necesita un componente de cliente que configure window.jQuery, importe dinámicamente Owl Carousel y lo inicialice sobre las diapositivas obtenidas de un Route Handler en la misma aplicación. La URL de fetch debe incluir la ruta de montaje que Webflow Cloud inyecta en el momento de la compilación, y el Route Handler debe mantenerse fuera del entorno de ejecución edge de Next.js.

Veamos los pasos.

1. Prepara la aplicación Next.js e instala Owl Carousel

Usa npm install del primer comando y mantén package-lock.json en el repositorio. Webflow Cloud acepta npm como su gestor de paquetes. Su documentación indica: "Actualmente, Webflow Cloud solo admite el gestor de paquetes npm". Otros gestores no son compatibles.

El paquete owl.carousel se utiliza aquí como una compilación básica para navegador que lee window.jQuery cuando se ejecuta. Instala jQuery junto con Owl para que el global esté disponible cuando se cargue el plugin. Un cast alrededor de .owlCarousel() no proporciona una declaración para un módulo owl.carousel no resuelto.

Ahora deberías tener un proyecto que comienza con npm run dev y sirve la página predeterminada de Next.js en http://localhost:3000, con jquery y owl.carousel listados bajo dependencies en package.json.

2. Carga las hojas de estilo de Owl Carousel en el diseño raíz

Importa la hoja de estilo base y el tema predeterminado de Owl en app/layout.tsx para que se incluyan en cada página. La hoja de estilo base gestiona el escenario, el tamaño de los elementos y los cambios de posición aplicados al deslizar. Su tema predeterminado da estilo a las flechas de navegación y a los puntos.

Sin la hoja de estilo base, el plugin se inicializa y no registra errores, pero los elementos nunca forman un escenario horizontal, lo que dificulta la depuración más adelante.

Añade las importaciones encima de tu propia hoja de estilo global:

// app/layout.tsx
import type { Metadata } from 'next';
import 'owl.carousel/dist/assets/owl.carousel.min.css';
import 'owl.carousel/dist/assets/owl.theme.default.min.css';
import './globals.css';

export const metadata: Metadata = {
  title: 'Showcase',
  description: 'Featured work carousel',
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

El orden de importación importa aquí. Tu globals.css va al final, así que cualquier anulación que escribas para .owl-nav o .owl-dots ganará en la cascada sin !important.

Reinicia el servidor de desarrollo y abre la pestaña de Red del navegador: deberías ver las reglas de Owl integradas en el CSS de la página, y la página predeterminada debería verse igual porque nada en ella lleva aún una clase owl-carousel .

3. Crea el componente de cliente que inicializa Owl Carousel

Renderiza las diapositivas como marcado simple, luego establece window.jQuery e importa Owl dentro de useEffect. Un import 'owl.carousel' estático en la parte superior del archivo se eleva y evalúa antes de que se ejecute cualquier código del componente.

En ese punto, no hay window.jQuery en el navegador y no hay window en absoluto durante el prerrenderizado del servidor. Las importaciones dinámicas dentro del efecto se ejecutan solo en el navegador y solo después de haber asignado la variable global.

Crea el componente en app/components/OwlSlider.tsx:

'use client';

import { useEffect, useRef } from 'react';

export type Slide = { title: string; imageUrl: string; alt: string };

export default function OwlSlider({ slides }: { slides: Slide[] }) {
  const stageRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const el = stageRef.current;
    if (!el || slides.length === 0) return;

    let cancelled = false;
    let $owl: any = null;

    (async () => {
      const jq = (await import('jquery')).default;
      (window as any).jQuery = jq;
      (window as any).$ = jq;
      await import('owl.carousel');
      if (cancelled) return;

      $owl = jq(el) as any;
      $owl.owlCarousel({
        items: 3,
        margin: 16,
        loop: true,
        nav: true,
        dots: true,
        responsive: {
          0: { items: 1 },
          768: { items: 2 },
          1024: { items: 3 },
        },
      });
    })();

    return () => {
      cancelled = true;
      if ($owl) $owl.trigger('destroy.owl.carousel');
    };
  }, [slides]);

  return (
    <div ref={stageRef} className="owl-carousel owl-theme">
      {slides.map((slide) => (
        <div key={slide.imageUrl} className="item">
          <img src={slide.imageUrl} alt={slide.alt} />
          <p>{slide.title}</p>
        </div>
      ))}
    </div>
  );
}

La bandera canceled cubre los casos en los que el componente se desmonta mientras las importaciones aún se están resolviendo.

Para una comprobación rápida, renderiza OwlSlider desde app/page.tsx con tres objetos literales que coincidan con el tipo Slide . Deberías ver varios elementos en fila en una ventana amplia y un solo elemento en una estrecha, con flechas y puntos del tema predeterminado.

4. Sirve las diapositivas desde un Route Handler

Coloca los datos de las diapositivas detrás de GET /api/slides e importa el JSON de forma estática. Cloudflare Workers no puede leer un archivo de datos empaquetado a través de node:fs bajo la fecha de compatibilidad fijada de Webflow Cloud. La importación estática empaqueta el archivo en el momento de la compilación.

Cloudflare Workers expone node:fs solo con una fecha de compatibilidad posterior a la que fija Webflow Cloud. Por lo tanto, una llamada a readFileSync puede funcionar en tu portátil y fallar en la plataforma.

La plataforma sí proporciona node:path, por lo que la limitación es específica del acceso a archivos.

Comienza con el archivo de datos en data/slides.json:

[
  {
    "title": "Harbour Lights rebrand",
    "imageUrl": "https://placehold.co/800x600/1f2937/ffffff",
    "alt": "Harbour Lights brand posters pinned to a studio wall"
  },
  {
    "title": "Fielding annual report",
    "imageUrl": "https://placehold.co/800x600/334155/ffffff",
    "alt": "Open spread of the Fielding annual report on a desk"
  },
  {
    "title": "Ridgeway store launch",
    "imageUrl": "https://placehold.co/800x600/475569/ffffff",
    "alt": "Ridgeway storefront signage photographed at dusk"
  }
]

Cada objeto debe incluir las tres claves, porque el componente lee imageUrl para el src y alt para la accesibilidad.

El manejador tiene cuatro líneas una vez que los datos son una importación de módulo:

// app/api/slides/route.ts
import { NextResponse } from 'next/server';
import slides from '@/data/slides.json';

export async function GET() {
  return NextResponse.json(slides, {
    headers: {
      'Cache-Control': 'public, max-age=300',
    },
  });
}

Omítelaexport const runtime = 'edge'. Webflow Cloud implementa Next.js a través del adaptador OpenNext Cloudflare, el cual no es compatible con el entorno de ejecución (runtime) edge de Next.js.

Webflow Cloud funciona sobre Cloudflare Workers, y su documentación indica que el entorno de ejecución Edge ofrece un alojamiento rápido y distribuido globalmente. El objetivo de entorno de ejecución edge de Next.js es un concepto distinto. Añadir la directiva genera una compilación defectuosa.

La página de "bring-your-own-app" de Webflow Cloud sigue indicando que se añada la directiva a las rutas de la API, razón por la cual este error sigue apareciendo.

Accede a http://localhost:3000/api/slides en el navegador y deberías recibir tu matriz JSON con un estado correcto y la cabecera de caché visible en la respuesta.

5. Obtén las diapositivas incluyendo la ruta de montaje

Antepón la ruta de montaje de NEXT_PUBLIC_BASE_PATH a cada solicitud desde el lado del navegador. Una solicitud relativa a la raíz hacia /api/slides abandona la aplicación montada tras la implementación.

Webflow Cloud inyecta basePath en la compilación de Next.js automáticamente; la documentación es clara: "No necesitas añadir un adaptador, una ruta base ni un modo de salida". El enrutamiento del lado del servidor detecta la ruta, mientras que las solicitudes del lado del navegador requieren el prefijo. La página de "bring-your-own-app" explica la consecuencia directamente: "Las llamadas fetch del lado del cliente deben incluir manualmente la ruta base".

NEXT_PUBLIC_BASE_PATH contiene datos de enrutamiento públicos que no son confidenciales, por lo que exponerlos al navegador es adecuado.

El cargador en sí es pequeño y la ruta base se lee una vez en el ámbito del módulo:

'use client';

import { useEffect, useState } from 'react';
import OwlSlider, { type Slide } from './OwlSlider';

const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? '';

export default function SlidesLoader() {
  const [slides, setSlides] = useState<Slide[]>([]);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    fetch(`${basePath}/api/slides`)
      .then((res) => {
        if (!res.ok) throw new Error(`Slides request failed with ${res.status}`);
        return res.json() as Promise<Slide[]>;
      })
      .then(setSlides)
      .catch((err: Error) => setError(err.message));
  }, []);

  if (error) return <p role="alert">{error}</p>;
  return <OwlSlider slides={slides} />;
}

Renderiza SlidesLoader desde app/page.tsx en lugar de la matriz codificada. Localmente, deja NEXT_PUBLIC_BASE_PATH sin definir para que la solicitud fetch vaya a /api/slides; en Webflow Cloud, asígnale el valor de la ruta de montaje en las variables de entorno. Los valores de NEXT_PUBLIC_ se insertan durante la compilación.

Eso funciona aquí porque Webflow Cloud expone las variables de entorno tanto a la compilación como a la aplicación desplegada en tiempo de ejecución: "Tanto las variables de entorno secretas como las no secretas están disponibles para el proceso de compilación de tu aplicación y para la aplicación desplegada en tiempo de ejecución".

Recarga la página local y el carrusel debería poblarse ahora desde la ruta de la API.

6. Despliega la aplicación en Webflow Cloud y móntala en una ruta

La ruta de montaje y la variable de entorno pública deben coincidir. Crea un entorno con una ruta de montaje de /showcase y, en las variables de ese entorno, añade NEXT_PUBLIC_BASE_PATH con el valor /showcase. Usa la barra diagonal inicial y omite la barra diagonal final.

Sigue el flujo actual de despliegue y publicación de Webflow Cloud. Montar la aplicación en un dominio personalizado requiere un plan Premium o superior.

Abre https://your-site-domain/showcase, y deberías ver el mismo carrusel que tenías localmente, y https://your-site-domain/showcase/api/slides debería devolver el JSON. Si la página se renderiza pero las diapositivas no aparecen, revisa primero la variable de entorno.

¿Qué causa que una integración de Owl Carousel falle en Webflow Cloud?

Empieza por la consola y el registro de compilación. Las señales comunes apuntan a una ruta de montaje faltante, una directiva de entorno de ejecución incompatible, una evaluación temprana del módulo Owl o acceso a archivos a través de node:fs.

Cada categoría genera un mensaje de error específico, lo que facilita aislar la solicitud o importación fallida.

La consola muestra "SyntaxError: Unexpected token '<'" and the carousel stays empty

Causa: La solicitud llegó al enrutamiento del sitio de Webflow y devolvió una página HTML 404. Llamar a .json() en esa respuesta genera un error de sintaxis porque el cargador espera una matriz JSON, no el marcado de página devuelto. Esto generalmente significa que el navegador solicitó /api/slides desde la raíz del sitio en lugar de solicitar la ruta bajo la ruta de la aplicación montada.

Solución: Configura NEXT_PUBLIC_BASE_PATH en el entorno de Webflow Cloud incluso si también existe en tu .env.local local, y haz coincidir la ruta de montaje carácter por carácter. Luego vuelve a implementar porque los valores de NEXT_PUBLIC_ se integran durante el tiempo de compilación.

Abre la solicitud fallida en la pestaña Red e inspecciona su URL, el estado de la respuesta y el cuerpo de la respuesta. Una URL a la que le falta /showcase muestra que la variable estaba vacía durante la compilación. La solicitud corregida debería usar /showcase/api/slides y devolver la matriz JSON en lugar de HTML.

La implementación se detiene con un error de compilación en la ruta de las diapositivas

Causa: Una directiva de tiempo de ejecución edge de Next.js en la ruta entra en conflicto con la configuración del adaptador OpenNext Cloudflare utilizada por Webflow Cloud. El objetivo del tiempo de ejecución perimetral de Next.js es independiente del tiempo de ejecución de Cloudflare Workers que aloja la aplicación implementada, por lo que agregar la directiva puede interrumpir la compilación aunque la plataforma proporcione alojamiento distribuido globalmente.

Solución: Busca runtime = 'edge' en el repositorio y elimina la directiva de cada controlador de ruta y página de la aplicación. Esta línea suele provenir de un tutorial antiguo de Next.js, así que la busco antes de cada primera implementación.

Mantén el controlador de diapositivas como una función GET exportada estándar que devuelva NextResponse.json(slides). Luego vuelve a compilar y verifica el registro de la ruta de las diapositivas. La compilación debería completarse sin intentar apuntar a la configuración de tiempo de ejecución perimetral de Next.js no compatible.

"ReferenceError: window is not defined" durante la compilación, o "owlCarousel is not a function" en el navegador

Causa: Owl Carousel se evaluó antes de que jQuery se convirtiera en una variable global del navegador. Un prerrenderizado del servidor no tiene window, y una importación temprana del navegador deja a .owlCarousel() no disponible en el prototipo de jQuery.

Una importación estática se eleva antes de que el efecto del componente pueda asignar jQuery a window.jQuery y window.$, por lo que una declaración de componente de cliente por sí sola no soluciona el orden de evaluación.

Solución: Usa el orden de importación de componentes de cliente: importa jQuery dentro de useEffect, asígnalo a window.jQuery y window.$, importa owl.carousel, e inicialízalo. Una importación estática de Owl en cualquier componente puede romper la compilación, así que busca from 'owl.carousel' y import 'owl.carousel' y mueve cada coincidencia a un efecto.

Después del cambio, la compilación del servidor ya no debería evaluar Owl, y el navegador debería exponer .owlCarousel() después de que se resuelva la importación dinámica.

La ruta implementada devuelve 500 mientras que la misma ruta funciona con npm run dev

Causa: El controlador contiene una importación node:fs o una llamada readFileSync contra data/slides.json. La ejecución local de Node puede ocultar la limitación de acceso a archivos implementada porque el archivo está disponible para el proceso local.

Bajo la fecha de compatibilidad fijada de Webflow Cloud, el Worker implementado no puede usar ese archivo incluido a través de node:fs, aunque node:path esté disponible.

Solución: Reemplaza la lectura del sistema de archivos con una importación de módulo JSON estática. Importa slides desde @/data/slides.json en la parte superior del controlador de ruta, luego devuélvelo a través de NextResponse.json(slides).

La importación agrupa los datos en el momento de la compilación y elimina la lectura del archivo en tiempo de ejecución. Si los datos deben ser dinámicos, búscalos a través de HTTP desde su ubicación. Prueba /api/slides localmente, vuelve a implementar y confirma que la ruta montada devuelve la matriz JSON con una respuesta exitosa en lugar de un error del servidor.

Qué puedes construir a continuación con Owl Carousel y Webflow

El límite del controlador de ruta mantiene un intercambio posterior de CMS fuera del componente de cliente. El siguiente paso más común es reemplazar el archivo JSON con elementos del CMS de Webflow, para que los editores gestionen estudios de caso o productos en el CMS de Webflow y aparezcan en el carrusel en la siguiente solicitud.

La API REST del CMS devuelve elementos de colección que puedes asignar directamente al tipo Slide, y el token de la API pertenece a una variable de entorno secreta que solo se lee dentro del controlador, donde se redacta de los registros de compilación y nunca se envía al navegador.

El mismo patrón de carga también puede servir para un carrusel de testimonios o un muro de logotipos.

Explora la integración con Owl Carousel para descubrir más formas de conectar el slider con un proyecto de Webflow.