Optimizing your app for Webflow Cloud | Webflow Developer Documentation

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.

General recommendations

Serving assets from your Webflow site

To ensure your app is optimized for bandwidth, make sure to serve assets (like images, videos, and files) directly from your app, rather than proxying assets from your site. This helps reduce unnecessary data transfer and ensures your assets are delivered quickly and reliably.

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.

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

For images, it’s recommend to use the <img> tag instead of the <Image /> component. Using Next.js <Image /> component may serve the asset from a different origin, which may cause issues with caching and performance.

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 ---
2 import 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 ---
2 export 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>

Environment variables

Astro provides several ways to access environment variables, depending on where your code runs:

Use import.meta.env for built-in variables like BASE_URL and ASSETS_PREFIX, and for any custom variables prefixed with PUBLIC_. Using the PUBLIC prefix will make the variable available on both the server and the client.
Use Astro.locals.runtime.env in Astro server-side components to access custom environment variables.
Use locals.runtime.env in API routes to access custom environment variables.

To use locals.runtime.env variables during local development, create a dev.vars file in your project root. Use the same format as a standard .env file to define your environment variables.

Accessing environment variables in Astro

1 // 1. Built-in environment variables (available everywhere)
2 import.meta.env.BASE_URL
3 import.meta.env.ASSETS_PREFIX
4 
5 // 2. In Astro components (e.g., src/pages/foo.astro)
6 Astro.locals.runtime.env.VARIABLE_NAME
7 
8 // 3. In API routes (e.g., src/pages/api/foo.ts)
9 import type { APIRoute } from 'astro';
10 
11 export const GET: APIRoute = async ({ locals }) => {
12   const siteId = locals.runtime.env.WEBFLOW_SITE_ID;
13   const accessToken = locals.runtime.env.WEBFLOW_SITE_API_TOKEN;
14   // Use siteId and accessToken as needed
15 };

API routes

To ensure Astro API routes work on the Workers runtime, add the following line to the top of your route:

src/routes/api/hello.ts

1 // Add this line to your route to ensure it runs on the Edge runtime
2 export const config = {
3     runtime: "edge",
4 };
5 
6 import type { APIRoute } from 'astro';
7 
8 
9 export const GET: APIRoute = async ({ locals }) => {
10   return new Response(JSON.stringify({ message: 'Hello from the edge!', runtime }), {
11     status: 200,
12     headers: { 'Content-Type': 'application/json' }
13   });
14 };

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

Tailwind CSS

To use Tailwind CSS in your Astro project, use the @tailwindcss/vite plugin to ensure compatibility. Once you’ve created your Astro project from the CLI, follow the instructions in the Tailwind CSS integration for Astro guide to set up Tailwind CSS.

@astrojs/tailwind is not supported on Webflow Cloud

@astrojs/tailwind is deprecated and not supported on Webflow Cloud.

Third-party templates and guides may still reference it, but it’s not recommended to use it. Instead, upgrade to the latest version of Tailwind CSS and use the @tailwindcss/vite plugin to ensure compatibility.