Optimizing your app for Webflow Cloud

Webflow Cloud supports the Next.js, Astro, and Vite frameworks, though running any of them 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.

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

Webflow Cloud automatically optimizes images for better performance and reduced bandwidth usage. Here’s how different image types are handled:

Next.js Image component with local images

When you use the <Image /> component with local images Webflow Cloud automatically:

• Resizes images for optimal performance
• Serves images through Webflow’s CDN for faster loading
• Reduces bandwidth usage

Example:

1
import Image from 'next/image';
2
3
// This image will be automatically optimized
4
<Image
5
  src="/my-image.jpg"
6
  alt="Description"
7
  width={500}
8
  height={300}
9
/>

Next.js Image component with external images

When you use the <Image /> component with external images, including those from your main Webflow site, Webflow Cloud doesn’t automatically resize the image. However, you can still benefit from other Image component features like lazy loading.

1
// External images are not automatically optimized
2
<Image
3
  src="https://example.com/image.jpg"
4
  alt="External image"
5
  width={500}
6
  height={300}
7
/>

Plain img tags

When using regular <img> tags, no automatic optimization occurs. For assets in your /public folder, include assetPrefix in the src path to ensure proper CDN caching:

1
// Include assetPrefix for CDN caching
2
<img src={`${assetPrefix}/my-image.jpg`} alt="Description" />

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

• Cloudflare Adapter for Next.js
• Next.js Edge Runtime Documentation
• Cloudflare Workers Next.js Guide
• OpenNext x Cloudflare Images

Astro

Starting a new app

webflow cloud init scaffolds an Astro project for you, so you don’t pick a version — the CLI installs a supported one and keeps the template in step with Webflow Cloud.

To control the version yourself, create the project with Astro’s own tooling and deploy it as a bring-your-own-app. Webflow Cloud builds either kind of project the same way: it reads the version from your package.json and picks the adapter to match.

Ready-to-deploy examples

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.

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.

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 app root. Use the same format as a standard .env file to define your environment variables.

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_API_TOKEN;
14
  // Use siteId and accessToken as needed
15
};

API routes

Enable Edge runtime for API routes

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

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
};

Disable Astro’s CSRF protection (if needed)

You may encounter issues with POST requests containing form data. Disable Astro’s built-in CSRF protection and implement your own CSRF handling.

In your astro.config.mjs file, add the following:

1
{
2
  security: {
3
    checkOrigin: false,
4
  },
5
}

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 app root.

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

Tailwind CSS

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

Vite

Webflow Cloud deploys any Vite app — React, Vue, Svelte, vanilla JavaScript, or anything else Vite builds. If your package.json has a vite dependency and no more specific framework, Webflow Cloud builds it as a Vite app.

Ready-to-deploy examples

Each of these also has an -app-bindings variant with SQLite, KV, and object storage already wired up — for example hello-world-react-app-bindings.

Base path

Webflow Cloud sets Vite’s base option to your environment’s mount path at build time. Don’t set base yourself — it’s overwritten.

Read it through Vite’s standard import.meta.env.BASE_URL, which reflects whatever base was set to:

1
// BASE_URL is "/" locally and your mount path in production
2
const response = await fetch(`${import.meta.env.BASE_URL}api/users`);

Vite rewrites asset URLs in your HTML, CSS, and imported modules automatically. You only need BASE_URL for paths you build yourself, such as fetch calls and links constructed as strings.

Adding API routes

A Vite app is a single-page app by default, and Webflow Cloud serves it as static assets. If you want server-side routes, add a src/worker.ts that handles them and falls back to your static assets:

1
/// <reference types="@cloudflare/workers-types" />
2
3
interface Env {
4
  ASSETS: Fetcher;
5
}
6
7
export default {
8
  async fetch(request: Request, env: Env): Promise<Response> {
9
    const url = new URL(request.url);
10
11
    if (url.pathname.endsWith('/api/hello')) {
12
      return Response.json({ message: 'Hello from the edge!' });
13
    }
14
15
    // Anything else falls through to the built SPA
16
    return env.ASSETS.fetch(request);
17
  },
18
} satisfies ExportedHandler<Env>;

If you don’t provide one, Webflow Cloud generates the asset-serving worker above without the API branch, so a plain SPA needs no worker file at all.

The ASSETS binding is provided by the platform and serves your built client output. Your storage bindings arrive on the same Env object.

Environment variables

Vite only exposes variables prefixed with VITE_ to client-side code, and it inlines them into your bundle at build time.

1
interface Env {
2
  ASSETS: Fetcher;
3
  API_TOKEN: string; // Set in your Webflow Cloud environment variables
4
}
5
6
export default {
7
  async fetch(request: Request, env: Env): Promise<Response> {
8
    // env.API_TOKEN never reaches the browser
9
    return env.ASSETS.fetch(request);
10
  },
11
} satisfies ExportedHandler<Env>;

Static assets

Put static files in public/ at your app root. Vite copies them to the build output as-is and Webflow Cloud serves them through the CDN. Reference them with BASE_URL:

1
<img src={`${import.meta.env.BASE_URL}logo.svg`} alt="Logo" />

Local development

vite dev works with no additional setup. For a run against the Workers runtime with your storage bindings connected, install the Cloudflare plugin and Wrangler:

$
npm install --save-dev @cloudflare/vite-plugin wrangler

Then add the plugin to your config and run vite dev as usual. Wrangler emulates the runtime and bindings on your machine, so no Cloudflare account is needed.

1
import { defineConfig } from 'vite';
2
import react from '@vitejs/plugin-react';
3
import { cloudflare } from '@cloudflare/vite-plugin';
4
5
export default defineConfig({
6
  plugins: [react(), cloudflare()],
7
});

Webflow Cloud adds this plugin during its own build whether or not you install it, so adding it locally only changes your development experience.

Additional resources

• Cloudflare Vite plugin
• Vite base option
• Vite environment variables

Additional resources

• Deploying Astro to Cloudflare
• Cloudflare Workers framework guide for Astro
• Hybrid rendering in Astro