DEV Community: Mitrasish

Astro vs Next.js SEO: Core Web Vitals and the Catch

Mitrasish — Thu, 09 Jul 2026 20:30:00 +0000

Originally published on the Lyra blog.

Astro vs Next.js SEO comes down to one variable neither framework can dodge: how much JavaScript reaches the browser before your Core Web Vitals scores lock in. Get that variable right and canonicals, sitemaps, and structured data are a solved problem in both frameworks. Get it wrong and no amount of metadata tuning saves a slow page.

Astro vs Next.js SEO: the short answer

Astro wins Core Web Vitals by default for a content-only blog: its islands architecture ships no JavaScript unless a component asks for it, so Largest Contentful Paint (LCP) and Interaction to Next Paint (INP) start clean without any tuning. Next.js's App Router closes most of that gap with Server Components and streaming, and pulls ahead the moment the site needs auth, a dashboard, or per-user content sitting next to the blog.

Neither answer is universal, and that is the actual decision repo-based blog owners face. A marketing site with a blog bolted on has different constraints than a SaaS product with a blog living inside the same app as the dashboard. The rest of this post works through why JavaScript weight drives the scores, where each framework earns its keep, and how to keep the SEO fundamentals airtight regardless of which one you pick.

Why JavaScript weight moves Core Web Vitals in the first place

Every kilobyte of JavaScript the browser downloads, parses, and executes competes with the work of painting your content and responding to a click. A framework's default JavaScript footprint is not a cosmetic detail; it is the single biggest lever most sites have over their Core Web Vitals scores, ahead of image optimization, font loading, or CDN choice.

That lever matters because most sites are still failing the test. The 2025 Web Almanac measured that only 48% of websites achieve "good" Core Web Vitals on mobile and 56% on desktop, against the standard thresholds of LCP at or under 2.5 seconds, INP at or under 200 milliseconds, and Cumulative Layout Shift (CLS) at or under 0.1. Just over half the web clears the bar on desktop; fewer than half do on mobile, where JavaScript's cost in parse and execution time is highest.

LCP, CLS, and INP: what each one actually measures

LCP measures how long it takes the largest visible element, usually a hero image or the main heading, to render. CLS measures how much visible content shifts unexpectedly after it first appears, the classic case being an ad or image that loads late and pushes the text you were reading down the page. INP measures how quickly the page responds to a user's interaction, replacing the older First Input Delay metric with a measure that covers the full interaction, not just the first one.

All three are sensitive to JavaScript in different ways. A large JS bundle delays LCP because the main thread is busy parsing and executing instead of painting. It hurts CLS when late-loading scripts inject content into a page that already rendered without reserving space for it. It hurts INP directly: a busy main thread cannot respond to a click until it finishes whatever JavaScript task it is already running.

Astro's zero-JS-by-default model (islands architecture)

Astro's core mechanism is the islands architecture: every UI component renders to static HTML and CSS by default, with all client-side JavaScript stripped out automatically. Interactivity is opt-in per component through a client:* directive, so a comment widget or a search box ships its own JavaScript while the surrounding article, headings, and images ship none.

Astro's own documentation is direct about the reasoning: "This avoids the monolithic JavaScript payloads that slow down the responsiveness of many other, modern JavaScript web frameworks." For a blog post with no interactive elements at all, that means the page can ship effectively zero JavaScript and still render the full page, images included, which is why Astro's default Core Web Vitals scores for content sites are hard to beat without deliberate effort in another framework.

Where Next.js's JS weight comes from, and how streaming/RSC cuts it

The reputation Next.js has for heavier pages comes from its Pages Router era and from React apps in general, where every component, including static ones, shipped as client-side JavaScript to be hydrated in the browser. The App Router changes the default: pages are Server Components unless marked otherwise, and Server Components render on the server with their code and dependencies never sent to the client at all. A blog post with no interactive widgets can be built entirely of Server Components and ship no more JavaScript than an equivalent Astro page.

Streaming is the other half of the story. The App Router streams HTML in chunks aligned to <Suspense> boundaries instead of waiting for every data fetch to resolve before sending anything. Next.js's own guidance is blunt about the alternative: "Without streaming, the server waits for all data before sending any HTML, so TTFB equals the slowest query. With streaming, the server sends the static shell as soon as it's ready." That static shell, your layout, navigation, and fallback content, paints immediately, and Next.js's own advice is to keep the LCP element (a hero image or the main heading) outside any Suspense boundary so it renders in that shell rather than waiting on a slow fetch.

