> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.webflow.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.webflow.com/_mcp/server. # Bring your own app > Configure your Next.js or Astro app to work with Webflow Cloud Webflow Cloud deploys your app using the [Edge runtime](/webflow-cloud/environment), enabling fast, globally distributed hosting. Before deploying to Webflow Cloud, your app may require some configuration to ensure compatibility with the Edge environment. These instructions guide you through deploying an existing Next.js or Astro app to Webflow Cloud. #### Get Started with Webflow Cloud To familiarize yourself with Webflow Cloud, try the walkthrough in [Get started with Webflow Cloud](/webflow-cloud/getting-started) first. **Time Estimate:** 30 minutes ## Prerequisites * A Webflow account * A GitHub account * One of the following applications in a GitHub repository: * An Astro app (version 5 or higher) * A Next.js app (version 15 or higher) * Node.js 22.0.0 or higher and `npm` installed * **Note:** Currently, Webflow Cloud supports only the `npm` package manager ## Fast path: one-click deploy To deploy an application from a GitHub repository quickly, click this button and follow the steps to deploy it to Webflow Cloud: [![Deploy to Webflow](https://webflow.com/img/deploy-dark.svg)](https://webflow.com/dashboard/cloud/deploy) The process prompts you to select a GitHub repository, install the GitHub app that gives Webflow access to the repository, and specify how to deploy it to Webflow Cloud. To generate a one-click deploy button, see [Deploy with one click](/webflow-cloud/deploy-button). ## Deploying an application from GitHub Follow these steps to deploy an application from a GitHub repository: 1. Log in to Webflow and go to your dashboard. 2. From your Workspace, click **New Project > App** and authorize Webflow to access your GitHub account. 3. Expand **Import a GitHub repository**, specify the GitHub organization and repository, and click the **Import** button next to the repository, as in this picture: Selecting the GitHub repository 4. Give the app a name for Webflow Cloud and select the branch to deploy as in this picture: Selecting the branch to deploy 5. Optional: Under **Advanced settings**, select the path to the root of the application and add any environment variables that the app needs. 6. Click **Deploy**. Webflow publishes the application and shows information about it. * To see information about applications that are part of a site, go to the site settings and click **Webflow Cloud**. The applications that are part of this site are listed. Then you can click an application to see information about its environments and deployments. Looking at the applications within a site * To see information about applications that are not within a site, go to the Workspace settings, where applications are listed next to sites. You can filter the list by clicking **All projects > Apps**. Looking at the applications within a workspace To get to its environments and deployments, open the application's settings and then click **Webflow Cloud**. ## Configuring applications for Webflow Cloud These sections describe how to ensure that your application runs properly on Webflow Cloud. ### Configure your app Webflow Cloud deploys your app on the [Edge runtime](/webflow-cloud/environment), enabling fast, globally distributed hosting. The Edge runtime environment differs from traditional Node.js servers, requiring specific configurations for compatibility. The following steps outline common migration patterns to help you adapt your application for Webflow Cloud. Depending on your application's specific requirements, you may need to make additional adjustments beyond these configurations. #### Next.js #### Webflow Cloud is compatible with Next.js 15 and higher Webflow Cloud is compatible with Next.js 15 and higher. If you're using a version of Next.js lower than 15, please upgrade to the latest version. #### Configure your base path In Webflow Cloud, your application is served from the mount path you configured in your environment settings. For example, if your mount path is `/app`, your application will be accessible at `yourdomain.webflow.io/app`. To ensure proper routing and asset loading, you must configure the `basePath` and `assetPrefix` properties in your `next.config.ts` file to match this mount path exactly. ```ts title="next.config.ts" module.exports = { // Configure the base path and asset prefix to reflect the mount path of your environment // For example, if your app is mounted at /app, set basePath and assetPrefix to '/app' basePath: '/app', assetPrefix: '/app', // Additional Next.js configuration options can be added here // For example: // output: 'standalone', // reactStrictMode: true, } ``` #### Install and configure OpenNext OpenNext is an adapter designed specifically for deploying Next.js applications to cloud environments like Webflow Cloud. By using OpenNext, you can deploy your Next.js app without managing complex infrastructure configurations yourself. 1. **Install OpenNext**
In your terminal, navigate to your app and run the following command to install OpenNext: ```bash npm install @opennextjs/cloudflare@1.6.5 ``` 2. **Configure OpenNext**
Create a new configuration file named `open-next.config.ts` in your app's root directory. This file configures OpenNext to work with Webflow Cloud's deployment environment. ```ts title="open-next.config.ts" import type { NextConfig } from "next"; import { defineCloudflareConfig } from "@opennextjs/cloudflare"; export default defineCloudflareConfig({ }); ``` #### Set up local testing for Webflow Cloud Webflow Cloud uses Wrangler - Cloudflare's CLI tool - to bridge the gap between local development and cloud deployment. By integrating Wrangler into your workflow, you can identify and resolve compatibility issues early, significantly reducing debugging time after deployment. 1. **Install Wrangler**
To get started, install and configure Wrangler as a dev dependency in your app. ```bash npm install wrangler --save-dev ``` 2. **Set up your Wrangler configuration**
Create a `wrangler.json` file in your app root that defines how your application will run in development. ```jsonc title="wrangler.json" { "$schema": "node_modules/wrangler/config-schema.json", "name": "nextjs", "main": ".open-next/worker.js", "compatibility_date": "2025-03-01", "compatibility_flags": [ "nodejs_compat" ], "assets": { "binding": "ASSETS", "directory": ".open-next/assets" }, "observability": { "enabled": true } /** Rest of Code **/ } ``` See the Cloudflare documentation for [more details on how to configure Wrangler](https://developers.cloudflare.com/workers/wrangler/configuration/). 3. **Create a Cloudflare environment file**
Create a new file named `cloudflare-env.d.ts` in your app's root directory. This file will allow you to use environment variables defined in your Webflow Cloud environment. ```ts title="cloudflare-env.d.ts" interface CloudflareEnv { } ``` 4. **Add the development preview command**
Add this script to your `package.json` file to enable local testing with Wrangler. This command builds your Next.js app and immediately serves it using the Edge runtime, giving you an exact preview of how your app will perform in production on Webflow Cloud: ```json title="package.json" "scripts": { // Existing scripts... "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview", // } ``` #### Define your Webflow Cloud framework configuration Create a `webflow.json` file at the root of your app to inform Webflow Cloud about your app's framework. ```json title="webflow.json" { "cloud": { "framework": "nextjs" } } ``` #### Astro #### Configure Astro for Webflow Cloud Configure Astro for deployment on Webflow Cloud by adding the following to your `astro.config.js` file: ```js title={"astro.config.js"} import { defineConfig } from "astro/config"; import cloudflare from "@astrojs/cloudflare"; // Import the Cloudflare adapter import react from "@astrojs/react"; // https://astro.build/config export default defineConfig({ // Server you app and assets from the correct mount path base: "/YOUR_MOUNT_PATH", build: { assetsPrefix: "/YOUR_MOUNT_PATH", }, output: "server", // Use the server output mode // Use the Cloudflare adapter adapter: cloudflare({ platformProxy: { enabled: true, }, }), // Enable React components integrations: [react()], // Optimize the build configuration for the Edge runtime vite: { resolve: { // Use react-dom/server.edge instead of react-dom/server.browser for React 19. // Without this, MessageChannel from node:worker_threads needs to be polyfilled. alias: import.meta.env.PROD ? { "react-dom/server": "react-dom/server.edge", } : undefined, }, }, }); ``` This configuration is essential for deploying your Astro app to Webflow Cloud. Here's a breakdown of what each part does: * **Sets the correct mount path**: Your app is served from a specific subdirectory in your Webflow Cloud environment (e.g., `/app`). The `base` and `build.assetsPrefix` options must match this path to ensure all routes and assets load correctly. * **Enables Edge runtime compatibility**: Webflow Cloud uses an [Edge runtime](/webflow-cloud/environment), not a traditional Node.js server. The `@astrojs/cloudflare` adapter compiles your app to be compatible with this serverless environment. * **Optimizes React for the Edge**: To prevent build errors, the `vite` configuration includes a production-specific alias for React. This forces the build to use `react-dom/server.edge`, which is designed for non-Node.js environments like Webflow Cloud. #### Set up local testing for Webflow Cloud Webflow Cloud uses Wrangler - Cloudflare's CLI tool - to bridge the gap between local development and cloud deployment. By integrating Wrangler into your workflow, you can identify and resolve compatibility issues early, significantly reducing debugging time after deployment. 1. **Install Wrangler**
To get started, install and configure Wrangler as a dev dependency in your app. ```bash npm install wrangler --save-dev ``` 2. **Set up your Wrangler configuration**
Create a `wrangler.json` file in your app root that defines how your application will run in development. ```jsonc title="wrangler.json" { "$schema": "node_modules/wrangler/config-schema.json", "name": "astro", "main": "./dist/_worker.js/index.js", "compatibility_date": "2025-04-15", "compatibility_flags": [ "nodejs_compat" ], "assets": { "binding": "ASSETS", "directory": "./dist" }, "observability": { "enabled": true } } ``` See the Cloudflare documentation for [more details on how to configure Wrangler](https://developers.cloudflare.com/workers/wrangler/configuration/). #### wrangler.json Use `wrangler.json` to preview your app locally with the Cloudflare Workers runtime. Keep this file aligned with the settings your app needs in Webflow Cloud. 3. **Create a Cloudflare environment file**
Create a new file named `worker-configuration.d.ts` in your app's root directory. This file will allow you to use environment variables defined in your Webflow Cloud environment. ```ts title="worker-configuration.d.ts" /* eslint-disable @typescript-eslint/no-empty-interface */ // Generated by Wrangler // After adding bindings to `wrangler.json`, regenerate this interface via `npm run cf-typegen` interface Env {} ``` 4. **Add the development preview command**
Add this script to your `package.json` file to enable local testing with Wrangler. This command builds your Astro app and immediately serves it using the Cloudflare Workers runtime, giving you an exact preview of how your app will perform in production on Webflow Cloud: ```json title="package.json" "scripts": { // Existing scripts... "preview": "astro build && wrangler dev", // } ``` #### Define your Webflow Cloud framework configuration Create a `webflow.json` file at the root of your app to inform Webflow Cloud about your application's framework. ```json title="webflow.json" { "cloud": { "framework": "astro" } } ``` ### Managing assets and APIs #### Next.js #### Asset references How you reference assets depends on which component you're using: **Next.js Image component**: Local images are automatically optimized and served through Webflow's CDN. ```tsx title="src/app/components/Logo.tsx" import Image from "next/image"; export function Logo() { return ( Logo ); } ``` **Plain img tags**: Must include `assetPrefix` to load correctly and enable CDN caching. ```tsx title="src/app/components/Icon.tsx" import config from "../../../next.config"; // Get the asset prefix from config const assetPrefix = config.assetPrefix || config.basePath || ''; export function Icon() { return ( Star icon ); } ``` #### APIs When using Next.js with a configured base path, there's an important distinction between API route definitions and client-side requests: 1. **Server-side API route handlers** are automatically mounted at your base path by Next.js. To ensure your API routes run on the Edge runtime, add the `export const runtime = 'edge';` directive to your API route. 2. **Client-side fetch calls** must ***manually*** include the base path to correctly reach your endpoints Without these adjustments, your API routes will not build properly and your client-side fetch calls will fail by targeting the wrong URL. Implement these patterns in all your APIs and client-side data fetching functions: ```tsx title="API Routes" // /src/pages/api/data.ts import { NextRequest, NextResponse } from 'next/server'; export async function GET(request: NextRequest) { return NextResponse.json({ message: 'Hello, world!' }); } ``` ```tsx title="Client-side fetch call" import config from "../next.config"; // Get the base path from config const basePath = config.basePath || ''; export async function fetchData() { const response = await fetch(`${basePath}/api/data`); return response.json(); } ``` #### Edge Runtime: Use \`fetch\` API The Edge runtime has limited API support. Stick to `fetch` for API calls and avoid third-party clients like `axios` which may not be compatible. #### Astro #### Asset references When deployed to Webflow Cloud, all your static assets must include the configured mount path to load correctly. Without this path prefix, browsers will request assets from the root domain, resulting in 404 errors. We recommend constructing asset paths using the `import.meta.env.ASSETS_PREFIX` variable, which references the `build.assetsPrefix` value you configured. Webflow Cloud will automatically configure a CDN for assets that use `import.meta.env.ASSETS_PREFIX` for improved loading performance. Implement this pattern in your components for reliable asset loading: ```tsx title="layouts/Layout.astro" --- // Get the assets prefix from config const assetsPrefix = import.meta.env.ASSETS_PREFIX || import.meta.env.BASE_URL || ''; --- Astro Basics ``` #### APIs 1. **Server-side API route handlers** are automatically mounted at your base path by Astro. However, **you must add** the following code to your API route to ensure it runs on the Edge runtime: ```tsx // Add this line to your route to ensure it runs on the Edge runtime export const config = { runtime: "edge", }; ``` 2. **Client-side fetch calls** must ***manually*** include the base path to correctly reach your endpoints Without these adjustments, your API routes will not build properly and your client-side fetch calls will fail by targeting the wrong URL. Implement these patterns in all your APIs and client-side data fetching functions: ```tsx title="Server-side API route" {1-4} // Add this line to your route to ensure it runs on the Edge runtime export const config = { runtime: "edge", }; import type { APIRoute } from 'astro'; // Sample data const users = [ { id: 1, name: 'Arthur Dent', email: 'arthur@earth.com' }, { id: 2, name: 'Ford Prefect', email: 'ford@betelgeuse.com' }, { id: 3, name: 'Zaphod Beeblebrox', email: 'zaphod@heartofgold.com' }, { id: 4, name: 'Trillian', email: 'trillian@earth.com' }, { id: 5, name: 'Marvin', email: 'marvin@paranoidandroid.com' } ]; export const GET: APIRoute = async ({ params, request, context }) => { const url = new URL(request.url); const id = url.searchParams.get('id'); if (id) { const user = users.find(user => user.id === parseInt(id)); if (!user) { return new Response(JSON.stringify({ error: 'User not found' }), { status: 404, headers: { 'Content-Type': 'application/json' } }); } return new Response(JSON.stringify(user), { status: 200, headers: { 'Content-Type': 'application/json' } }); } return new Response(JSON.stringify(users), { status: 200, headers: { 'Content-Type': 'application/json' } }); }; ``` ```tsx title="Client-side fetch call" --- // src/components/ViewProfile.jsx import { useState } from 'react'; export function ViewProfile({ userId }) { const [user, setUser] = useState(null); const [loading, setLoading] = useState(false); const fetchUserProfile = async () => { setLoading(true); try { // Get the base path for API requests const basePath = import.meta.env.BASE_URL || ''; // Include the base path in the fetch URL const response = await fetch(`${basePath}/api/users.json?id=${userId}`); if (!response.ok) { throw new Error('Failed to fetch user'); } const userData = await response.json(); setUser(userData); } catch (error) { console.error('Error fetching user:', error); } finally { setLoading(false); } }; return (
{user && (

{user.name}

Email: {user.email}

)}
); } ``` #### Edge Runtime: Use \`fetch\` API The Edge runtime has limited API support. Stick to `fetch` for API calls and avoid third-party clients like `axios` which may not be compatible. ### Configuring environment variables #### Access environment variable settings In Webflow Cloud, navigate to your app's environment settings: * If the application is in your Workspace: 1. Open the Dashboard, go to your Workspace settings, and click **All projects > Apps**. 2. Click the application to open its settings and then click **Webflow Cloud.** 3. In the table of apps, click the app. 4. In the table of environments, click the environment. 5. In the table, go to the **Environment variables** tab. * If the application is in a site: 1. Open the site settings and click **Webflow Cloud**. 2. In the table of apps, click the app. 3. In the table of environments, click the environment. 4. In the table, go to the **Environment variables** tab. #### Add and configure environment variables Add each environment variable that your application requires: 1. Click **Add Variable** 2. Enter a name for the variable, such as `DATABASE_URL` or `API_KEY` 3. Enter the value for the variable 4. Toggle **Secret Variable** for sensitive values that should be encrypted, such as API keys and tokens 5. Click **Add variable** Repeat this process for all required variables. #### Environment variables are only available at runtime Environment variables in Webflow Cloud are injected at runtime only and are not accessible during the build process. Keep the following in mind to avoid build failures: * Do not include environment variable validation or required checks that run during build time * Use conditional logic to handle cases where environment variables might be undefined during builds #### Access environment variables in your code Your environment variables are accessible in your code using the following methods. #### Next.js Next.js provides environment variables through the `process.env` object. ```ts title="Next.js" process.env.VARIABLE_NAME ``` #### Astro 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. ```ts title="Accessing environment variables in Astro" // 1. Built-in environment variables (available everywhere) import.meta.env.BASE_URL import.meta.env.ASSETS_PREFIX // 2. In Astro components (e.g., src/pages/foo.astro) Astro.locals.runtime.env.VARIABLE_NAME // 3. In API routes (e.g., src/pages/api/foo.ts) import type { APIRoute } from 'astro'; export const GET: APIRoute = async ({ locals }) => { const siteId = locals.runtime.env.WEBFLOW_SITE_ID; const accessToken = locals.runtime.env.WEBFLOW_API_TOKEN; // Use siteId and accessToken as needed }; ``` ### Deploying applications After configuring your app: #### Test your app in the local preview environment Before deploying, test your app locally in an environment that simulates Webflow Cloud. The `preview` script uses Wrangler to serve your app from the correct mount path. ```bash npm run preview ``` Your app will be available at `http://localhost:PORT/YOUR_MOUNT_PATH`, where `PORT` is the port number shown in your terminal and `YOUR_MOUNT_PATH` is the one you configured. #### Authenticate with Webflow In your terminal, run the following command to authenticate with Webflow: ```bash webflow auth login ``` This command opens a browser window to authenticate your Webflow account. After you grant access, the CLI saves a `WEBFLOW_API_TOKEN` to a `.env` file at the root of your app. The first time you run `webflow cloud deploy`, the CLI prompts you to choose the deploy target (site-attached or standalone) and the specific site or workspace — it does not pick one for you at login. You can skip this step and let `webflow cloud deploy` trigger the OAuth flow on demand. #### Deploy using the Webflow CLI After authenticating, run the following command to deploy your app: ```bash webflow cloud deploy ``` On the first run, the CLI prompts you to identify the deploy target — choose **Existing site** to attach the app to a Webflow site (mounted at a path like `/app`), or **New domain** to deploy as a standalone app hosted on its own subdomain. To skip these prompts in CI/CD, pass `--no-input` together with `--site-id` (site-attached) or `--workspace-id` (standalone). See the [`webflow cloud deploy` reference](/cli/command-reference#cloud-deploy) for all flags. Additionally, when you commit your changes to your GitHub branch, Webflow Cloud will automatically detect the changes and deploy your app to your environment. Learn more about [deployments in the documentation.](/webflow-cloud/deployments) #### Your deployment may take up to 2 minutes to complete View your deployment in the ["Environment Details"](/webflow-cloud/deployments#deployment-history) dashboard. Review the status of your deployment by viewing the [build logs](/webflow-cloud/deployments#build-logs). #### View your app at your site's URL + mount path Once your app has been successfully deployed, navigate to your site's domain and mount path to see your newly deployed Webflow Cloud app! ## Next steps Now that you've successfully deployed your app on Webflow Cloud, here's what you can do next. #### [Sync your Webflow design system](/devlink/reference/overview) Learn how to use DevLink to sync your Webflow styles, variables, and components with your app #### [Optimize your app for Webflow Cloud](/webflow-cloud/environment/framework-customization) Explore how to optimize and tailor your deployment for the best experience on Webflow Cloud. #### [Manage deployments](/webflow-cloud/deployments) Explore deployment options and Webflow Cloud's CI/CD integration with GitHub to streamline your release process #### [Add a SQLite database to your app](/webflow-cloud/add-sqlite) Add a SQLite database to your app to store and retrieve user data. ## Troubleshooting #### I'm seeing a 404 error when I try to access my app For an app on its own domain, verify that the latest deployment succeeded. For an app on a site, if you have never published your site before, publish it now. If you have already published your site, check your mount path, confirm the environment exists, and verify that the latest deployment succeeded. #### A deployment doesn't start when I push to my Github repo The [Webflow Cloud GitHub App](https://github.com/apps/webflow-cloud/installations/select_target) may not have access to your repository. To check, go to the `Webflow Cloud` tab in your Webflow site settings and click "Install GitHub App." Follow the prompts on GitHub to ensure Webflow has access to read from your repository. Once you grant access, try committing to the branch that Webflow Cloud should be monitoring for deployments in your app. #### My assets or API routes aren't loading correctly Check that you're correctly using the base path in all asset and API references. Look for fixed paths that might be missing the base path prefix. #### Authentication isn't working properly Verify that your callback URLs include the correct base path and that you're not duplicating the base path in your code references. #### My build is failing in Webflow Cloud Check your app's [build logs](/webflow-cloud/deployments#build-logs) in the Webflow Cloud dashboard. Common issues include: * Incompatible Node.js version * Environment variables not configured correctly * Missing or incorrect framework configuration in the following files: * `webflow.json` * `next.config.js` or `Astro.config.js` * `wrangler.json` * `cloudflare-env.d.ts` or `worker-configuration.d.ts` * Custom build commands not supported (Webflow Cloud only uses `Astro build` or `next build`) #### Caching is not working as expected Webflow Cloud overrides custom cache headers from your application. Once content is cached, you can't control caching behavior through standard HTTP headers like `Cache-Control`. See more on header behavior limitations [here](/webflow-cloud/limits#header-behavior-limitations). This means traditional cache invalidation methods won't work - you'll need to work within Webflow Cloud's caching behavior rather than trying to override it.