Deployment

Learn how to deploy your documentation site to production.

Vercel (Recommended)

Vercel is the easiest way to deploy Next.js applications.

One-Click Deploy

Manual Deploy

1. Push your code to GitHub
2. Go to vercel.com 
3. Import your repository
4. Vercel will automatically detect Next.js and configure the build

Environment Variables

If you have environment variables, add them in the Vercel dashboard:

1. Go to Project Settings → Environment Variables
2. Add your variables for Production, Preview, and Development

Netlify

Deploy via Git

1. Push your code to GitHub/GitLab/Bitbucket
2. Go to netlify.com 
3. Click “New site from Git”
4. Select your repository
5. Configure build settings:
   • Build command: npm run build
   • Publish directory: .next

netlify.toml

Create a netlify.toml file in the project root:

[build]
  command = "npm run build"
  publish = ".next"
 
[[plugins]]
  package = "@netlify/plugin-nextjs"

Static Export

If you need a fully static site (no server required):

Configure Next.js

Edit next.config.ts:

import nextra from "nextra";
 
const withNextra = nextra({
  defaultShowCopyCode: true,
});
 
export default withNextra({
  reactStrictMode: true,
  output: "export", // Enable static export
  images: {
    unoptimized: true, // Required for static export
  },
});

Build Static Files

npm run build

The static files will be in the out/ directory.

Deploy Anywhere

Upload the out/ directory to any static hosting:

• GitHub Pages
• Cloudflare Pages
• AWS S3 + CloudFront
• Any web server

Docker

Dockerfile

Create a Dockerfile:

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:18-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
COPY --from=builder /app/public ./public
 
EXPOSE 3000
CMD ["npm", "start"]

Build and Run

docker build -t my-docs .
docker run -p 3000:3000 my-docs

GitHub Pages

Configure for GitHub Pages

1. Enable static export in next.config.ts (see above)

2. Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages
 
on:
  push:
    branches: [main]
 
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "18"
          cache: "npm"
 
      - name: Install dependencies
        run: npm ci
 
      - name: Build
        run: npm run build
 
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./out

3. Enable GitHub Pages in repository settings, selecting “gh-pages” branch

Custom Domain

Vercel

1. Go to Project Settings → Domains
2. Add your custom domain
3. Configure DNS as instructed

Other Platforms

Add a CNAME file to the public/ directory:

docs.your-domain.com

Then configure your DNS to point to your hosting provider.

Build Scripts