Streaming also improves INP through selective hydration: each Suspense boundary hydrates independently, so React can prioritize hydrating whatever section the user is actually touching instead of blocking on the whole page in one pass. None of this is theoretical. Frigade's own case study moved a client-rendered Pages Router site to Server Components on the App Router. Bundle size dropped 62%. Speed Index, measured with Pingdom Speedtest and PageSpeed Insights, came in 63% faster. That gap did not come from a framework limitation; it came from an architecture the App Router was built to fix.

When Astro's zero-JS approach wins

Content-first blogs, docs, and marketing sites

If the site is mostly text, images, and links, with a handful of interactive widgets at most, Astro's default gets you a fast, low-JavaScript page without having to think about it. This is Vercel's own framing too, and Vercel maintains Next.js, so it has no reason to undersell Astro: Vercel's comparison recommends Astro for "purely static content sites," naming blogs, documentation portals, marketing sites, and portfolios specifically, and describes its strength as shipping "minimal client-side JavaScript" with "isolated interactivity" for the few components that need it, like a search bar or a signup form.

That is the profile of most repo-based blogs: a founder or a small team publishing posts as Markdown files, with a comment widget or a newsletter signup at most for interactivity. For that shape of site, reaching for Astro is not a performance hack, it is matching the tool to the job.

When Next.js's weight is worth it

Auth, dashboards, and personalization at scale

The moment the site is not just a blog, when the same repo also serves a logged-in dashboard, a checkout flow, or content that varies per user, Next.js's App Router earns its extra weight. Server Actions let a form submission run a mutation on the server. The caching and revalidation system then returns updated data and re-rendered UI in a single round trip, commonly gated behind an auth() check inside the action itself.

Astro does not compete on this ground by design. Astro has no official first-party authentication solution; auth runs through community integrations or third-party providers like Supabase, Firebase, or Better Auth, wired up through Astro's middleware and context.locals. That works, but it is assembled, not built in. Vercel's own comparison puts it plainly: Next.js is "the better choice" for "SaaS dashboards, collaborative tools, marketplaces, and commerce apps where every route involves server-side logic and user-specific data," and frames it as "the safer starting point" for a site that might grow from static content into app-like interactivity, since that growth does not require a framework migration.

Astro's server islands: personalization without going full-app

Astro's answer to that gap is narrower but real. Server Islands, enabled with a server:defer directive, let a mostly-static page render instantly with fallback content while one specific dynamic or personalized component, a logged-in user's avatar, say, fetches and streams in separately, without making the rest of the page dynamic.

That closes a meaningful slice of the personalization gap without adopting Next.js's full application model: a content site can show "Welcome back, Alex" in the corner while the article itself stays static and fast. It does not give Astro Server Actions, a first-party auth story, or the caching and revalidation system Next.js builds mutations around. For a blog with one personalized widget, Server Islands are usually enough. For an app where most routes need session state, Next.js is still the more direct route.

Build speed: does it actually matter for a blog-sized repo

Build time comes up in every framework debate, and for a blog-sized repo, it should not decide anything. Both frameworks statically generate content at build time, Astro by default, Next.js through generateStaticParams in the App Router, and a repo with a few hundred Markdown posts builds in well under a couple of minutes on either one. The variable that actually separates them is runtime JavaScript weight, not the minutes your CI spends building the site. If build time is the deciding factor in your framework choice, that is usually a sign the real question, how much JavaScript ships to readers, has not been asked yet.

Keeping SEO airtight in either framework

Whichever framework you pick, the technical SEO fundamentals do not change: a self-referencing canonical, a sitemap that reflects your actual URLs, and structured data that validates. Both frameworks handle all three; the mechanics just differ.

Metadata, canonicals, and sitemaps (generateMetadata vs @astrojs/sitemap)

In the Next.js App Router, each page's metadata, including its canonical URL, comes from generateMetadata, and sitemap.ts generates the sitemap, with a generateSitemaps function available to split output once you approach Google's cap of 50,000 URLs per sitemap file. These are Route Handlers, so they are cached by default. If you want that correctness enforced automatically rather than eyeballed per PR, our GitHub Actions SEO checks post covers a CI job that parses the built HTML for a missing canonical or a mismatch before merge.

Astro's equivalent is the @astrojs/sitemap integration, which generates sitemap-index.xml and sitemap-0.xml at build time once you set the site option in astro.config. The one gap worth knowing up front: it cannot generate sitemap entries for dynamic routes when the site runs in SSR mode, which matters if you lean on Server Islands for personalized routes alongside a mostly-static blog.

Structured data and robots files

