
## 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.

Fixing Image Loading Issues on Netlify with netlify.toml Configuration


## Table of Contents

1. [Introduction](#introduction)
2. [The Problem](#the-problem)
3. [Why Lighthouse in CI/CD Matters](#why-lighthouse-in-cicd-matters)
4. [Issues Encountered](#issues-encountered)
5. [Solutions and Implementation](#solutions-and-implementation)
6. [Best Practices](#best-practices)
7. [Conclusion](#conclusion)

## Introduction

Website performance is critical to user experience, SEO rankings, and conversion rates. However, performance regressions often go unnoticed until they reach production. This post covers how to implement Lighthouse performance testing as part of your CI/CD pipeline to catch performance issues before they impact your users.

## The Problem

Performance regression detection is challenging because:

- **Manual Testing is Inefficient**: Running Lighthouse manually for every build wastes developer time and is easily forgotten.
- **No Baseline Comparison**: Without automated comparison, it's hard to know if a change degrades performance.
- **Silent Performance Degradation**: Small performance issues accumulate and go unnoticed until users complain.
- **Inconsistent Environments**: Local testing environments differ from production, making results unreliable.
- **Lack of Visibility**: Teams don't have a clear view of performance trends over time.

## Why Lighthouse in CI/CD Matters

Integrating Lighthouse into your CI/CD pipeline provides:

- **Automated Performance Checks**: Every pull request gets a performance audit automatically.
- **Baseline Comparisons**: Detect when performance scores drop relative to the previous build.
- **Fast Feedback Loop**: Developers get immediate performance feedback while making changes.
- **Enforced Standards**: Set minimum performance thresholds that block merges if not met.
- **Historical Tracking**: Build a performance history to understand trends and improvements.

## Issues Encountered

### 1. **Lighthouse Variability and Flaky Results**

Lighthouse results vary between runs due to:

- Network throttling differences
- CPU throttling inconsistencies
- Background processes on the CI runner

**Solution**: Run Lighthouse multiple times and average the results, or use median values. Set realistic thresholds (e.g., 85/100 instead of 95/100) to account for variability.

```yaml
# Example: Run Lighthouse 3 times and average scores
- name: Run Lighthouse Audit
  uses: actions/checkout@v3
- name: Setup Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18'
- name: Install dependencies
  run: npm install -g @lhci/cli@latest
- name: Run LHCI
  run: lhci autorun
```

### 2. **Lighthouse CLI Timeout Issues**

Large pages or slow networks can cause Lighthouse to timeout during CI runs.

**Solution**:

- Increase the timeout setting in `lighthouserc.js`:
  ```javascript
  module.exports = {
    ci: {
      collect: {
        numRetries: 3,
        settings: {
          chromeFlags: ['--disable-dev-shm-usage'], // Use disk instead of shared memory
          onlyCategories: ['performance', 'accessibility'], // Only audit needed categories
        },
      },
    },
  };
  ```
- Use `--disable-dev-shm-usage` flag to prevent memory issues on CI runners with limited shared memory.

### 3. **Authentication and Protected Pages**

Lighthouse cannot audit pages behind authentication or paywalls.

**Solution**:

- Test public pages only
- Use a test account for authenticated pages:
  ```javascript
  settings: {
    settings: {
      formFactor: 'mobile',
      screenEmulation: {
        mobile: true,
        width: 412,
        height: 823,
      }
    }
  }
  ```

### 4. **Comparison Baseline Not Available**

New projects don't have a baseline to compare against initially.

**Solution**:

- Store initial results as a baseline in your repository
- Use Lighthouse CI storage API to store historical results
- Start with informational thresholds and enforce stricter ones over time

### 5. **CI Runner Performance Constraints**

CI runners may have different hardware than production, causing misleading results.

**Solution**:

- Use consistent CI runners (e.g., GitHub Actions on the same machine type)
- Normalize CPU and network throttling settings
- Focus on relative changes rather than absolute scores

## Solutions and Implementation

### Step 1: Install Lighthouse CI

```bash
npm install -g @lhci/cli@latest
```

### Step 2: Create `lighthouserc.js` Configuration

```javascript
// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      url: ['http://localhost:3000', 'http://localhost:3000/about'],
      numberOfRuns: 3,
      settings: {
        chromeFlags: ['--disable-dev-shm-usage', '--no-sandbox'],
      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        'categories:performance': ['error', { minScore: 0.85 }],
        'categories:accessibility': ['error', { minScore: 0.9 }],
        'categories:best-practices': ['error', { minScore: 0.85 }],
        'categories:seo': ['error', { minScore: 0.9 }],
      },
    },
  },
};
```

### Step 3: GitHub Actions Workflow

```yaml
# .github/workflows/lighthouse.yml
name: Lighthouse CI

on: [push, pull_request]

jobs:
  lighthouse:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Install Lighthouse CI
        run: npm install -g @lhci/cli@latest

      - name: Start local server
        run: npm start &
        env:
          NODE_ENV: production

      - name: Wait for server
        run: sleep 5

      - name: Run Lighthouse CI
        run: lhci autorun

      - name: Upload Lighthouse results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: lighthouse-results
          path: .lighthouseci/
```

### Step 4: Store and Compare Results

Use Lighthouse CI's temporary public storage or set up persistent storage:

```javascript
upload: {
  target: 'temporary-public-storage', // For free tier
  // OR for persistent storage:
  // target: 'lhci',
  // serverBaseUrl: 'https://your-lhci-server.com',
  // token: process.env.LHCI_TOKEN,
}
```

## Best Practices

1. **Start with Loose Thresholds**: Begin with achievable thresholds (e.g., 70-80) and gradually increase them as performance improves.

2. **Test Multiple Routes**: Audit both your homepage and key user paths to get comprehensive coverage.

3. **Monitor Trends, Not Just Pass/Fail**: Set up dashboards to visualize performance over time using tools like:

   - Lighthouse CI dashboard
   - Custom metrics stored in your database
   - GitHub Actions workflow visualizations

4. **Use Performance Budgets**: Define maximum file sizes, JavaScript budgets, and resource counts:

   ```javascript
   'resource-summary': ['error', {
     'script': [{ budget: 170 }],
     'total': [{ budget: 300 }]
   }]
   ```

5. **Exclude External Dependencies**: Focus on your own code by excluding third-party scripts when possible:

   ```yaml
   settings:
     skipAudits: ['uses-rel-preconnect']
   ```

6. **Schedule Regular Full Audits**: Run comprehensive Lighthouse audits on a schedule to catch performance issues that PR-level audits might miss:

   ```yaml
   schedule:
     - cron: '0 0 * * 0' # Weekly on Sunday
   ```

7. **Communicate Results**: Post Lighthouse results as comments on pull requests for visibility:
   ```yaml
   - name: Comment PR with results
     uses: actions/github-script@v6
     with:
       script: |
         github.rest.issues.createComment({
           issue_number: context.issue.number,
           owner: context.repo.owner,
           repo: context.repo.repo,
           body: 'Performance Audit: [View results](https://your-storage.com/results)'
         })
   ```

## Conclusion

Implementing Lighthouse in your CI/CD pipeline transforms performance from an afterthought into a first-class requirement. While you'll encounter variability, timeouts, and baseline challenges, these are solvable with proper configuration and realistic thresholds.

The key is to start simple, automate early, and gradually increase strictness as your team's performance culture matures. By catching performance regressions before they reach production, you protect your users' experience and maintain the speed that drives engagement and conversions.

For more resources:

- [Lighthouse CI Official Docs](https://github.com/GoogleChrome/lighthouse-ci)
- [Web Vitals Guide](https://web.dev/vitals/)
- [Performance Budgets](https://www.smashingmagazine.com/2015/09/3-types-of-performance-budgets/)


Implement automated Lighthouse performance testing in your CI/CD pipeline to catch performance regressions early. Learn the problems, challenges, and solutions for integrating Lighthouse into GitHub Actions or other CI systems.

Lighthouse Pipeline - Automate Performance Testing in CI/CD


## Table of Contents

1. [Introduction](#introduction)
2. [The Main Branch: Squash and Merge](#the-main-branch-squash-and-merge)
3. [Other Benefits](#other-benefits)
4. [Other Cases for Main](#other-cases-for-main)
5. [Example: Create Feature Branch](#example-create-feature-branch)
6. [The Release Branch: Fast-Forward](#the-release-branch-fast-forward)
7. [Syntax: Syncing Main to Release](#syntax-syncing-main-to-release)
8. [Conclusion](#conclusion)

## Introduction

This blog demonstrates a clean and efficient Git workflow tailored for small teams. We will focus on keeping the `main` branch history readable while ensuring the `release` branch remains a stable mirror of production.

## The Main Branch: Squash and Merge

When working on features or bugs, developers often create dozens of "work-in-progress" commits. To keep the `main` branch clean, we use the **Squash and Merge** pattern. This collapses all commits from a branch into a single, high-quality commit on `main`.

- **Feature Branches (`feature/description`):** Use this for new development.
- **Bug Branches (`bugs/description`):** Use this for fixing issues found in development.

## Other Benefits

- **Feature Reversion:** If a feature introduced a failure, squashing makes it easier to revert the change.
- **Simplified "Git Blame":** `git blame` will point to a feature instead of an individual commit like `fixed typo`.
- **Avoiding "Broken" Intermediate Commits:** Sometimes in a feature branch a developer fixes the build or unit tests. If you don't use squash and keep all history, the main branch will contain "broken" build commits.

## Other Cases for Main

Beyond features and bugs, you might merge into `main` for:

- **Refactoring:** Code cleanup that doesn't change functionality.
- **Documentation:** Updates to README files or API docs.
- **CI/CD Updates:** Modifying GitHub Actions or deployment scripts.
- **Dependency Updates:** Merging automated PRs (like Dependabot) to keep libraries secure.

## Example: Create Feature Branch

```
# Ensure you are on main and up to date
git checkout main
git pull origin main

# Create and switch to a new feature branch
git checkout -b feature/describe-feature
```

## The Release Branch: Fast-Forward

For small teams, we want the `release` branch to be easy to manage. We use the **Fast-Forward** pattern, which keeps all commit history identical between `main` and `release`.

**Alternative Approaches:**

- **Merge Commits:** Some teams use `--no-ff` to create a dedicated "Merge node" to show exactly when a release happened.
- **Squash to Release:** Some teams squash all of `main` into one single "Version 1.0" commit on the release branch, though this makes tracking individual changes harder.

## Syntax: Syncing Main to Release

To move your verified code from `main` to `release` using the fast-forward pattern, run:

```bash
git checkout release
git merge main --ff-only
git push origin release
```

## Conclusion

By using Squash for development and Fast-Forward for releases, your team maintains a professional, readable history that is easy to debug. Hopefully, you find this pattern helpful for your team's workflow!


A practical guide on using Squash and Fast-Forward patterns to manage a clean Git workflow.

DevOps

Fixing Image Loading Issues on Netlify with netlify.toml Configuration

Lighthouse Pipeline - Automate Performance Testing in CI/CD

Git Merge Patterns for Main and Release Branches

DevOps

Fixing Image Loading Issues on Netlify with netlify.toml Configuration

Lighthouse Pipeline - Automate Performance Testing in CI/CD

Git Merge Patterns for Main and Release Branches

Subscribe for Updates