Deployment Guide

This guide covers various deployment options for your Next.js web template, from simple static hosting to full-featured platforms with server-side rendering capabilities.

Vercel (Recommended)

Vercel is the easiest way to deploy Next.js applications, created by the same team that builds Next.js.

Quick Deploy

1. Connect your repository:

   • Visit vercel.com
   • Sign up with GitHub, GitLab, or Bitbucket
   • Import your project repository

2. Configure deployment:

   # Install Vercel CLI (optional)
   npm i -g vercel
   
   # Deploy from command line
   vercel
   

3. Environment variables:

   • Add environment variables in the Vercel dashboard
   • Or use the CLI: vercel env add

Custom Domain

# Add custom domain
vercel domains add yourdomain.com

# Configure DNS
# Add CNAME record: www -> cname.vercel-dns.com
# Add A record: @ -> 76.76.19.61

Netlify

Netlify offers excellent static site hosting with continuous deployment.

Setup

1. Build configuration: Create netlify.toml in your project root:

   [build]
     command = "npm run build"
     publish = "out"
   
   [build.environment]
     NODE_VERSION = "18"
   
   [[redirects]]
     from = "/*"
     to = "/index.html"
     status = 200
   

2. Static export configuration: Update next.config.js:

   /** @type {import('next').NextConfig} */
   const nextConfig = {
     output: 'export',
     trailingSlash: true,
     images: {
       unoptimized: true
     }
   }
   
   module.exports = nextConfig
   

3. Deploy:

   • Connect your Git repository
   • Netlify will automatically deploy on every push

GitHub Pages

Deploy your static site directly from your GitHub repository.

Setup

1. Install gh-pages:

   npm install --save-dev gh-pages
   

2. Update package.json:

   {
     "scripts": {
       "deploy": "gh-pages -d out",
       "build-and-deploy": "npm run build && npm run deploy"
     }
   }
   

3. Configure Next.js:

   // next.config.js
   const isProd = process.env.NODE_ENV === 'production'
   
   const nextConfig = {
     output: 'export',
     basePath: isProd ? '/your-repo-name' : '',
     assetPrefix: isProd ? '/your-repo-name/' : '',
   }
   
   module.exports = nextConfig
   

4. Deploy:

   npm run build-and-deploy
   

AWS Amplify

AWS Amplify provides hosting with built-in CI/CD and serverless backend integration.

Setup

1. Install Amplify CLI:

   npm install -g @aws-amplify/cli
   amplify configure
   

2. Initialize project:

   amplify init
   amplify add hosting
   amplify publish
   

3. Build settings:

   version: 1
   frontend:
     phases:
       preBuild:
         commands:
           - npm ci
       build:
         commands:
           - npm run build
     artifacts:
       baseDirectory: .next
       files:
         - '**/*'
     cache:
       paths:
         - node_modules/**/*
   

Docker Deployment

Containerize your application for deployment anywhere.

Dockerfile

# Dockerfile
FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci --only=production

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

RUN npm run build

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT 3000

CMD ["node", "server.js"]

Docker Compose

# docker-compose.yml
version: '3.8'
services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    restart: unless-stopped

Build and run:

# Build image
docker build -t my-next-app .

# Run container
docker run -p 3000:3000 my-next-app

# Or use docker-compose
docker-compose up -d

Railway

Railway offers simple deployment with automatic HTTPS and custom domains.

Setup

1. Connect repository:

   • Visit railway.app
   • Connect your GitHub repository
   • Railway will auto-detect Next.js

2. Environment variables:

   • Add variables in Railway dashboard
   • Or use railway.json:

   {
     "build": {
       "builder": "NIXPACKS"
     },
     "deploy": {
       "startCommand": "npm start",
       "restartPolicyType": "ON_FAILURE"
     }
   }
   

DigitalOcean App Platform

Deploy to DigitalOcean's managed platform.

Setup

1. App specification: Create .do/app.yaml:

   name: my-next-app
   services:
   - name: web
     source_dir: /
     github:
       repo: your-username/your-repo
       branch: main
     run_command: npm start
     environment_slug: node-js
     instance_count: 1
     instance_size_slug: basic-xxs
     routes:
     - path: /
   

2. Deploy:

   • Use DigitalOcean dashboard
   • Or use doctl CLI

Environment Variables

Production Environment Setup

For all deployment platforms, ensure you set these environment variables:

# Required
NODE_ENV=production
NEXTAUTH_SECRET=your-secret-key
NEXTAUTH_URL=https://yourdomain.com

# Database (if applicable)
DATABASE_URL=your-database-url

# API Keys
STRIPE_SECRET_KEY=your-stripe-key
SENDGRID_API_KEY=your-sendgrid-key

# Analytics
GOOGLE_ANALYTICS_ID=your-ga-id

Performance Optimization

Build Optimization

// next.config.js
const nextConfig = {
  // Enable compression
  compress: true,
  
  // Optimize images
  images: {
    domains: ['example.com'],
    formats: ['image/webp', 'image/avif'],
  },
  
  // Bundle analyzer (development only)
  ...(process.env.ANALYZE === 'true' && {
    webpack: (config) => {
      config.plugins.push(
        new (require('@next/bundle-analyzer'))({
          enabled: true,
        })
      )
      return config
    },
  }),
}

CDN Configuration

For static assets, configure CDN:

// next.config.js
const nextConfig = {
  assetPrefix: process.env.NODE_ENV === 'production' 
    ? 'https://cdn.yourdomain.com' 
    : '',
}

Monitoring and Analytics

Error Tracking

Integrate error tracking services:

# Sentry
npm install @sentry/nextjs

# Configure in next.config.js
const { withSentryConfig } = require('@sentry/nextjs');

module.exports = withSentryConfig(nextConfig, {
  silent: true,
  org: 'your-org',
  project: 'your-project',
});

Performance Monitoring

// pages/_app.js
import { Analytics } from '@vercel/analytics/react';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <Analytics />
    </>
  );
}

Troubleshooting

Common Issues

1. Build failures:

   • Check Node.js version compatibility
   • Verify all dependencies are installed
   • Review build logs for specific errors

2. Environment variables not working:

   • Ensure variables are prefixed with NEXT_PUBLIC_ for client-side access
   • Restart deployment after adding variables

3. Static export issues:

   • Remove server-side features (API routes, ISR)
   • Configure next.config.js for static export

4. Performance issues:

   • Enable compression
   • Optimize images and fonts
   • Use CDN for static assets

Getting Help

If you encounter deployment issues:

• Check the troubleshooting guide
• Review platform-specific documentation
• Contact our support team
• Join our community forums

Successful deployment is just the beginning – monitor your application's performance and user experience to ensure optimal results!