Neither framework does anything magic here; both just give you a place to put the JSON-LD and the robots directives correctly. Next.js's robots.ts and sitemap.ts file conventions and Astro's config-driven equivalents both compile to the same static output Google reads. The mistake that actually costs rankings is not a framework limitation, it is a malformed JSON-LD block or a canonical pointing at the wrong URL shipping quietly because nobody checked the built HTML before merge.

A decision checklist for a repo-based blog choosing between them

If your repo is...	Lean toward
A blog, docs site, or marketing site with no logged-in area	Astro
A blog that will always stay separate from any app/dashboard	Astro
A blog living inside a product repo that already has auth, a dashboard, or Server Actions	Next.js
Planning to add personalization, checkout, or user accounts later	Next.js
Only need one or two personalized widgets on otherwise static pages	Either: Astro Server Islands or Next.js Suspense both cover this
Migrating an existing Next.js app and adding a blog to it	Next.js, don't split frameworks for one section

We ran this exact checklist on our own site. Trylyra.ai is a marketing page plus a blog with no auth and no dashboard, the textbook case for Astro. We built it on Next.js's App Router anyway, because the same repo also needs to grow into the product dashboard later, and splitting frameworks for one section was not worth maintaining two build pipelines for a team our size. That is the trade-off this checklist is for: it is not always the framework with the better default score, it is the one that matches what the rest of your repo already is.

If none of the app-like requirements apply, default to Astro and take the Core Web Vitals win with less engineering effort. If the blog shares a repo with a product that already needs auth or a dashboard, Next.js's App Router gets you comparable scores with one codebase instead of two. Either way, the framework choice is a one-time decision your SEO strategy does not depend on nearly as much as the discipline you bring to canonicals, sitemaps, and shipping verified content on top of it.

For teams whose blog already lives in one of these repos and just needs posts written and reviewed without babysitting the frontmatter, that is the exact slot our AI blog writer for developers is built for: it reads your repo, drafts in your voice, and opens a pull request against whichever framework you picked. If you want to see how that looks against your own stack, request early access and tell us which of the two you are on. The workflow is the same either way, a Git-based AI blog writer commits a .md file to a branch and opens a PR, since neither Astro nor Next.js changes what a reviewable diff looks like.

I'm building Lyra, an autonomous blog writer that writes in your blog's voice, fact-checks every claim, and opens a pull request you review. This post comes from her blog, where we publish what we learn running the pipeline. Happy to answer questions in the comments.

llms.txt: what it is and how to add one

Mitrasish — Tue, 07 Jul 2026 20:30:00 +0000

Originally published on the Lyra blog.

An llms.txt file is a plain Markdown file you host at /llms.txt that hands AI crawlers a clean, curated map of your site's most important pages. It is not styled for people. It is a shortlist a language model can read in one pass: your site name, a one-paragraph summary, and a few sections of links with short descriptions. The idea, proposed by Jeremy Howard in 2024, is simple. Models work better with context than with raw HTML, so give them the context directly.

This guide covers what goes in an llms.txt file, whether it actually moves the needle, how it differs from robots.txt and a sitemap, and how to write and host one in a few minutes.

What is llms.txt and what goes in it?

llms.txt is a Markdown file at the root of your domain that points AI models at the pages that matter, with a sentence of context on each. A browser will render it as text. A model reading it gets a quick, structured sense of what your site is and where the good parts live, without crawling and parsing every page first.

The format is loose but conventional. A well-formed file has four parts:

An H1 with the name of your site or project. This is the only required line.
A blockquote summary: two or three sentences on what the site is and who it serves.
Optional free-text notes under the summary for anything a model should know up front.
H2 sections of links, each link followed by a short description after a colon.

Because it is just Markdown, it reads the same way structured content reads to a model: predictable headings, plain prose, no markup noise. That predictability is the point. The same instinct drives good answer engine optimization: answer the question plainly, structure it cleanly, and machine readers pick it up. An llms.txt file applies that thinking at the level of your whole site instead of a single page.

It pairs with the technical hygiene that already helps you rank. If you have worked through SEO for SaaS, an llms.txt file is a small, fast addition to that same checklist, not a replacement for it.

Does llms.txt actually help?

Honest answer: it is an emerging convention, not a ranking guarantee. No major AI provider has publicly confirmed that an llms.txt file changes how they rank, retrieve, or cite your pages. Adoption among the big crawlers is still uneven, and some teams treat it with healthy skepticism for exactly that reason.

So why add one? A few reasons that hold up even without a confirmed ranking benefit:

