
## Table of Contents

1. [Introduction](#introduction)
2. [Understanding the Image Loading Issue](#understanding-the-image-loading-issue)
3. [What is netlify.toml?](#what-is-netlifytoml)
4. [Why Image Optimization Fails on Netlify](#why-image-optimization-fails-on-netlify)
5. [Solution: Disable Image Optimization](#solution-disable-image-optimization)
6. [Setting Up netlify.toml](#setting-up-netlifytoml)
7. [HTTP to HTTPS Redirect Configuration](#http-to-https-redirect-configuration)
8. [Complete netlify.toml Example](#complete-netlifytoml-example)
9. [Deploying to Netlify](#deploying-to-netlify)
10. [Conclusion](#conclusion)

## Introduction

Deploying a Next.js application to Netlify can be smooth, but you might encounter an unexpected issue: images fail to load in production even though they work perfectly locally and on Vercel. This typically happens because of how Next.js handles image optimization and how Netlify processes serverless functions. In this guide, we'll explore the root cause, understand the `netlify.toml` configuration file, and implement a complete solution including HTTPS redirects.

## Understanding the Image Loading Issue

When you deploy your Next.js application to Netlify, you might notice images appearing broken or failing to load. Looking at the browser's Network tab, you'll see requests like:

```
/_next/image?url=https%3A%2F%2Fpicsum.photos%2Fseed%2Fimage%2F360%2F160&w=640&q=75
```

These requests return 404 errors or fail silently, even though the external image URL (like `picsum.photos` or `unsplash.com`) is valid and accessible.

## What is netlify.toml?

`netlify.toml` is Netlify's configuration file that allows you to define build settings, environment variables, redirects, headers, functions, and other deployment behaviors. It's similar to other infrastructure-as-code files like `docker-compose.yml` or `package.json`.

**Key purposes of netlify.toml:**

- Define build commands and publish directory
- Configure environment variables
- Set up redirects and URL rewriting
- Add HTTP headers (security, caching, CORS)
- Configure serverless functions
- Define custom error pages

Unlike Vercel (which auto-detects Next.js configuration), Netlify requires explicit configuration for optimal Next.js support.

## Why Image Optimization Fails on Netlify

Next.js Image Component includes built-in image optimization via the `/_next/image` API endpoint. This works by:

1. Accepting an external image URL
2. Downloading and optimizing the image on-the-fly
3. Serving it in optimized formats (WebP, AVIF)

**However:**

- **Vercel**: Has native support for Next.js Image Optimization as a built-in service ✅
- **Netlify**: Does NOT have a built-in Image Optimization API. The `/_next/image` endpoint doesn't work because Netlify can't run the image processing logic ❌

When Netlify tries to handle the `/_next/image` request, it either:

- Returns a 404 (endpoint not found)
- Times out (no handler)
- Returns an error (serverless function failure)

## Solution: Disable Image Optimization

The fix is to **disable Next.js Image Optimization** when building for Netlify. This tells Next.js to serve images directly from their source URLs without processing.

### Step 1: Update next.config.js

Add environment variable detection and disable optimization:

```javascript
const isNetlify = process.env.NETLIFY === 'true';

const nextConfig = {
  env: {
    // Your existing env vars
  },
  images: {
    unoptimized: isNetlify, // Disable optimization on Netlify
    domains: ['images.unsplash.com', 'picsum.photos', 'cdn.countryflags.com'],
  },
  // ... rest of config
};

module.exports = nextConfig;
```

**Important:** `NETLIFY` is a **built-in environment variable** that Netlify automatically sets to `'true'` during builds. You don't need to manually configure it—it's provided for free by Netlify. This makes detection seamless:

- ✅ On Netlify builds: `process.env.NETLIFY === 'true'` (automatic)
- ✅ On Vercel/local: `process.env.NETLIFY` is undefined → images use optimization
- ✅ The same codebase works on both platforms without manual setup

## Setting Up netlify.toml

Create a `netlify.toml` file in your project root. This tells Netlify how to build and serve your Next.js app.

### Basic Configuration

```toml
[build]
  command = "npm run build"
  publish = ".next"

[functions]
  external_node_modules = ["sharp"]
```

**Explanation:**

- `[build]`: Defines how Netlify builds your project
  - `command = "npm run build"`: Runs your Next.js build
  - `publish = ".next"`: Publishes the `.next` directory (Next.js output)
- `[functions]`: Serverless function configuration
  - `external_node_modules = ["sharp"]`: Allows the `sharp` library (image processing) if needed

## HTTP to HTTPS Redirect Configuration

Modern web standards require HTTPS. You can enforce this at the Netlify level using `netlify.toml`:

```toml
[[redirects]]
  from = "http://*"
  to = "https://:splat"
  status = 301
  force = true
```

**How it works:**

- `from = "http://*"`: Matches all HTTP URLs (wildcard `*`)
- `to = "https://:splat"`: Redirects to HTTPS, preserving the path (`:splat` is Netlify's placeholder)
- `status = 301`: Permanent redirect (helps SEO)
- `force = true`: Forces redirect even if a file exists at that path

**Example:**

- `http://example.com/blog/post-1` → `https://example.com/blog/post-1` (path preserved)

## Complete netlify.toml Example

Here's a production-ready configuration with security headers:

```toml
# Netlify configuration for Next.js application

[build]
  command = "npm run build"
  publish = ".next"

[functions]
  external_node_modules = ["sharp"]

# Redirect HTTP to HTTPS (permanent redirect)
[[redirects]]
  from = "http://*"
  to = "https://:splat"
  status = 301
  force = true

# Security headers
[[headers]]
  for = "/*"
  [headers.values]
    # Enable HTTPS everywhere and HSTS (strict transport security)
    Strict-Transport-Security = "max-age=31536000; includeSubDomains; preload"
    # Prevent clickjacking attacks
    X-Frame-Options = "DENY"
    # Prevent MIME type sniffing
    X-Content-Type-Options = "nosniff"
    # Enable browser XSS protection
    X-XSS-Protection = "1; mode=block"

# Cache static assets longer (optional)
[[headers]]
  for = "/_next/static/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

# Custom error page (optional)
[[redirects]]
  from = "/*"
  to = "/404.html"
  status = 404
```

## Deploying to Netlify

Once you have `netlify.toml` ready, follow these steps:

### Option 1: Using Netlify UI

1. Push your code to GitHub
2. Connect your repository to Netlify
3. Deploy (that's it! Netlify automatically handles the rest)

✅ **No manual environment variable setup needed.** Netlify automatically sets `NETLIFY=true` during builds.

### Option 2: Using Netlify CLI

```bash
# Install Netlify CLI
npm install -g netlify-cli

# Deploy
netlify deploy --prod
```

Netlify will automatically:

- Detect your `netlify.toml` configuration
- Set the `NETLIFY` environment variable to `'true'`
- Build your Next.js app with image optimization disabled

### Verify Configuration

After deployment:

1. **Check images load**: Visit your site and verify all images render correctly
2. **Test HTTPS redirect**: Visit `http://example.com` → should redirect to `https://example.com`
3. **Inspect headers**: Use browser DevTools → Network tab → check response headers for security directives

## Conclusion

By understanding how Next.js Image Optimization works and Netlify's limitations, you can configure your application to work seamlessly across different platforms. The `netlify.toml` file is your gateway to fine-tuning deployment behavior, from disabling image optimization to enforcing HTTPS.

**Key takeaways:**

- ✅ Disable image optimization on Netlify using `unoptimized: isNetlify` in `next.config.js`
- ✅ Use `netlify.toml` to configure build settings, redirects, and security headers
- ✅ Enforce HTTPS redirects for better security and SEO
- ✅ Test thoroughly before pushing to production

With this setup, your Next.js blog will work reliably on Netlify with all images loading correctly and your site protected by modern security standards.


Learn how to fix image loading issues when deploying Next.js applications to Netlify, understand what netlify.toml is, and configure redirects like HTTP to HTTPS using best practices.

Configuration

Fixing Image Loading Issues on Netlify with netlify.toml Configuration

Subscribe for Updates