Bring your own app

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 property in your next.config.ts file to match this mount path exactly.

1
module.exports = {
2
    // Configure the base path to reflect the mount path of your environment
3
    // For example, if your app is mounted at /app, set basePath to '/app'
4
    basePath: '/app',
5
    
6
    // Additional Next.js configuration options can be added here
7
    // For example:
8
    // output: 'standalone',
9
    // reactStrictMode: true,
10
}

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 project and run the following command to install OpenNext:

   $
   npm install @opennextjs/cloudflare@1.0.0-beta.4

2. Configure OpenNext
   Create a new configuration file named open-next.config.ts in your project’s root directory. This file configures OpenNext to work with Webflow Cloud’s deployment environment.

   open-next.config.ts

   1
   import type { NextConfig } from "next";
   2
   3
   import { defineCloudflareConfig } from "@opennextjs/cloudflare";
   4
   5
   export default defineCloudflareConfig({
   6
   });

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

   $
   npm install wrangler --save-dev

2. Set up your Wrangler configuration
   Create a wrangler.jsonc file in your project root that defines how your application will run in both development and production.

   wrangler.jsonc

   1
   {
   2
       "$schema": "node_modules/wrangler/config-schema.json",
   3
       "name": "nextjs",
   4
       "main": ".open-next/worker.js",
   5
       "compatibility_date": "2025-03-01",
   6
       "compatibility_flags": [
   7
           "nodejs_compat"
   8
       ],
   9
       "assets": {
   10
           "binding": "ASSETS",
   11
           "directory": ".open-next/assets"
   12
       },
   13
       "observability": {
   14
           "enabled": true
   15
       }
   16
       /** Rest of Code **/
   17
   }

   See the Cloudflare documentation for more details on how to configure Wrangler.

3. Create a Cloudflare environment file
   Create a new file named cloudflare-env.d.ts in your project’s root directory. This file will allow you to use environment variables defined in your Webflow Cloud environment.

   cloudflare-env.d.ts

   1
   interface CloudflareEnv {
   2
   }

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:

   package.json

   1
   "scripts": {
   2
       // Existing scripts...
   3
       "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview", // 
   4
   }

Define your Webflow Cloud framework configuration

Create a webflow.json file at the root of your project to inform Webflow Cloud about your app’s framework.

1
{
2
    "cloud": {
3
        "framework": "nextjs"
4
    }
5
}

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. Implement this pattern in your components for reliable asset loading:

1
import config from "../next.config";
2
import Image from "next/image";
3
4
// Get the base path from config
5
const basePath = config.basePath || '';
6
7
export function Logo() {
8
return (
9
    <Image 
10
    src={`${basePath}/images/logo.png`} // Add base path to asset path
11
    alt="Logo" 
12
    width={180} 
13
    height={40} 
14
    priority
15
    />
16
);
17
}

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:

1
// /src/pages/api/data.ts
2
import { NextRequest, NextResponse } from 'next/server';
3
4
export async function GET(request: NextRequest) {
5
    return NextResponse.json({ message: 'Hello, world!' });
6
}
7
8
export const runtime = 'edge'; // Add this line to your API route