It is cheap. Writing one takes minutes. Maintaining it means editing a text file when you ship or retire a major page. There is no infrastructure and no ongoing cost.
It removes ambiguity. A curated shortlist with descriptions is easier for any model to parse than a 200-page sitemap or a wall of rendered HTML. You are doing the summarizing instead of hoping the crawler gets it right.
It is a signal. Shipping one says you think about machine readers as an audience. That mindset, more than the file itself, is what helps you show up in AI answers.

Treat it the way you would treat clean structured data or a tidy sitemap: good practice with a low ceiling on downside, not a magic lever. The win is not the file alone. It is the habit of writing for both people and the models that increasingly sit between people and your site. The same logic is why we fact-check every claim and link in a post before it ships: if a model is going to cite you, the page it cites had better be accurate and easy to read.

If you want to see a live one, Lyra serves her own at trylyra.ai/llms.txt. It is a small, real example of the format described here.

How is llms.txt different from robots.txt and sitemap.xml?

They live in the same place and they all talk to crawlers, but they do different jobs. Mixing them up is the most common confusion, so here is the split.

File	What it does	Who it is for
`robots.txt`	Sets rules: which paths crawlers may or may not access.	Crawlers deciding what to fetch.
`sitemap.xml`	Lists every URL so crawlers can discover them all.	Search engines indexing the full site.
`llms.txt`	Curates your best pages with plain-language descriptions.	Language models that want context fast.

A sitemap is exhaustive. It wants to list everything. An llms.txt file is the opposite: it is opinionated and short, a highlight reel of the pages you would actually want an AI to read and quote. robots.txt is about permission, not content: it decides which crawlers may read you, and getting the AI crawler rules right is its own job, because blocking the wrong bot quietly deletes you from AI answers. None of the three replaces the others. You can and usually should have all three.

One nuance worth keeping straight. Some teams also publish full-text versions of pages at paths like page.md or an llms-full.txt that inlines whole documents. That is an extension, not a requirement. The core llms.txt file is just the map.

How do I write an llms.txt file?

Start with the pages you would hand a new hire on day one. Your homepage, your core product or pricing pages, your docs, and a handful of your strongest blog posts. Skip thin pages, duplicates, and anything expired. Quality over coverage. A model gets more from 15 well-described links than from 150 bare URLs. Your docs pages deserve the same scrutiny as the rest of the list: they carry the highest concentration of AI agent traffic on most sites, so getting them structured for docs SEO matters at least as much as which links make the file.

Then write the file. Here is a minimal example you can adapt:

# Acme Analytics

> Acme Analytics is a privacy-first product analytics tool for small SaaS
> teams. We help founders see which features drive retention without
> shipping user data to third parties.

Self-serve, no credit card to start. Docs are public and versioned.

## Product

