The Hidden SEO Bug in My Next.js Portfolio (and How I Fixed It)
My portfolio looked fine from the outside. It had a sitemap, a robots file, an RSS feed, share images and a tidy title template. But when I sat down to audit its SEO properly, I found one line in the root layout that was quietly telling Google that almost every page on the site was a copy of the homepage.
This post walks through that bug, why it happens in the Next.js App Router, and the small set of fixes I applied afterwards.
The Bug: An Inherited Canonical URL
A canonical URL tells search engines "this is the original address of this page." It's how you avoid duplicate-content problems when the same content is reachable at more than one URL.
In my root layout, I had set the canonical to the homepage, along with the Open Graph URL:
// app/layout.tsx
export const metadata = {
metadataBase: new URL(site.url),
alternates: { canonical: "/" },
openGraph: { url: "/", /* ... */ },
};
That looks harmless. It's the homepage's canonical, after all. The problem is that metadata in the App Router is inherited. Any page that doesn't define its own alternates keeps the layout's. So my About page, Contact page, every project and every service page all rendered this:
<link rel="canonical" href="https://example.com/" />
From Google's point of view, those pages were declaring themselves duplicates of the homepage. The likely outcome is that they get dropped from search results, and Search Console reports them as "Duplicate, Google chose different canonical." Only the few pages that happened to set their own canonical, like the blog, were safe.
The Second Gotcha: Shallow Merging
The obvious fix is to give every page its own canonical. But there's a related trap. Metadata is merged shallowly, one top-level key at a time. If a page sets openGraph, it doesn't add to the layout's openGraph. It replaces it entirely.
// app/page.tsx
export const metadata = {
openGraph: { url: "/" }, // the layout's title, description and siteName are now gone
};
So a "small" override can silently strip the share title and description from a page. The same applies to alternates (setting a canonical drops any RSS link declared alongside it) and twitter.
The Fix: One Helper for Every Page
Instead of remembering all of this on every page, I moved it into a single helper that returns complete metadata for a page:
// lib/seo.ts
export function pageMetadata({ title, description, path }) {
const shareTitle = `${title} — ${site.name}`;
return {
title,
description,
alternates: { canonical: path },
openGraph: {
type: "website",
siteName: site.name,
locale: "en_US",
title: shareTitle,
description,
url: path,
},
twitter: { card: "summary_large_image", title: shareTitle, description },
};
}
Every page now uses it, both static and dynamic:
// app/about/page.tsx
export const metadata = pageMetadata({
title: "About",
description: "Software engineer and content creator...",
path: "/about",
});
// app/projects/[slug]/page.tsx
export async function generateMetadata({ params }) {
const { slug } = await params;
const project = await getProject(slug);
return pageMetadata({
title: project?.title ?? "Project",
description: project?.summary,
path: `/projects/${slug}`,
});
}
The root layout no longer sets a canonical at all. The homepage declares its own "/", so nothing can inherit it by accident.
Share Images Need the Same Care
File-based opengraph-image.tsx routes are a great feature. They generate a share card per route segment. But a page that defines its own openGraph no longer picks up its parent's image. Once every page used the helper, each section needed its own opengraph-image.tsx.
That sounds like a lot of files, but they're tiny because they all call one shared renderer:
// app/services/[slug]/opengraph-image.tsx
export default async function Image({ params }) {
const { slug } = await params;
const service = await getService(slug);
return renderOgImage({
eyebrow: "Services",
title: service?.title ?? "Service not found",
subtitle: service?.summary,
});
}
Now a shared link to a service shows that service's name, not a generic site card.
Structured Data: Telling Google Who You Are
For a personal site, the single most useful piece of structured data is a Person entry on the homepage. Its sameAs field links your name to your profiles elsewhere, which helps search engines understand that they all belong to the same person:
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Person",
"@id": "https://example.com/#person",
"name": "Your Name",
"jobTitle": "Software Engineer",
"url": "https://example.com",
"sameAs": ["https://github.com/you", "https://www.linkedin.com/in/you"]
},
{
"@type": "WebSite",
"name": "Your Name",
"url": "https://example.com",
"publisher": { "@id": "https://example.com/#person" }
}
]
}
I generate the sameAs list from the same social links the site already shows, so it can't drift out of date. I also added BreadcrumbList data to pages that show breadcrumbs, so search results can display the page's place in the site.
The Smaller Wins
- Descriptions everywhere. Pages without a meta description let Google pick a snippet, which is often a random fragment of navigation text.
- Sitemap
lastModified. Every entry now carries the content's last edit date, which helps crawlers prioritise what changed. - Optimised images. Switching the header logo to
next/imagewith real dimensions avoids layout shift and oversized downloads. - A complete web manifest. Adding
start_urland adescriptionis a two-line change.
How to Check Your Own Site
- Open a few inner pages, view the source and search for
rel="canonical". Each should point to the page itself, not the homepage. - Check the
og:titleandog:urltags on the same pages. - Run your homepage through Google's Rich Results Test to confirm your structured data is read correctly.
- In Search Console, look at the Page indexing report for "Duplicate, Google chose different canonical."
- Make sure your production site URL is actually configured. If
metadataBasefalls back tolocalhost, every canonical you just fixed points nowhere.
Summary
The App Router's metadata inheritance is convenient, but it cuts both ways. A canonical URL in a root layout is inherited by every page that doesn't override it, and overrides replace whole objects rather than merging them. The fix is simple: keep page-specific fields like canonicals out of layouts, and use one helper that returns complete metadata for each page. Add per-section share images and a Person entry in your structured data, and a portfolio that merely looks SEO-ready actually is.

