> 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, Astro, or Vite 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 6 or 7) * A Next.js app (version 15 or higher) * A Vite app (version 6.1 or higher) — React, Vue, Svelte, or vanilla JavaScript * Node.js 22 or later and `npm` installed * **Note:** Currently, Webflow Cloud supports only the `npm` package manager * **Note:** Astro 6 and Astro 7 require Node.js 22.12 or later ## 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 **In most cases, you don't.** Webflow Cloud reads your `package.json`, detects your framework, and generates the deployment configuration when it builds your app. You commit your app the way you'd normally write it. Here's what that means in practice — this is the complete `next.config.ts` from the [Next.js starter](https://github.com/Webflow-Examples/hello-world-next-app), which deploys to Webflow Cloud as-is: ```ts title="next.config.ts" import type { NextConfig } from "next"; const nextConfig: NextConfig = { /* config options here */ }; export default nextConfig; ``` No adapter, no base path, no `wrangler.json`. #### What the platform owns, and what you own | Configuration | Owner | | -------------------------------------------- | -------------------------------------------------------------------------------------------- | | Framework and version detection | Webflow Cloud, from your `package.json` | | Installing and wiring the Cloudflare adapter | Webflow Cloud | | Base path and asset prefix | Webflow Cloud, from your environment's [mount path](/webflow-cloud/environments#mount-paths) | | Production deployment configuration | Webflow Cloud | | Your app code and framework options | You | | Storage bindings | You declare them, Webflow Cloud provisions them | #### Leave the base path unset Don't set `basePath`/`assetPrefix` (Next.js) or `base`/`build.assetsPrefix` (Astro) in your framework config. Webflow Cloud sets them at build time from your environment's mount path, and overwrites whatever you commit. Read the values at runtime instead of hard-coding them — see [Mount path configuration](/webflow-cloud/environment/configuration#mount-path-configuration). If you need your local server to match a non-root mount path, see [Local development](#local-development). #### Optional: declare your framework explicitly Detection is automatic. If you want to pin it — for example in a monorepo, or a repo where detection is ambiguous — add a `webflow.json` at your app root: ```json title="webflow.json" { "cloud": { "framework": "nextjs" } } ``` Supported values are `nextjs`, `astro`, `vite`, and `static`. For Astro, use `astro` — Webflow Cloud detects the major version from your `package.json` and selects the matching adapter. ### Local development You have two options, and which one you want depends on what you're doing. #### Iterate quickly (no extra setup) Use your framework's own dev server. Nothing to install beyond your app's own dependencies, and no Cloudflare or Webflow packages. ```bash title="Next.js" next dev ``` ```bash title="Astro" astro dev ``` This is the fastest feedback loop and the right default for building UI and business logic. Two differences from production to be aware of: * **Your app serves from `/`, not from your mount path.** Webflow Cloud applies the base path at build time only. If your environment is mounted at the root, there's no difference. If it's mounted at a subpath like `/app`, your local URLs won't carry that prefix — which is exactly why you should read the base path at runtime rather than hard-code it. * **Storage bindings aren't connected.** Use the parity option below if your app reads from KV, D1, or R2. #### Match production (optional) To run your app on the same Workers runtime that Webflow Cloud uses — including local storage bindings — install the adapter and Wrangler yourself. #### This runs entirely on your machine Wrangler emulates the Workers runtime and your storage bindings locally, in a `.wrangler` directory. You don't need a Cloudflare account, and you don't need to log in. ```bash title="Next.js" npm install @opennextjs/cloudflare npm install --save-dev wrangler # then: npx opennextjs-cloudflare build && npx opennextjs-cloudflare preview ``` ```bash title="Astro" npm install @astrojs/cloudflare npm install --save-dev wrangler # then: astro build && astro preview ``` With the adapter installed, `astro dev` also connects your local storage bindings, and `astro preview` serves the built app on the Workers runtime. See [local preview](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#local-preview) in the adapter docs. Installing the adapter yourself is fully supported: Webflow Cloud only installs an adapter when your app doesn't already declare one, so your version is the one that gets used. If your app uses storage, this is also how you get typed bindings locally: ```bash npx wrangler types ``` See [Storage bindings](#storage-bindings) for the `wrangler.json` you need. ### Storage bindings If your app uses [KV, SQLite, or object storage](/webflow-cloud/storing-data/overview), commit a `wrangler.json` that declares the bindings. Webflow Cloud reads it during deployment, provisions the resources for your environment, and injects the real IDs. ```json title="wrangler.json" { "$schema": "node_modules/wrangler/config-schema.json", "name": "my-app", "compatibility_date": "2025-04-15", "d1_databases": [ { "binding": "DB", "database_name": "db", "database_id": "0", "migrations_dir": "drizzle" } ], "kv_namespaces": [{ "binding": "SESSIONS", "id": "local" }], "r2_buckets": [{ "binding": "MEDIA", "bucket_name": "media" }] } ``` #### The ID values are placeholders `database_id` and `id` are required, so local commands like `wrangler types` and `wrangler d1 migrations apply --local` work. The values you commit are never used in production — Webflow Cloud replaces them with the IDs of the resources it provisions for your environment. Use any placeholder you like. What matters is the **binding name** (`DB`, `SESSIONS`, `MEDIA`). That's what your code reads, and it's preserved exactly. #### Missing required fields are skipped silently Webflow Cloud validates this file before reading your bindings. If a required field is missing, it logs an error to your [build logs](/webflow-cloud/deployments#build-logs) and continues **without your bindings** — the build succeeds and the app deploys, but your storage isn't connected. If your bindings seem to vanish in production, check the build log for a validation error first. Required fields are `name` and `compatibility_date` at the top level, plus: | Binding | Required fields | | :-------------- | :---------------------------------------- | | `kv_namespaces` | `binding`, `id` | | `d1_databases` | `binding`, `database_name`, `database_id` | | `r2_buckets` | `binding`, `bucket_name` | For a complete working example, see the starters with bindings wired up: [Next.js](https://github.com/Webflow-Examples/hello-world-next-app-bindings) and [Astro](https://github.com/Webflow-Examples/hello-world-astro-app-bindings). ### 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 the base path to load correctly and enable CDN caching. ```tsx title="src/app/components/Icon.tsx" // Set NEXT_PUBLIC_BASE_PATH in your environment variables to your mount path const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? ''; export function Icon() { return ( Star icon ); } ``` #### Don't import your own \`next.config\` Reading `basePath` by importing `next.config` doesn't work on Webflow Cloud. The builder generates its own `next.config` at build time and moves yours aside, so the value you read locally isn't the value used in production. Use an environment variable, as shown above. #### APIs When your app is served from a mount 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 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" // Set NEXT_PUBLIC_BASE_PATH in your environment variables to your mount path const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? ''; export async function fetchData() { const response = await fetch(`${basePath}/api/data`); return response.json(); } ``` #### \`Link\` and \`next/image\` handle this for you Next.js applies the base path automatically to ``, `useRouter()`, `redirect()`, and the `next/image` component. You only need the prefix for plain `` tags and manual `fetch` calls. #### 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 available during builds and at runtime Both secret and non-secret environment variables are available to your application's build process—for example, for auth-framework configuration—and remain available to the deployed application at runtime. Secret values are value-redacted from Webflow Cloud build logs. Even so, avoid intentionally printing secrets, since redaction is a safety mechanism rather than a recommended secret-handling workflow. Because variables are available at build time, framework variables that get inlined during the build (such as `NEXT_PUBLIC_*` and Astro's `PUBLIC_*`) work as expected. Anything inlined this way ends up in the JavaScript you ship to browsers, so don't mark a value secret and then inline it. #### 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: #### Run your app locally Before deploying, check your app with your framework's dev server: ```bash npm run dev ``` For a run against the same runtime Webflow Cloud uses, including storage bindings, see [Local development](#local-development). #### 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: * An incompatible Node.js version * Environment variables not configured correctly * A framework version Webflow Cloud doesn't support yet — check the [supported frameworks](/webflow-cloud/environment/framework-customization) * A custom build script — Webflow Cloud runs the framework's own build (`opennextjs-cloudflare build` or `astro build`) and ignores a custom `build` script in your `package.json` #### 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.