- [Overview](https://acme.com/): What Acme does and who it is for.
- [Pricing](https://acme.com/pricing/): Plans, limits, and the free tier.
- [Integrations](https://acme.com/integrations/): Supported sources and SDKs.

## Docs

- [Quickstart](https://acme.com/docs/quickstart/): Install and send your first event.
- [API reference](https://acme.com/docs/api/): Endpoints, auth, and rate limits.

## Blog

- [Retention metrics that matter](https://acme.com/blog/retention/): The four numbers we track.
- [Self-hosting Acme](https://acme.com/blog/self-host/): Run it on your own infra.

A few rules that keep it useful:

Use absolute URLs. A model may read the file out of context, so relative paths can break.
Write descriptions, not labels. "Pricing: plans, limits, and the free tier" tells a model more than "Pricing" alone.
Keep the summary specific. Say what you do and who you serve. Skip the marketing adjectives.
Stay current. When you ship or kill a major page, update the file. A stale map is worse than none.

How do I host it at /llms.txt?

The file has to resolve at your domain root, at https://yourdomain.com/llms.txt, and return plain text or Markdown. How you get it there depends on your stack.

Static sites: drop llms.txt in your public/ or root output directory. Most static hosts serve it as-is.
Next.js, Astro, and similar frameworks: put it in the public/static folder, or add a route that returns the text with a text/plain or text/markdown content type.
A CMS or platform you do not control: check whether it lets you add a root-level file or a custom route. If not, a redirect or edge function can serve it.

Once it is live, open the URL in a browser and confirm you see your raw Markdown, not a 404 and not an HTML page wrapping it. That is the whole job. There is no registry to submit to and no verification step.

Where this fits in your AI search strategy

An llms.txt file is one small piece. It makes your site easy to map. It does not write the pages that make the map worth reading. Those still come from clear, accurate, well-structured content that answers real questions, which is what gets cited whether or not a crawler reads your llms.txt first. The file is a pointer; the pages are the payload.

This is where the work scales or stalls. Maintaining the file is trivial. Producing a steady stream of pages worth pointing to is the hard part, and it is exactly the gap Lyra fills. Lyra is an autonomous writer who finds topics worth covering, drafts them in your blog's existing voice, fact-checks the claims and links, scores the draft, and opens a GitHub pull request for you to review. Nothing publishes on its own. You bring your own Anthropic key, and Lyra is in early access while we build in the open, so talk to the founder to see whether she's a fit. If you want the deeper version of how an autonomous AI blog writer works end to end, the pillar page walks through it.

Add the llms.txt file this afternoon. It is five minutes of work with no real downside. Then spend your energy on the content it points to, because that is what actually earns the citation.

GitHub Actions SEO: gate PRs on broken links and schema

Mitrasish — Sun, 05 Jul 2026 20:30:00 +0000

Originally published on the Lyra blog.

Code review is good at catching logic bugs. SEO bugs are different: a broken canonical does not throw a build error, a dead external link does not fail a type check, and a malformed JSON-LD block does not appear in a diff in any way that signals a problem. They ship quietly. You find out weeks later from Search Console.

The fix is a GitHub Actions SEO workflow that gates every blog PR automatically. Four jobs check broken links, meta and canonical correctness, JSON-LD validity, and a Lighthouse performance budget. The merge button stays red until all four pass.

This is the workflow, job by job.

What a blog PR can ship that code review misses

A code reviewer checking a blog post looks at the prose: is the structure right, does the intro land, are the claims defensible? Nobody in that review is clicking every external link, validating the canonical, or running the new hero image through a performance budget. Those checks are not part of the review process. CI makes them automatic.

Broken external links nobody clicked during editorial review

External links rot. A link that resolved when the author found the source may have moved, renamed, or 404ed by the time the post ships. Nobody in editorial review clicks every citation in a 2,000-word post. A CI job does.

A missing or self-conflicting canonical that splits your ranking signal

The canonical tag tells Google which URL to credit when the same or similar content appears at multiple addresses. In a Next.js App Router site, pages generate their canonical via generateMetadata. The common failure mode is a page that inherits a canonical from a parent layout instead of setting its own, producing a post whose canonical points at /blog/ rather than /blog/your-post-slug/. Astro's sitemap integration has its own version of this failure mode, covered in our Astro vs Next.js SEO comparison, so the check below is worth adapting rather than skipping if you are on Astro instead.

The page renders without error, silently sending its ranking signal to the wrong URL.

Malformed JSON-LD that silently forfeits rich-result eligibility

Nestlé measured that pages appearing as rich results in Google Search have an 82% higher click-through rate than non-rich-result pages, a figure cited in Google's structured data documentation. A Milestone Internet study of 4.5 million queries measured 58 clicks per 100 queries for rich results against 41 for standard results. A single malformed property in the JSON-LD block, a date string in the wrong format, or a missing required field silently disqualifies the page from rich-result consideration. The structured data is rendered in the HTML; it just does not validate.

Lighthouse runs around 8 automated SEO audits per page, and none of them validate JSON-LD content. A separate validation step closes that gap.

A new hero image that blows your Lighthouse budget

Google's Core Web Vitals thresholds are LCP under 2.5 seconds, CLS under 0.1, and INP under 200 milliseconds. Roughly half of all tracked origins pass all three, per 2025 Web Almanac data, with desktop (56%) outperforming mobile (48%).

A PR that adds a 3MB PNG where a 200KB WebP should be can push LCP over threshold, but the build succeeds and the post looks fine locally. The regression only surfaces in Search Console weeks later.

The GitHub Actions SEO workflow: four checks, one file

All four jobs live in .github/workflows/blog-seo.yml. The workflow triggers on pull requests that change files in content/blog/, so it only runs when content changes:

name: Blog SEO checks

on:
  pull_request:
    paths:
      - 'content/blog/**'
      - '.github/workflows/blog-seo.yml'

Job 1: broken links - lychee-action scans Markdown files before the build

lychee-action wraps lychee, a link checker written in Rust. The lychee project benchmarks it at 576 links in about 60 seconds on the analysis-tools-dev/static-analysis repository; throughput varies by repo size and link distribution, but most blogs with a few dozen posts complete in well under two minutes. It reads Markdown files directly and does not require a running server, so it can complete before any build step.

jobs:
  broken-links:
    name: Broken links
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Check links
        uses: lycheeverse/lychee-action@v2
        with:
          args: --verbose --no-progress 'content/blog/**/*.md'
          fail: true
          jobSummary: true

fail: true exits with a non-zero code on any broken link, which fails the job. jobSummary: true writes the full report to the GitHub Actions job summary, accessible from the PR's check status.

Add a .lycheeignore at the repo root for URLs to exclude, one regex per line:

# Localhost references in code blocks
http://localhost
# Web archive links
https://web.archive.org

Job 2: meta, canonical, and OG tags - parse built HTML after next build

There is no off-the-shelf action for meta-tag validation on a Next.js App Router site, so this job builds the site and runs a short Node script against the HTML output. The script checks each page for a <meta name="description">, a <link rel="canonical"> that matches the page's own URL, and basic Open Graph tags.

After validating, the job uploads the build as an artifact. The JSON-LD and Lighthouse jobs download it instead of rebuilding, so all three validate the same output and CI time does not multiply with each additional check:

  meta-tags:
    name: Meta and canonical tags
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v6
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Cache Next.js build
        uses: actions/cache@v6
        with:
          path: .next/cache
          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}

      - name: Build
        run: npx next build
        env:
          NODE_ENV: production

      - name: Check meta and canonical tags
        run: node scripts/check-meta.mjs

      - name: Upload build artifact
        uses: actions/upload-artifact@v7
        with:
          name: next-build
          path: |
            .next/
            public/
          retention-days: 1

Setting process.exitCode = 1 instead of calling process.exit(1) immediately lets the script report every failure across all pages in a single run rather than stopping at the first hit. Create scripts/check-meta.mjs in your repo:

// scripts/check-meta.mjs
import { readdir, readFile } from 'node:fs/promises';
import { join, resolve } from 'node:path';

const SITE_URL = process.env.SITE_URL ?? 'https://yoursite.com';
const BLOG_DIR = resolve('.next/server/app/blog');

async function walk(dir) {
  const entries = await readdir(dir, { withFileTypes: true });
  const files = [];
  for (const entry of entries) {
    const full = join(dir, entry.name);
    if (entry.isDirectory()) {
      files.push(...await walk(full));
    } else if (entry.name === 'page.html') {
      files.push(full);
    }
  }
  return files;
}

async function checkPage(htmlPath) {
  const slug = htmlPath.replace(BLOG_DIR + '/', '').replace('/page.html', '');
  const html = await readFile(htmlPath, 'utf8');
  const expectedUrl = `${SITE_URL}/blog/${slug}/`;
  let ok = true;

  const description =
    html.match(/<meta[^>]+name="description"[^>]+content="([^"]+)"/i)?.[1] ??
    html.match(/<meta[^>]+content="([^"]+)"[^>]+name="description"/i)?.[1] ??
    null;

  if (!description) {
    console.error(`[FAIL] Missing meta description: /blog/${slug}/`);
    process.exitCode = 1;
    ok = false;
  }

  const canonical =
    html.match(/<link[^>]+rel="canonical"[^>]+href="([^"]+)"/i)?.[1] ??
    html.match(/<link[^>]+href="([^"]+)"[^>]+rel="canonical"/i)?.[1] ??
    null;

  if (!canonical || canonical !== expectedUrl) {
    console.error(`[FAIL] Canonical mismatch: /blog/${slug}/`);
    console.error(`  Expected: ${expectedUrl}`);
    console.error(`  Found:    ${canonical ?? 'missing'}`);
    process.exitCode = 1;
    ok = false;
  }

  const ogTitle =
    html.match(/<meta[^>]+property="og:title"[^>]+content="([^"]+)"/i)?.[1] ??
    html.match(/<meta[^>]+content="([^"]+)"[^>]+property="og:title"/i)?.[1] ??
    null;

  if (!ogTitle) {
    console.error(`[FAIL] Missing og:title: /blog/${slug}/`);
    process.exitCode = 1;
    ok = false;
  }

  if (ok) console.log(`[OK]   /blog/${slug}/`);
}

