Optimizing your app for Webflow Cloud

Adapt and optimize supported frameworks for deployment on Webflow Cloud.

Optimizing your app 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.

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 />

Webflow Cloud automatically handles routing through your base path when using the Next.js Image component, so you don’t need to manually add assetPrefix to your image paths.

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

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

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:

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

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:

astro.config.mjs

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.

@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.

Additional resources

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

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 />

Webflow Cloud automatically handles routing through your base path when using the Next.js Image component, so you don’t need to manually add assetPrefix to your image paths.

Next.js Image component with external images

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

Astro

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

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

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:

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

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:

astro.config.mjs

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

Assets

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

Tailwind CSS

@astrojs/tailwind is not supported on Webflow Cloud

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

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	/>

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	/>

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

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

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>

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

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

Environment configuration

Next.js

Images

Next.js Image component with local images

Next.js Image component with external images

Plain img tags

Limitations

Additional resources

Astro

Loading React components

Static pages

Environment variables

API routes

Enable Edge runtime for API routes

Disable Astro’s CSRF protection (if needed)

Assets

Tailwind CSS

@astrojs/tailwind is not supported on Webflow Cloud

Additional resources

Environment configuration

Next.js

Images

Next.js Image component with local images

Next.js Image component with external images

Plain img tags

Limitations

Additional resources

Astro

Loading React components

Static pages

Environment variables

API routes

Enable Edge runtime for API routes

Disable Astro’s CSRF protection (if needed)

Assets

Tailwind CSS

@astrojs/tailwind is not supported on Webflow Cloud

Additional resources

Plain `img` tags

Plain `img` tags