Adapting frameworks for Webflow Cloud

Adapt and optimize supported frameworks for deployment on Webflow Cloud.

Webflow Cloud supports the Next.js and Astro frameworks, though running either on the Workers runtime may require specific configuration or adjustments. This page offers guidance on framework-specific setup, limitations, and best practices to help you get the most out of your deployment.

Environment configuration

For general deployment and environment configuration, see the configuration guide. This page focuses on requirements and recommendations unique to each supported framework.

Next.js

Webflow Cloud deploys Next.js apps using the OpenNext Cloudflare adapter, an open-source tool that brings Next.js to the edge. It handles translating Next.js’s server-side features to the edge runtime, including routing, API routes, static assets, and server functions, enabling modern Next.js apps to run with minimal changes.

Not all Next.js features are fully supported yet—some, especially those tied to Node.js APIs, may need adaptation. For the latest compatibility details, see the OpenNext documentation.

To run your Next.js app on Webflow Cloud, you may need to adapt some features and provide custom configuration. See the sections below for details.

Images

The Next.js <Image /> component requires a custom loader to work properly on Webflow Cloud. Without this, images may not load for users in production.

Set up a custom image loader:

  1. Configure next.config.js:

    1module.exports = {
    2 images: {
    3 loader: 'custom',
    4 loaderFile: './imageLoader.ts',
    5 },
    6}
  2. Create imageLoader.ts in your project root:

    1// Helper function to remove leading slash from image paths
    2// Cloudflare's /cdn-cgi/image service expects paths without leading slashes
    3const normalizeSrc = (src: string) => src.startsWith('/') ? src.slice(1) : src;
    4
    5export default function cloudflareLoader({ src, width, quality }) {
    6 // In development, return the original src to avoid transformation
    7 // This prevents issues with local development servers
    8 if (process.env.NODE_ENV === 'development') return src;
    9
    10 // Build transformation parameters for Cloudflare's image service
    11 const params = [`width=${width}`];
    12 if (quality) params.push(`quality=${quality}`);
    13 const paramsString = params.join(',');
    14
    15 // Return the Cloudflare image transformation URL
    16 // Format: /cdn-cgi/image/{params}/{normalized_image_path}
    17 return `/cdn-cgi/image/${paramsString}/${normalizeSrc(src)}`;
    18}

This routes image requests through Cloudflare’s optimization service, ensuring reliable image delivery for all users.

Limitations

Some Next.js features have limitations when running on Webflow Cloud:

  • Middleware: Node.js runtime middleware isn’t supported. Only Edge runtime middleware works on the Workers runtime
  • ISR & On-demand revalidation: Incremental Static Regeneration and on-demand revalidation are experimental
  • Composable caching: The use cache directive isn’t yet supported

See the OpenNext Cloudflare adapter documentation for current feature support.

Additional resources

Astro

Webflow Cloud deploys Astro apps using the @astrojs/cloudflare adapter. The adapter supports server-side rendering, API routes, and advanced features like server islands and sessions—translating Astro’s server functionality to the Workers runtime for seamless edge deployment.

Most features work out of the box, but some Node.js APIs and integrations may need additional configuration. For details and advanced usage, see the Astro Cloudflare integration guide. However, we’ve outlined the most common adjustments below.

Loading React components

Be sure to add the client:load directive to your components to load your components.

src/pages/index.astro
1---
2import HelloWorld from '../components/HelloWorld';
3---
4
5<div class="container">
6 <HelloWorld client:load />
7</div>

Static pages

By default, all Astro routes are server-rendered on the edge. For static routes (such as a custom 404 page or privacy policy), enable pre-rendering to generate and serve them as static assets for faster loading.

src/pages/404.astro
1---
2export const prerender = true; // Pre-render the page for best performance
3---
4<html>
5 <body>
6 <h1>404: Not Found</h1>
7 <p>This page does not exist.</p>
8 </body>
9</html>

API routes

To ensure Astro API routes work on the Workers runtime, access the runtime context through context.locals.runtime.

src/routes/api/hello.ts
1import type { APIRoute } from 'astro';
2
3export const GET: APIRoute = async ({ context }) => {
4 // Required: Access the runtime context for edge runtime compatibility
5 const runtime = context.locals.runtime;
6 return new Response(JSON.stringify({ message: 'Hello from the edge!', runtime }), {
7 status: 200,
8 headers: { 'Content-Type': 'application/json' }
9 });
10};

Assets

Astro serves all static assets (such as images, stylesheets, and icons) from the public directory. Be sure to place all static files (images, CSS, fonts, etc.) in the public directory at your project root.

public/
├── images/
│ └── logo.png
├── styles/
│ └── global.css
└── favicon.ico

Image optimization

Astro’s default image optimization service isn’t supported on Webflow Cloud, but you can enable edge image optimization by configuring the Cloudflare image service in your astro.config.mjs. This lets you serve optimized images globally via Cloudflare’s infrastructure.

astro.config.mjs
1import { defineConfig } from "astro/config";
2import cloudflare from "@astrojs/cloudflare";
3import cloudflareImages from "@astrojs/image/cloudflare";
4
5export default defineConfig({
6 adapter: cloudflare(),
7 image: {
8 service: cloudflareImages(),
9 },
10});

Additional resources