const files = await walk(BLOG_DIR).catch(() => []);

if (files.length === 0) {
  console.error('[FAIL] No HTML found in .next/server/app/blog - run next build first');
  process.exitCode = 1;
} else {
  await Promise.all(files.map(checkPage));
}

walk recurses the App Router build directory and collects every page.html file. Next.js 15 App Router writes pre-rendered pages to .next/server/app/blog/<slug>/page.html, so the slug is extracted directly from the path. checkPage reads each file, runs all three checks without short-circuiting, and logs every failure before the process exits. Set SITE_URL via the environment (or hardcode your domain) to match the canonical your generateMetadata produces.

Job 3: JSON-LD linting - schemar posts pass/fail results as a sticky PR comment

Schemar (johnnyreilly/schemar) wraps the Schema Markup Validator. It accepts a list of URLs, checks the JSON-LD on each against Schema.org's rules, and returns pass/fail results. Combine it with marocchino/sticky-pull-request-comment to keep the validation output as a single updating comment on the PR rather than a new comment on every push.

This job downloads the build artifact from the meta-tags job rather than rebuilding from scratch. The needs: meta-tags dependency controls ordering; the artifact carries the actual output.

The job also needs the slug of the post being reviewed. Rather than hardcoding it, a get-slug step extracts the filename from the git diff - the slug is just the new .md filename in content/blog/ with its extension stripped:

  json-ld:
    name: JSON-LD validation
    runs-on: ubuntu-latest
    needs: meta-tags
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v6
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Download build artifact
        uses: actions/download-artifact@v8
        with:
          name: next-build

      - name: Get new post slug
        id: slug
        run: |
          git fetch origin ${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}
          SLUG=$(git diff --name-only origin/${{ github.base_ref }}..HEAD \
            -- 'content/blog/' | grep '\.md$' | head -1 \
            | sed 's|content/blog/||; s|\.md$||')
          echo "slug=${SLUG}" >> $GITHUB_OUTPUT

      - name: Start preview server
        run: npx next start &

      - name: Wait for server
        run: npx wait-on http://localhost:3000

      - name: Validate JSON-LD
        id: schemar
        uses: johnnyreilly/schemar@v0.1.1
        with:
          urls: "http://localhost:3000/blog/${{ steps.slug.outputs.slug }}/"

      - name: Format results as markdown
        id: format
        if: always()
        uses: actions/github-script@v9
        with:
          script: |
            const results = ${{ steps.schemar.outputs.results }};
            const lines = results.map((r) =>
              `${r.processedValidationResult.success ? '🟢' : '🔴'} ${r.url}: ${r.processedValidationResult.resultText}`
            );
            core.setOutput('comment', ['### JSON-LD validation', ...lines].join('\n'));

      - name: Post results as sticky PR comment
        uses: marocchino/sticky-pull-request-comment@v3
        with:
          header: json-ld-validation
          message: ${{ steps.format.outputs.comment }}

