How to Deploy Nextra on Webflow Cloud
.jpg)
Watch Video Tutorial
I recently deployed a Nextra documentation site to Webflow Cloud. It wasn't straightforward, but after solving several edge runtime issues, it works. Here's what I learned.
What is Nextra?
Nextra is a framework built on Next.js for creating documentation sites. It uses MDX (Markdown + React) and comes with a docs theme, search, and syntax highlighting out of the box.
What is Webflow Cloud?
Webflow Cloud is Webflow's hosting platform that runs on Cloudflare Workers. It supports Next.js 15+ and provides global edge deployment.
Prerequisites
Before starting, you need:
- Node.js 20.0.0 or higher (download)
- npm (comes with Node.js)
- A Webflow account
- A GitHub account
- Webflow CLI installed:
npm install -g @webflow/cli
Step 1: Create a Nextra Project
First, create a new Next.js project with Nextra:
npx create-next-app@latest my-docs --typescript
cd my-docs
Install Nextra dependencies:
npm install nextra nextra-theme-docs
Step 2: Configure Next.js for Nextra
Create next.config.ts in your project root:
import type { NextConfig } from "next";import nextra from "nextra";const withNextra = nextra({
defaultShowCopyCode: true,
});const nextConfig: NextConfig = {
// Required for Webflow Cloud edge runtime
serverExternalPackages: ['@nodelib/fs.scandir', '@nodelib/fs.stat', 'fast-glob'],
// Skip type checking during build (Webflow injects code that causes TS errors)
typescript: {
ignoreBuildErrors: true,
},
// Skip ESLint during build
eslint: {
ignoreDuringBuilds: true,
},
webpack: (config, { isServer }) => {
if (!isServer) {
// Prevent Node.js modules from being bundled for client
config.resolve.fallback = {
...config.resolve.fallback,
fs: false,
module: false,
path: false,
os: false,
};
}
return config;
},
};
export default withNextra(nextConfig);
Step 3: Create the Critical File - mdx-components.tsx
This file is required and was the key to making the sidebar work. Create mdx-components.tsx in your project root:
import type { MDXComponents } from "mdx/types";import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs';export function useMDXComponents(components: MDXComponents): MDXComponents {
const themeComponents = getThemeComponents();
return {
...themeComponents,
...components,
};
}
Important: Without importing theme components, your sidebar won't render. This took me hours to figure out.
Step 4: Set Up Nextra Theme Configuration
Create theme.config.tsx:
import type { DocsThemeConfig } from "nextra-theme-docs";const config: DocsThemeConfig = {
logo: <span>My Documentation</span>,
project: {
link: "https://github.com/yourusername/your-repo",
},
docsRepositoryBase: "https://github.com/yourusername/your-repo/tree/main",
footer: {
content: (
<span>
{new Date().getFullYear()} © My Documentation
</span>
),
},
};
export default config;
Step 5: Create App Layout
Create src/app/layout.tsx:
import { Footer, Layout, Navbar } from 'nextra-theme-docs'import { Banner } from 'nextra/components'import { getPageMap } from 'nextra/page-map'import 'nextra-theme-docs/style.css'export const metadata = {
title: "My Documentation",
description: "Documentation powered by Nextra",
}const banner = (
<Banner storageKey="announcement">
Welcome to my docs
</Banner>
)
const navbar = (
<Navbar
logo={<strong>My Docs</strong>}
projectLink="https://github.com/yourusername/your-repo"
/>
)const footer = (
<Footer>
MIT {new Date().getFullYear()} © My Documentation
</Footer>
)
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const pageMap = await getPageMap()
return (
<html lang="en" dir="ltr" suppressHydrationWarning>
<body>
<Layout
banner={banner}
navbar={navbar}
footer={footer}
pageMap={pageMap}
sidebar={{ autoCollapse: true }}
docsRepositoryBase="https://github.com/yourusername/your-repo/tree/main"
>
{children}
</Layout>
</body>
</html>
)
}
Step 6: Create Navigation Structure
Create src/app/_meta.tsx to define your sidebar navigation:
export default {
index: "Home",
"getting-started": "Getting Started",
about: "About",
};
Step 7: Create Your First Page
Create src/app/page.mdx:
# Welcome to My Documentation
This is built with Nextra and deployed on Webflow Cloud.
## Getting Started
Check out the sidebar to explore the documentation.
Step 8: Install Webflow Cloud Dependencies
Install required packages for Webflow Cloud deployment:
npm install @opennextjs/cloudflare
npm install -D wrangler @cloudflare/workers-types
Initialize OpenNext Cloudflare in your next.config.ts (add at the top):
import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare";
initOpenNextCloudflareForDev();
Step 9: Create Webflow Configuration
Create webflow.json:
{
"cloud": {
"framework": "nextjs"
}
}
Create wrangler.json:
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "my-docs",
"main": ".open-next/worker.js",
"compatibility_date": "2025-03-01",
"compatibility_flags": ["nodejs_compat"],
"assets": {
"binding": "ASSETS",
"directory": ".open-next/assets"
}
}
The nodejs_compat flag is critical - it enables Node.js APIs in Cloudflare Workers runtime.
Step 10: Create OpenNext Configuration
Create open-next.config.ts:
import { defineCloudflareConfig } from "@opennextjs/cloudflare";export default defineCloudflareConfig({});
Step 11: Test Locally
Before deploying, test your build locally:
npm run build
If the build fails with "Module not found: fs", double-check your next.config.ts webpack configuration and mdx-components.tsx file.
Step 12: Push to GitHub
Initialize git and push your project:
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main
Step 13: Deploy to Webflow Cloud
Method 1: Run the Webflow CLI deploy command:
webflow cloud deploy
The CLI will:
- Run
npm cito install dependencies - Build your Next.js app
- Package it with OpenNext Cloudflare adapter
- Deploy to Cloudflare Workers via Webflow Cloud
Method2: Deploy it on Webflow Cloud UI through Github Source( you can also fork it on my github source.)
Common Issues I Encountered
Issue 1: Sidebar Not Showing
Problem: The sidebar navigation wasn't rendering at all.
Solution: Import theme components in mdx-components.tsx:
import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs';
Without this, Nextra's wrapper component doesn't apply and the sidebar won't render.
Issue 2: "Module not found: fs"
Problem: Build failed with "Can't resolve 'fs'" errors.
Solution: Add webpack fallbacks in next.config.ts and use serverExternalPackages to mark file system libraries as external:
serverExternalPackages: ['@nodelib/fs.scandir', '@nodelib/fs.stat', 'fast-glob']
Issue 3: TypeScript Errors During Build
Problem: Webflow injects configuration code during deployment that causes TypeScript errors.
Solution: Disable TypeScript checks during build:
typescript: {
ignoreBuildErrors: true,
}
Why This Configuration Works
Nextra uses file system operations at build time to scan your MDX files and generate the page map. Cloudflare Workers (which Webflow Cloud uses) doesn't support Node.js fs module at runtime, but it's fine during the build phase.
The key is:
- Build time: Nextra reads files to create the page map (allowed)
- Runtime: Only the generated page map is used (no file system access needed)
By marking file system libraries as external and adding webpack fallbacks, we prevent them from being bundled into the client code while still allowing them during the build process.
Official Documentation References
- Nextra Documentation
- Webflow Cloud Documentation
- Node.js Compatibility on Webflow Cloud
- OpenNext Cloudflare Adapter
Repository
The complete example is available on GitHub, you can fork and deploy it easily.
https://github.com/lvsao/webflow-nextra
Meta Description: Learn how to deploy Nextra documentation sites on Webflow Cloud. Step-by-step guide covering edge runtime configuration, common issues, and solutions for Next.js 15 with Cloudflare Workers.
