# I Built Nextvital to Turn Lighthouse Warnings Into Actual Next.js Fixes

I've seen the same scenario play out dozens of times.

A developer opens Lighthouse. The score is 54. They see warnings like **"Serve images in next-gen formats"** and **"Eliminate render-blocking resources."**

They know performance matters. But the report tells them **what's wrong—not what to actually change in their Next.js codebase.**

So they close the tab and get back to building features.

**That's the gap I built Nextvital to solve.**

* * *

## What Is Nextvital?

**Nextvital is an open-source performance auditing tool for Next.js developers.**

Give it any public URL. It runs a Google PageSpeed Insights audit and translates Lighthouse findings into **specific Next.js fixes**.

Instead of:

> "Optimise your images."

You get:

> Use `next/image` with the correct `sizes` prop.

Instead of:

> "Eliminate render-blocking resources."

You get:

> Replace the external Google Fonts request with `next/font`.

Instead of:

> "Reduce unused JavaScript."

You might get:

> Lazy-load this component with `next/dynamic`.

Every fix includes:

*   The Lighthouse audit that triggered it
    
*   Estimated savings in KB or milliseconds
    
*   Before/after Next.js code examples
    
*   A direct link to the relevant Next.js documentation
    

**Paste a URL. Get a ranked to-do list. Open your editor and start at the top.**

* * *

## The Problem With Generic Performance Advice

Most performance tools operate at the browser level.

That's useful—but there's a translation layer missing for framework developers.

For example, Lighthouse might tell you:

**"Serve images in next-gen formats."**

A Next.js developer doesn't necessarily need to manually convert an image. The actual fix could involve:

*   Adding `width` and `height` to `next/image`
    
*   Adding the correct `sizes` attribute
    
*   Using `next/image` instead of a regular `<img>`
    
*   Configuring remote image patterns
    
*   Changing how a large hero image is loaded
    

The same problem appears across fonts, JavaScript, caching, rendering, and code splitting.

Every developer has to translate the Lighthouse recommendation into a framework-specific implementation.

After doing that repeatedly, I mapped the relationship out properly:

**38 Lighthouse audit IDs → specific Next.js APIs and patterns.**

That mapping is the core of Nextvital.

* * *

# Key Features

## 1\. Instant URL Audits

Paste any public URL and Nextvital handles the rest.

The audit pipeline includes:

*   URL validation
    
*   SSRF protection
    
*   24-hour Redis caching
    
*   Per-IP rate limiting
    
*   Google PageSpeed Insights
    
*   Core Web Vitals extraction
    
*   Failed audit grouping
    
*   Potential savings estimation
    
*   Ranked Next.js fixes
    

Cached audits return instantly.

New audits typically take **3–8 seconds**, depending on Google's PageSpeed infrastructure.

* * *

## 2\. Fix Cards With Real Next.js Code

This is where Nextvital goes beyond simply opening PageSpeed Insights.

Every failed audit is translated into a **fix card** containing:

*   The original Lighthouse finding
    
*   Estimated performance impact
    
*   A before/after code example
    
*   Next.js-specific implementation guidance
    
*   A direct link to the documentation
    

The examples target the **Next.js App Router**, with notes for Pages Router where the APIs differ.

Instead of going:

**Lighthouse → Google → Next.js docs → Search → Experiment → Fix**

you can go:

**Lighthouse → Nextvital → Fix**

* * *

## 3\. Progress Dashboard

Performance work isn't a one-time task.

Every audit is saved to your session, giving you a history of previous results and a unified checklist of remaining fixes.

As you make changes and re-audit your site, you can see what's been fixed and what still needs attention.

**One audit tells you where you are. The dashboard shows your progress.**

* * *

## 4\. Shareable Performance Reports

Every audit has a **Copy Share Link** button.

Each result gets a permanent `/r/[id]` URL that is fully server-rendered with:

*   Open Graph metadata
    
*   Twitter Card metadata
    
*   JSON-LD structured data
    

That means you can drop a report directly into Slack, Linear, GitHub, or a pull request and get a proper preview.

No screenshots.

No exported JSON files.

**Just a link.**

* * *

## 5\. Optional BYOK AI Action Plan

Nextvital also includes an optional AI layer.

Bring your own API key from:

*   Anthropic
    
*   Google Gemini
    
*   OpenRouter
    
*   Local Ollama models
    

The AI receives only the audit data generated by Nextvital. It can't invent scores, savings estimates, or findings that aren't present in the report.

It's designed as a **second layer of explanation**, not a replacement for the audit.

And it's completely optional.

Without an API key, Nextvital works normally—the AI panel simply doesn't appear.

### Want everything local?

Run an Ollama model such as `llama3.2` and select **Local (Ollama)**.

The AI runs on your machine with:

*   No account
    
*   No API bill
    
*   No external AI provider
    
*   No audit data leaving your network
    

* * *

# The Technical Foundation

Nextvital is built with **Next.js 16, App Router, and TypeScript strict mode**.

The audit pipeline looks like this:

```text
URL Input
   ↓
Zod Validation + SSRF Protection
   ↓
Redis Cache Check (24h TTL)
   ↓
Per-IP Rate Limit + In-flight Lock + Daily Budget
   ↓
Google PageSpeed Insights API
   ↓
Response Shaping
   ↓
Core Web Vitals + Failed Audits + Savings + Resources
   ↓
Next.js Fix Map
(38 Lighthouse IDs → Actionable Fixes)
   ↓
Results Page + Session History
```

### One design decision I'm particularly happy with

**The cache is checked before the rate limiter.**

If a URL has already been audited within the cache window, the result can be served immediately without consuming the rate-limit bucket.

That means repeated requests for the same URL are cheap, while new audits remain protected against abuse and excessive Google API usage.

### AI security

The AI explain endpoint builds its prompt **server-side from cached audit data**.

The client sends only the provider and model preference—not the audit payload.

This prevents a client request from injecting fabricated audit data into the AI context.

### Testing

Nextvital currently has **402 Vitest tests** covering the core logic without DOM dependencies.

CI runs on GitHub Actions against:

*   Node.js 20
    
*   Node.js 22
    

on every push.

* * *

# Getting Started

Nextvital is self-hosted.

You'll need four environment variables:

```env
GOOGLE_PSI_API_KEY=
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=
NEXT_PUBLIC_APP_URL=
```

Then:

```bash
git clone https://github.com/Skyz03/Next-Vital.git
cd
```