The fetch line writes an explicit refspec, origin/${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}, instead of a bare git fetch origin main. actions/checkout@v7 defaults to a shallow, single-branch clone of the PR head, so a bare fetch only populates FETCH_HEAD and leaves no local origin/main ref for the diff to compare against. The explicit refspec creates that ref directly.

It still is not enough on its own. actions/checkout@v7's default depth-1 clone fetches only the PR head commit, with no shared history to main in the local repository, so origin/main and HEAD have no common ancestor that git can find locally. A three-dot diff (origin/main...HEAD), which compares against the merge base, fails with fatal: no merge base in that state. The two-dot form above (origin/main..HEAD) compares the two tips directly and does not need one, so it works regardless of the checkout's fetch depth.

The header param on the sticky comment means each new push overwrites the previous result in place. The PR timeline stays clean.

Schemar's results output is Result[], a JSON array, not pre-formatted markdown: each entry carries a url and a processedValidationResult object with success and resultText fields, confirmed in schemar's action.yml. Passing that array straight to message posts raw JSON on the PR. The actions/github-script step in between maps each result to a one-line pass/fail row before it reaches the sticky comment, which is the same shape johnnyreilly's own writeup of the action uses for its PR comments.

Job 4: Lighthouse budget - serve the build locally, assert on LCP, CLS, and INP

treosh/lighthouse-ci-action runs Lighthouse CI against a locally served build and fails the job when any assertion falls below threshold.

Like the JSON-LD job, this downloads the artifact rather than running another build. It also uses the same get-slug step to discover the post URL from the diff, then generates .lighthouserc.json on the fly so no file needs manual editing per PR:

  lighthouse:
    name: Lighthouse budget
    runs-on: ubuntu-latest
    needs: meta-tags
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v6
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci

      - name: Download build artifact
        uses: actions/download-artifact@v8
        with:
          name: next-build

      - name: Get new post slug
        id: slug
        run: |
          git fetch origin ${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}
          SLUG=$(git diff --name-only origin/${{ github.base_ref }}..HEAD \
            -- 'content/blog/' | grep '\.md$' | head -1 \
            | sed 's|content/blog/||; s|\.md$||')
          echo "slug=${SLUG}" >> $GITHUB_OUTPUT

      - name: Generate .lighthouserc.json
        run: |
          cat > .lighthouserc.json << EOF
          {
            "ci": {
              "collect": {
                "url": ["http://localhost:3000/blog/${{ steps.slug.outputs.slug }}/"],
                "startServerCommand": "npx next start",
                "startServerReadyPattern": "started server"
              },
              "assert": {
                "assertions": {
                  "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
                  "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
                  "total-blocking-time": ["warn", { "maxNumericValue": 300 }]
                }
              }
            }
          }
          EOF

      - name: Run Lighthouse CI
        uses: treosh/lighthouse-ci-action@v12
        with:
          uploadArtifacts: true
          temporaryPublicStorage: true
          configPath: .lighthouserc.json

