DEV Community: Ricardo Diaz Miralles

Next.js opengraph-image applies to one route, not one subtree

Ricardo Diaz Miralles — Mon, 10 Aug 2026 17:06:11 +0000

I shipped a fix for my broken link previews and made 65 of 66 pages worse. The
build passed. Nothing warned me. The only way I found out was reading the
compiled HTML.

The original bug

Every page on the site declared this:

<meta property="og:image" content="https://example.net/favicon.svg" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

An SVG. Facebook, X, LinkedIn and WhatsApp do not render SVG as og:image, so
every link anyone shared appeared with no thumbnail at all. The declared
dimensions were fiction too — a favicon is a small square, not 1200×630.

It came from a default parameter in my metadata helper that nobody had revisited:

export function createPageMetadata({
  title,
  description,
  path = "/",
  image = "/favicon.svg",   // <- here
}) {

I will not pretend this is a subtle one. It is a site whose entire pitch is
"check your images before you publish them", failing at exactly that.

The obvious fix

Next.js has a file convention for this. Drop opengraph-image.tsx in app/,
export a function returning an ImageResponse, and Next generates the PNG at
build time and writes the tags for you:

// app/opengraph-image.tsx
import { ImageResponse } from "next/og";

export const size = { width: 1200, height: 630 };
export const contentType = "image/png";
export const alt = "…";

export default function Image() {
  return new ImageResponse(<div style={{ /* … */ }}>…</div>, { ...size });
}

I added that, plus one per route for the five pages that deserved their own
artwork. Removed the hardcoded image default so nothing would override the
generated file. next build — clean. Route list showed the image routes being
prerendered:

├ ○ /opengraph-image
├ ○ /instagram-image-checker/opengraph-image
├ ○ /social-media-image-sizes/opengraph-image
...

Looks finished. It was not.

What actually shipped

Before deploying I grepped the compiled HTML, which is the only reason this
story has a happy ending:

index                          -> /opengraph-image?82cf03fe3b00233a
instagram-image-checker        -> /instagram-image-checker/opengraph-image?2e46…
social-media-image-sizes       -> /social-media-image-sizes/opengraph-image?d5aa…
guides/image-alt-text          -> NO og:image
image-seo-meta-checker         -> NO og:image
open-graph-image-checker       -> NO og:image
es/social-media-image-sizes    -> NO og:image
es/instagram-image-checker     -> NO og:image

Six routes had an image. Every other page had no og:image tag at all —
worse than the SVG, because at least the SVG was a URL some scrapers would try.

The controlled test

I did not want to publish a claim I had only seen once in a messy state, so I
reduced it. Branch, one file at the root, nothing else emitting images:

// app/opengraph-image.tsx  — the only image file in the project
export default function Image() {
  return new ImageResponse(<div …>ROOT OG</div>, { ...size });
}

Build, then check:

/                       ->  /opengraph-image?29e6d2edd61b209f
/about                  ->  no og:image
/guides                 ->  no og:image
/guides/image-alt-text  ->  no og:image
/image-alt-text-checker ->  no og:image
/es/about               ->  no og:image

Then the question anyone will ask next — does a file in a segment cover that
segment's children? Added app/guides/opengraph-image.tsx and rebuilt:

/guides                      ->  /guides/opengraph-image?321e476533b4f29e
/guides/image-alt-text       ->  no og:image
/guides/image-size-for-web   ->  no og:image

No. app/guides/opengraph-image.tsx covers /guides and nothing beneath it.
The file applies to the one route the file sits in. Next.js 16.2.4.

Why the mental model is wrong

The docs are not wrong here, and it is worth being precise about that. The
API reference
says the convention sets the image "for a route segment", and that you add
the file to "any route segment". Exactly right, both times. I read straight
past it, twice.

The reason it is easy to misread is that the other metadata system in App
Router does cascade. A metadata object exported from a layout merges down into
every page beneath it — that is the whole point of putting metadataBase,
title.template and openGraph.siteName in the root layout once. So you build a
mental model where "metadata set high in the tree applies to everything below",
and then the file convention, which lives in the same feature area and is
described on adjacent doc pages, does not behave that way.

And the failure mode is silent. A missing og:image is not an error. There is no
build warning, no type error, no runtime complaint. The page renders perfectly.
You find out when someone shares a link and it comes out as a grey box, which
might be weeks later.

The fix that scales

The literal fix is one opengraph-image.tsx per route segment. For this project
that meant about 40 files, and doubling again for the /es subtree — plus a
matching twitter-image.tsx in each, or accept that X falls back to og:image.

So instead: one static route that serves every variant, and one default in the
metadata helper.

// app/og/[slug]/route.tsx
import { createOgImage } from "@/lib/ogImage";
import { DEFAULT_OG_SLUG, OG_VARIANTS } from "@/lib/ogVariants";

export const dynamic = "force-static";
export const dynamicParams = false;

export function generateStaticParams() {
  return Object.keys(OG_VARIANTS).map((slug) => ({ slug }));
}

export async function GET(_request: Request, { params }) {
  const { slug } = await params;
  return createOgImage(OG_VARIANTS[slug] ?? OG_VARIANTS[DEFAULT_OG_SLUG]);
}

force-static plus generateStaticParams means these are prerendered at build
time exactly like the file convention would be — the route handler never runs on
a request. Slugs carry the extension (default.png, instagram.png) so the URL
looks like an image to anything that cares.

Then the helper gives every page one by default:

const ogImage = ogImageMeta(ogVariant);   // ogVariant defaults to "default.png"

return {
  openGraph: { /* … */ images: [ogImage] },
  twitter:   { card: "summary_large_image", /* … */ images: [ogImage] },
};

A page that wants its own passes one word:

export const metadata = createPageMetadata({
  title: "Instagram Image Size Checker",
  path: "/instagram-image-checker",
  ogVariant: "instagram.png",
});

One more detail that is easy to get wrong: keep the variant catalogue in a module
that does not import next/og. If your metadata helper imports the file that
imports ImageResponse, every page that reads metadata drags the renderer along
with it. Catalogue and constants in one file, the ImageResponse JSX in another.

Result — 66 real pages, 66 with a PNG:

og:image        https://publishpixel.net/og/instagram.png
og:image:type   image/png
og:image:width  1200
og:image:height 630

What this costs

Two things you give up, and you should decide they are acceptable rather than
discover them:

You write the dimension tags yourself. The file convention reads size and
contentType from your exports and emits og:image:width, og:image:height and
og:image:type for free. Rolling your own route means declaring them in your
metadata — and if you change the canvas size in one place and not the other, you
are back to lying about dimensions, which is the bug I started with. Derive both
from the same constant.

You lose per-route params. app/shop/[slug]/opengraph-image.tsx receives
the route's params and can generate an image from the actual product. A shared
route cannot. If your images are genuinely per-URL — a blog with 400 posts
rendering each title into the card — the file convention is the right tool and
you should use it, one file in the dynamic segment, which covers every URL under
it because they are all the same route.

That is the real dividing line. Per-route images: file convention. A handful
of shared images across many static routes: a shared route beats 40 files.

How to check your own project

After next build, list the prerendered pages that have no og:image:

grep -L 'property="og:image"' $(find .next/server/app -name '*.html')

grep -L prints the files without a match. Anything unexpected in that list is a
page whose links will share as a grey box. Only covers prerendered routes, so
check dynamic ones against a running server.

Worth doing even if you never touch the file convention — the SVG default that
started all this had been in production for months, and no tool I was using
flagged it, because a page with a valid og:image URL pointing at an unsupported
format looks fine to a validator right up until a real scraper tries to render it.

The project is PublishPixel, a set of browser-based
image checks that run locally without uploading anything — I build and maintain
it, and the numbers above come from its production deployment. The page that
sent me looking was the
Open Graph image checker,
which teaches people to get link previews right and was, at the time, shipping
its own preview as an SVG.

If you have hit the opposite version of this — a file convention you expected to
apply to one route and found applied to many — I would like to hear it. I now
assume nothing in App Router cascades until I have checked the compiled HTML.

One line in your root layout can make every Next.js page render on demand

Ricardo Diaz Miralles — Thu, 06 Aug 2026 17:53:44 +0000

I spent a week looking at the wrong things.

The site is a small Next.js 16 App Router project on Netlify. Static content,
a few client-side tools, nothing exotic. But every response came back with this:

Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate
Cache-Status: "Netlify Durable"; fwd=bypass, "Netlify Edge"; fwd=miss

no-store. On a content site. Every request going to origin, every time.

I assumed it was a Netlify configuration problem, because that is what the
header looks like. It was not. The cause was four lines in my root layout, and
the fix took two files.

The symptom

next build prints a legend at the end of the route list that is easy to skim
past:

○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

Mine looked like this:

├ ƒ /
├ ƒ /about
├ ƒ /guides
├ ƒ /guides/image-size-for-web
├ ƒ /compress-image
...
├ ○ /sitemap.xml

Seventy-six ƒ. One ○, and the one static route was the sitemap.

Every page in the project was being server-rendered per request. Not because any
page asked for it, but because something above them did.

The cause

Here is the relevant part of my root layout:

import { headers } from "next/headers";

export default async function RootLayout({ children }) {
  const headersList = await headers();
  const pathname = headersList.get("x-publishpixel-pathname") || "/";
  const locale = getLocaleFromPathname(pathname);

  return (
    <html lang={locale}>
      {/* ... */}
    </html>
  );
}

I needed the locale in the root layout to set <html lang>, and the root layout
is a Server Component with no access to the current path. So I had middleware
set a header with the pathname and read it back with headers().

It works. It is also the whole problem.

headers() is a Dynamic API. Calling it opts the route into dynamic rendering,
because the output now depends on the request. And because I called it in the
root layout, every route under it inherited that. One call, seventy-six
dynamic routes.

Netlify then does the correct thing for a dynamically rendered response: it
refuses to cache it. no-store was not a misconfiguration. It was Netlify
honouring what my app told it.

This is the part I want to flag, because it is what cost me the week: the
header made it look like an infrastructure problem. I read Netlify docs, I
looked at netlify.toml, I checked the adapter. The answer was in my own layout.

The fix

The locale genuinely does depend on the URL. But I already had a client
component deriving it, and I had not noticed:

"use client";
import { usePathname } from "next/navigation";

export function LanguageProvider({ children, initialLanguage = "en" }) {
  const pathname = usePathname();
  const routeLanguage = getLocaleFromPathname(pathname || "/");
  const [language, setLanguage] = useState(initialLanguage);

  useEffect(() => {
    setLanguage(routeLanguage);
    document.documentElement.lang = routeLanguage;
  }, [routeLanguage]);
  // ...
}

usePathname resolves during server rendering too. In a statically generated
route it resolves at build time, per route, because each route is prerendered
separately. The provider was already receiving the right answer from the router.
It was just throwing it away on the first render in favour of the
initialLanguage prop that headers() was feeding it.

So the state seeds from the route instead:

-export function LanguageProvider({ children, initialLanguage = "en" }) {
+export function LanguageProvider({ children }) {
   const pathname = usePathname();
   const routeLanguage = getLocaleFromPathname(pathname || "/");
-  const [language, setLanguage] = useState(initialLanguage);
+  const [language, setLanguage] = useState(routeLanguage);

And the root layout stops reading headers entirely:

-export default async function RootLayout({ children }) {
-  const headersList = await headers();
-  const pathname = headersList.get("x-publishpixel-pathname") || "/";
-  const locale = getLocaleFromPathname(pathname);
-
+export default function RootLayout({ children }) {
   return (
-    <html lang={locale}>
+    <html lang="en">

Two files. The middleware also stopped propagating a header nobody read any more.

The result

Before:  1 static route,  76 dynamic
After:  77 static routes,  0 dynamic

In production:

	Before	After
`Cache-Control`	`private, no-cache, no-store`	`public, max-age=0, must-revalidate`
`Cache-Status`	`Netlify Durable; fwd=bypass`	`Netlify Durable; hit`
TTFB	0.34 – 0.44 s	0.16 – 0.20 s

Roughly half the time to first byte, on content that had not changed at all.

The tradeoff I accepted

The root layout now serves lang="en" in the static HTML for every route,
including the Spanish ones, and the provider corrects it on hydration.

I looked at doing this properly with route groups and two root layouts
(app/(en)/layout.tsx and app/(es)/layout.tsx), which is the canonical
solution and keeps lang correct in the raw HTML. I did not, because it meant
relocating around sixty route directories for an attribute that Google has
repeatedly said it ignores for language detection — the signals that actually
matter are hreflang and the visible content language, and both were already
correct.

Accessibility was the real concern, so the Spanish subtree gets a small layout
that fixes the attribute before hydration:

export default function SpanishLayout({ children }) {
  return (
    <>
      <script dangerouslySetInnerHTML={{ __html: 'document.documentElement.lang="es"' }} />
      {children}
    </>
  );
}

Worth being explicit that this is a compromise, not a best practice. If you are
starting a multilingual App Router project from scratch, use route groups with
separate root layouts and skip this entirely.

How to check your own project

Run next build and count the ƒ markers. If routes you expect to be static
are dynamic, something is calling a Dynamic API above them. The usual suspects:

headers() and cookies()
searchParams in a page or layout
noStore() or connection()
export const dynamic = "force-dynamic" left over from debugging
a fetch with cache: "no-store" in a layout

The higher up the tree the call is, the more it costs. In a leaf page it makes
one route dynamic. In the root layout it makes all of them dynamic.

One thing that helped me: check the legend, not just the list. It is easy to
read seventy route names and never notice they all carry the same marker.

The project is PublishPixel, a set of
browser-based image checks that run locally without uploading anything. The
measurements above come from its production deployment; the
social media image sizes reference
is the page I was profiling when I noticed the header.

If you have hit the same thing with a different Dynamic API, I would like to
hear which one — I suspect searchParams in a layout catches more people than
headers() does.

The pre-publish image checklist: 7 things I verify before any image goes live

Ricardo Diaz Miralles — Fri, 03 Jul 2026 22:44:18 +0000

Every developer has shipped an image that was too heavy, wrongly sized, or worse: one that still had GPS coordinates buried in its EXIF data. I did it enough times that I ended up building a checklist, and eventually a set of free browser tools around it. Here is the checklist, with both manual ways to run each check and the shortcut.

1. Dimensions: is it the size it will actually display at?

Serving a 4000px-wide photo in an 800px container wastes bandwidth and hurts LCP. Check the rendered size in DevTools (hover the img in the Elements panel) and compare it with the intrinsic size. As a rule of thumb, export at 1x and 2x of the display size and let srcset do the rest.

<img src="hero-800.webp"
     srcset="hero-800.webp 1x, hero-1600.webp 2x"
     width="800" height="450" alt="...">

2. File size: does it fit your budget?

For most content images, aim for under ~150 KB; hero images can justify more. If you are on Node, sharp handles resizing and compression in one pass:

import sharp from "sharp";
await sharp("input.jpg").resize(1600).webp({ quality: 78 }).toFile("hero.webp");

3. Format: WebP/AVIF unless you have a reason not to

JPEG/PNG still make sense for compatibility corner cases, but WebP typically cuts 25-35% at equal quality, and AVIF more. Photographs: AVIF/WebP. Logos and flat art: SVG. Screenshots: WebP or PNG.

4. Metadata: strip what you don't want public

This is the one people forget. Photos from phones carry EXIF: device model, timestamps, and often GPS location. Check what's inside with exiftool:

exiftool photo.jpg | grep -i -E "gps|serial|owner"

Re-exporting through most build pipelines (sharp, imagemin) strips EXIF, but images uploaded straight to a CMS often keep it.

5. Filename and alt text: the SEO part

IMG_4032.jpg tells search engines nothing. blue-running-shoes-side-view.webp does. Same for alt text: describe the image for someone who can't see it. That serves accessibility first and image SEO as a side effect.

6. Social readiness: will the crop survive each platform?

The same source image gets cropped differently by Open Graph previews (1.91:1), Instagram (4:5 or 1:1), YouTube thumbnails (16:9 with TV-safe margins)... If a campaign matters, prepare dedicated crops. I keep a cheat sheet of every platform's exact pixel sizes because they change every year.

7. Open Graph: does the preview actually render?

Before sharing, verify og:image resolves, is at least 1200x630, and isn't blocked by robots. The classic way is the Meta Sharing Debugger or curl + eyeballing the tags:

curl -s https://example.com | grep -o '<meta property="og:[^>]*>'

The shortcut

Running all seven checks by hand gets old fast. I built PublishPixel to run them in one pass: you drop an image and it reports dimensions, weight, format fit, filename, alt-text plan, metadata (including GPS), and readiness for web/SEO/social/YouTube. Everything runs client-side in your browser: no upload, no account, files never leave your machine. It's free; it exists because of this checklist.

Disclosure: PublishPixel is my project. The manual methods above work fine without it. The point is to run the checklist somehow before hitting publish.

What would you add as check #8?

A warehouse supervisor's guide to shipping a SaaS in 3 weeks (with a lot of AI help)

Ricardo Diaz Miralles — Fri, 01 May 2026 18:41:25 +0000

Hey DEV community 👋

I'm Ricardo. By day I run a warehouse in Boston, Lincolnshire (UK). By night, for the last few weeks, I've been building a SaaS with the help of AI tools — and as of this week, it's live in production with real Stripe payments.

This post is partly an introduction, partly a "non-developer founder ships product in 2026" snapshot.

The product

FairTime is a meeting scheduler that finds times across time zones and ranks options by attendance, comfort, and fairness — so the same person doesn't always end up taking the 11pm or the 6am call.

The reason it exists is personal. My family is scattered across Venezuela, the UK, and Spain. Every video call, someone is eating dinner late or waking up early. Almost always my mum. I wanted to build something that rotates the inconvenience instead of always defaulting to whoever complains less.

Then I realised distributed teams have the same problem dressed up in calendar invites.

The stack

Next.js 16 (App Router, Turbopack) — frontend + API routes
Stripe — subscriptions, with two-layer anti-trial-abuse (email + card fingerprint)
Turso (libSQL) — edge database for fairness history and trial tracking
Tailwind + shadcn/ui — UI
Netlify — hosting

Bilingual EN/ES from day one — useful for hispano teams.

Where AI fits in

I am not a developer. I read code, I can edit it, I can spot when something looks wrong — but I can't write 800 lines of TypeScript from scratch. AI tools (Claude in particular) have done most of the heavy lifting on the code I couldn't write myself.

What I bring: product judgement, the actual problem, attention to detail, and the willingness to push back when the AI suggests something wrong or over-engineered.

What I learned: AI doesn't replace understanding. The bugs I spent the most time on were the ones where I trusted the AI's first answer instead of pushing it to explain why.

Where I am right now

Started early April 2026
Solo founder, no investors
No paying users yet (the honest number)
Stripe live, anti-trial-abuse layered, OAuth verification with Google in progress
Just submitted to Capterra, working on getting indexed properly

What I'd love from you

Honest, technical feedback on the landing page. Specifically:

Does the value prop land in the first 5 seconds, or do you bounce?
Is the pricing page clear, or does anything feel sketchy?
What's the dumbest thing you'd remove?

The free tier needs no signup, so testing the actual planner costs nothing.

Also genuinely curious — anyone else here building without being a "real" developer? How do you handle the fear of imposter syndrome at 11pm when something breaks in production?

Cheers from a small town in Lincolnshire 🙏

🔗 https://fairtime.net