Overview
Vercel provides the best deployment experience for Next.js-based Fumadocs applications, with zero-configuration deployment, automatic HTTPS, and global CDN distribution.
Quick Start
Follow the prompts to link your project and deploy.
Git Integration
For automatic deployments on every push:
Go to Vercel Dashboard
Click “Add New…” → “Project”
Import your Git repository (GitHub, GitLab, Bitbucket)
Vercel auto-detects Next.js projects. Default settings:
Framework Preset: Next.js
Build Command: next build
Output Directory: .next
Install Command: Automatically detected
Click “Deploy” - Vercel will build and deploy your site.
Configuration
vercel.json
Optional configuration file for advanced settings:
{
"buildCommand": "npm run build",
"devCommand": "npm run dev",
"installCommand": "npm install",
"framework": "nextjs",
"outputDirectory": ".next"
}
Environment Variables
Set environment variables in the Vercel dashboard:
- Go to Project Settings → Environment Variables
- Add variables for:
NEXT_PUBLIC_* - Client-side variablesDATABASE_URL - Server-side secretsAPI_KEY - Private API keys
Or use the Vercel CLI:
vercel env add NEXT_PUBLIC_SITE_URL
Custom Domains
Add custom domains in Project Settings → Domains:
Enter your domain name (e.g., docs.example.com)
Point your domain to Vercel:
CNAME docs cname.vercel-dns.com
Vercel automatically provisions SSL certificates.
Build Optimization
Next.js Configuration
Optimize your next.config.js for Vercel:
import { createMDX } from 'fumadocs-mdx/next';
const withMDX = createMDX();
/** @type {import('next').NextConfig} */
const config = {
reactStrictMode: true,
// Optimize logging
logging: {
fetches: {
fullUrl: true,
},
},
// External packages for serverless
serverExternalPackages: [
'ts-morph',
'typescript',
'shiki',
'@takumi-rs/image-response',
],
// Remote image patterns
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'avatars.githubusercontent.com',
},
],
},
};
export default withMDX(config);
Bundle Analysis
Analyze your bundle size:
npm install --save-dev @next/bundle-analyzer
import createBundleAnalyzer from '@next/bundle-analyzer';
import { createMDX } from 'fumadocs-mdx/next';
const withAnalyzer = createBundleAnalyzer({
enabled: process.env.ANALYZE === 'true',
});
const withMDX = createMDX();
const config = {
// ... your config
};
export default withAnalyzer(withMDX(config));
ANALYZE=true npm run build
Caching Strategy
Optimize caching for static assets:
const config = {
async headers() {
return [
{
source: '/static/:path*',
headers: [
{
key: 'Cache-Control',
value: 'public, max-age=31536000, immutable',
},
],
},
];
},
};
Search Configuration
Built-in Search (Orama)
The default Orama search works out of the box on Vercel:
import { allDocs } from '@/.source';
import { createSearchAPI } from 'fumadocs-core/search/server';
const api = createSearchAPI('advanced', {
indexes: allDocs.map((page) => ({
id: page.url,
title: page.data.title,
description: page.data.description,
url: page.url,
structuredData: page.data.structuredData,
})),
});
export const GET = api.GET;
export const POST = api.POST;
Algolia Search
For larger documentation sites, use Algolia:
npm install algoliasearch
vercel env add ALGOLIA_APP_ID
vercel env add ALGOLIA_SEARCH_API_KEY
vercel env add ALGOLIA_WRITE_API_KEY
Edge Functions
Use Edge Runtime for faster response times:
export const runtime = 'edge';
export async function GET(request: Request) {
// ... your code
}
Fumadocs core features work on Edge Runtime, but some dependencies (like TypeScript compilation for API docs) require Node.js runtime.
Incremental Static Regeneration (ISR)
Regenerate pages on-demand:
app/docs/[...slug]/page.tsx
export const revalidate = 3600; // Revalidate every hour
export default function Page({ params }: { params: { slug: string[] } }) {
// ... your page component
}
On-Demand Revalidation
Revalidate specific pages via API:
app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';
export async function POST(request: NextRequest) {
const { path } = await request.json();
if (!path) {
return NextResponse.json({ error: 'Missing path' }, { status: 400 });
}
try {
revalidatePath(path);
return NextResponse.json({ revalidated: true, path });
} catch (error) {
return NextResponse.json({ error: 'Error revalidating' }, { status: 500 });
}
}
curl -X POST https://your-site.vercel.app/api/revalidate \
-H 'Content-Type: application/json' \
-d '{"path":"/docs/some-page"}'
Monorepo Support
For monorepo projects:
{
"buildCommand": "cd ../.. && npm run build --filter=docs",
"installCommand": "npm install --prefix=../..",
"framework": "nextjs"
}
- Project Settings → General
- Set Root Directory to your docs package (e.g.,
apps/docs)
- Enable Include source files outside of the Root Directory
Preview Deployments
Vercel creates preview deployments for every push:
- Production: Deploys from
main/master branch
- Preview: Deploys from feature branches and pull requests
Configure branch deployments:
- Project Settings → Git
- Set Production Branch
- Enable/disable preview deployments
CI/CD Integration
GitHub Actions
Deploy via GitHub Actions:
.github/workflows/deploy.yml
name: Deploy to Vercel
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Vercel CLI
run: npm install -g vercel
- name: Pull Vercel Environment
run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
- name: Build Project
run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
- name: Deploy to Vercel
run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
VERCEL_TOKEN in GitHub repository secrets.
Troubleshooting
Build Timeouts
If builds exceed time limits:
- Optimize dependencies (remove unused packages)
- Enable caching in
next.config.js
- Consider splitting large docs into separate projects
- Use static export for faster builds
Memory Issues
Increase Node.js memory:
{
"scripts": {
"build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
}
}
Function Size Limits
If serverless functions exceed size limits:
const config = {
serverExternalPackages: [
'large-package-name',
],
};
Cold Starts
Reduce cold start times:
- Minimize serverless function size
- Use Edge Runtime where possible
- Enable ISR for frequently accessed pages
- Consider static export for pure documentation
Analytics
Enable Vercel Analytics:
npm install @vercel/analytics
import { Analytics } from '@vercel/analytics/react';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
{children}
<Analytics />
</body>
</html>
);
}
Next Steps