The Generate .lighthouserc.json step uses a heredoc where ${{ steps.slug.outputs.slug }} is substituted by the Actions runner before the shell executes - so the generated file contains the literal slug, not a variable reference. LCP under 2500ms and CLS under 0.1 are Google's passing thresholds. Using "error" rather than "warn" is what causes the job to fail. Total blocking time is the closest lab-measurable proxy for INP; "warn" surfaces problems without blocking the merge on what is an approximation of a field metric. Tighten or relax as the site's performance baseline becomes clearer.

Wiring it into the PR so the merge button stays red

The four jobs above produce check runs on every PR. By default, GitHub does not prevent merging when a check fails. One configuration step makes them binding.

Required status checks in branch protection - the one setting that makes everything above binding

Go to repository Settings, then Branches. Add a branch protection rule for the branch content merges into, typically main. Under "Require status checks to pass before merging", add all four job names:

Broken links
Meta and canonical tags
JSON-LD validation
Lighthouse budget

With these set as required, the merge button stays disabled until all four pass. A single failure keeps the PR locked regardless of approvals. The same branch protection rule is also what stops any GitHub App, including a well-behaved AI writer, from pushing straight to main: it forces a Contents-write token through this exact PR path, which is worth checking alongside the app's actual permission grant.

Without this step, the entire setup is advisory: the checks run and report, but nothing actually blocks the merge. This is the step most workflow tutorials omit.

Surfacing failures inline with sticky PR comments

The Schemar job's sticky comment puts JSON-LD results directly on the PR without navigating to the Actions run page. For the other three jobs, the GitHub job summary (via jobSummary: true on lychee, and console output on the meta-tag script) provides the detailed report accessible from each check status link.

Make the meta-tag script output specific enough to act on immediately:

[FAIL] Missing meta description: /blog/new-post-slug/
[FAIL] Canonical mismatch: /blog/new-post-slug/
  Expected: https://yoursite.com/blog/new-post-slug/
  Found:    https://yoursite.com/blog/

Keeping it zero-maintenance: .lycheeignore, pinned action versions, and caching the build

Three habits prevent the workflow from becoming a source of noise.

Pin action versions to major version tags (@v2, @v7, @v12). Moving tags like @latest break without warning when upstream ships a breaking change. Check release pages when onboarding a new action; marocchino/sticky-pull-request-comment is at v3, for example.
Share the build output. The cache step in the meta-tags job preserves .next/cache between workflow runs, and the artifact upload carries the final output to the JSON-LD and Lighthouse jobs - one build per PR, three jobs consuming it.
Keep .lycheeignore current. As the blog grows, more code-block URLs and archived-page references need exclusion. A stale file generates false failures that train the team to dismiss CI output; update it when adding an exclusion-worthy URL.

Where the green check ends and editorial judgment begins

What four passing jobs actually confirm - and what they cannot

A green run confirms:

No external link in the PR's Markdown files returns a 4xx or 5xx response
Every generated page has a meta description, a self-referencing canonical, and Open Graph tags
The structured data on the new post validates against Schema.org
The new post clears Core Web Vitals thresholds under lab conditions

What it does not confirm: whether the facts are correct, whether the post answers the question it sets up, or whether the prose is worth reading. CI has no opinion about those things.

This is the same division that makes automated content creation work without creating editorial risk: automate every check that has a clear pass/fail definition, leave judgment to people with context.

The split that works: CI owns technical correctness, humans own voice and facts

When a PR reaches human review with all four checks green, the reviewer does not need to wonder whether the canonical is pointing at itself or whether the link to the case study still resolves. CI answered those questions. The reviewer can focus on what CI cannot check: accuracy, voice, and whether the post actually serves the reader.

Combined with an earlier fact-checking step, Lyra verifies claims and links before opening the PR, CI gates the technical surface, and human review handles editorial judgment. All three pass before the post ships.

For teams using a PR-based AI blog writer where an agent produces the first draft, the CI gate is especially useful. The agent drafts fast, the checks run in parallel, and the reviewer sees a PR already validated on both the technical and factual axes. Internal linking automation also benefits directly: the broken-link job confirms that any new cross-links added to a post actually resolve before they ship.