Deployment

This guide covers deploying your Metronic Next.js application to production environments.

Building for Production

# Navigate to your project directory
cd your-nextjs-project
 
# Install dependencies (if needed)
npm install
 
# Build for production
npm run build

This creates a .next directory with optimized files ready for deployment.

Configuration

Environment Variables

For production, create a .env.production file:

NEXT_PUBLIC_APP_NAME=metronic-nextjs
NEXT_PUBLIC_API_URL=https://your-production-api.com/api
NEXTAUTH_URL=https://your-domain.com
NEXTAUTH_SECRET=your-secret-key

Remember that only variables prefixed with NEXT_PUBLIC_ will be exposed to the browser.

Base Path Configuration

When deploying your Next.js application behind a reverse proxy (like nginx) or to a subdirectory, you need to configure the basePath in your next.config.mjs file.

Understanding Base Path

The basePath tells Next.js that your application is served from a subdirectory rather than the root domain. For example:

• Root deployment: https://example.com/ → basePath: '' or basePath: '/'
• Subdirectory deployment: https://example.com/my-app/ → basePath: '/my-app'

Configuration Options

Option 1: Using Environment Variable (Recommended)

Set the NEXT_PUBLIC_BASE_PATH environment variable in your .env.production file:

# For subdirectory deployment
NEXT_PUBLIC_BASE_PATH=/

Option 2: Hardcoded in Config

You can also hardcode the basePath directly in next.config.mjs:

const nextConfig = {
  basePath: '/your-custom-path',
  assetPrefix: '/your-custom-path',
  output: 'standalone',
};

Important Notes

1. Path Format: The basePath must be a path string (e.g., /my-app), not a full URL. If your environment variable contains a full URL, you'll need to extract just the pathname.

2. Trailing Slash: Next.js handles trailing slashes automatically, so both /my-app and /my-app/ work correctly.

3. Asset Prefix: The assetPrefix should match your basePath to ensure static assets (CSS, JS, images) are loaded from the correct path.

4. Links and Navigation: When using basePath, Next.js automatically prefixes all internal links and routes. However, if you're using the toAbsoluteUrl helper function from lib/helpers.ts, it uses NEXT_PUBLIC_BASE_PATH for absolute URLs.

5. Development vs Production: You can use different base paths for development and production by setting different values in .env and .env.production files.

Example: Deploying Behind Nginx

If you're deploying behind an nginx reverse proxy:

location /my-app {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
}

Then set in your .env.production:

NEXT_PUBLIC_BASE_PATH=/my-app

Troubleshooting Base Path Issues

If you're experiencing issues with assets not loading or routes not working:

1. Check Environment Variable: Ensure NEXT_PUBLIC_BASE_PATH is set correctly in your production environment.

2. Rebuild After Changes: After changing basePath, you must rebuild your application:

   npm run build

   Copy

3. Verify Asset Loading: Check your browser's Network tab to see if assets are being requested from the correct path.

4. Check Router Configuration: Ensure your reverse proxy (nginx, Apache, etc.) is configured to pass requests to the correct path.

Deployment Options

Vercel (Recommended)

Vercel provides the simplest deployment experience for Next.js applications:

1. Push your code to a Git repository (GitHub, GitLab, BitBucket)
2. Import your repository on vercel.com
3. Vercel will automatically detect Next.js and use the optimal build settings

Alternatively, use the Vercel CLI:

# Install Vercel CLI
npm install -g vercel
 
# Deploy
vercel

Next.js-Specific Deployment Options

Self-Hosted Static Export

For static site hosting (without server-side features):

1. Add this to your next.config.mjs:

export default {
  output: 'export',
}

2. Build your application:

npm run build

This generates a static out directory you can deploy to any static hosting service.

Node.js Server

For server-side rendering with a Node.js server:

1. Build your application:

npm run build

2. Start the Node.js server:

npm run start

This starts a production server on port 3000 by default.

Common Issues

Image Optimization

When using Next.js Image Optimization with static export, configure the loader in next.config.mjs:

export default {
  images: {
    loader: 'custom',
    loaderFile: './my-image-loader.js',
  }
}

Create a custom loader file:

// my-image-loader.js
export default function myImageLoader({ src, width, quality }) {
  return `https://your-cdn.com/${src}?w=${width}&q=${quality || 75}`
}

API Routes

API routes don't work with static exports. You'll need a server-side deployment method or serverless functions if you're using API routes.

Server Components

Server components require a server-side deployment method, such as Vercel, Node.js server, or Docker. They won't work with static exports.

Testing Production Build Locally

To preview your production build before deployment:

npm run build
npm run start

Visit http://localhost:3000 to preview your production build.

Continuous Deployment

For automated deployments, configure CI/CD pipelines:

GitHub Actions Example

Create a .github/workflows/deploy.yml file:

name: Deploy Next.js site to Vercel
 
on:
  push:
    branches: ["main"]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install Vercel CLI
        run: npm install --global vercel@latest
      - name: Deploy to Vercel
        run: vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}

For more information on Next.js deployment, refer to the official documentation.