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

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

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:

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

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

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

   wrangler.json

   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 app’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 app to inform Webflow Cloud about your app’s framework.

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

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.

1
import Image from "next/image";
2
3
export function Logo() {
4
    return (
5
        <Image
6
            src="/images/logo.png" // No prefix needed - automatically optimized
7
            alt="Logo"
8
            width={180}
9
            height={40}
10
            priority
11
        />
12
    );
13
}

Plain img tags: Must include assetPrefix to load correctly and enable CDN caching.

1
import config from "../../../next.config";
2
3
// Get the asset prefix from config
4
const assetPrefix = config.assetPrefix || config.basePath || '';
5
6
export function Icon() {
7
    return (
8
        <img
9
            src={`${assetPrefix}/icons/star.svg`} // Prefix required for CDN caching
10
            alt="Star icon"
11
        />
12
    );
13
}

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
}