@growth-labs/seo 0.5.0 → 0.6.0

package/src/routes/sitemap-pages.ts

@@ -4,8 +4,6 @@ import { getContentProvider } from '../_internal/state.js'
 import type { ContentItem } from '../types.js'
 import { generatePagesSitemap } from '../utils/sitemap.js'
 
-export const prerender = false
-
 export const GET: APIRoute = async (context) => {
 	const contentProvider = getContentProvider()
 

package/src/routes/sitemap-products.ts

@@ -4,8 +4,6 @@ import { getContentProvider } from '../_internal/state.js'
 import type { ContentItem } from '../types.js'
 import { generateProductSitemap } from '../utils/sitemap.js'
 
-export const prerender = false
-
 export const GET: APIRoute = async (context) => {
 	const contentProvider = getContentProvider()
 

package/src/routes/sitemap-videos.ts

@@ -4,8 +4,6 @@ import { getContentProvider } from '../_internal/state.js'
 import type { ContentItem } from '../types.js'
 import { generateVideoSitemap } from '../utils/sitemap.js'
 
-export const prerender = false
-
 export const GET: APIRoute = async (context) => {
 	const contentProvider = getContentProvider()
 

package/src/utils/apple-news-rss.ts

@@ -60,14 +60,17 @@ export function generateAppleNewsRss({
 	}
 
 	const filtered = forAppleNews(items, { publishable: appleNews.defaultPublishable })
-	// Newest-first ordering.
+	// Newest-first ordering. Coerce missing/unparseable dates to 0 (sort last) —
+	// a NaN comparator result makes Array.sort leave the element in place, which
+	// could park a junk-dated item at the front of the capped feed.
+	const publishTime = (value?: string): number => {
+		if (!value) return 0
+		const t = new Date(value).getTime()
+		return Number.isNaN(t) ? 0 : t
+	}
 	const sorted = filtered
 		.slice()
-		.sort((a, b) => {
-			const at = a.datePublished ? new Date(a.datePublished).getTime() : 0
-			const bt = b.datePublished ? new Date(b.datePublished).getTime() : 0
-			return bt - at
-		})
+		.sort((a, b) => publishTime(b.datePublished) - publishTime(a.datePublished))
 		.slice(0, MAX_ITEMS)
 
 	const selfLink = `${options.site.replace(/\/$/, '')}${appleNews.feedPath}`

package/src/utils/rss.ts

@@ -1,6 +1,13 @@
 import type { SeoOptionsWithResolvedSite } from '../options.js'
 import type { ContentItem } from '../types.js'
 
+// RSS is a "recent updates" surface, not a full archive (that's the sitemap).
+// Capping the item count keeps the feed lightweight for readers AND bounds the
+// prerendered /feed.xml asset — an uncapped full-body feed on a large catalog
+// would eventually breach Cloudflare's 25 MiB per-asset limit. Mirrors the
+// Apple News feed cap.
+const RSS_MAX_ITEMS = 50
+
 function escapeXml(str: string): string {
 	return str
 		.replace(/&/g, '&')
@@ -14,6 +21,17 @@ function toRfc822(dateStr: string): string {
 	return new Date(dateStr).toUTCString()
 }
 
+// Parse to epoch ms, coercing missing/unparseable dates to 0 so they sort last.
+// A raw `new Date(bad).getTime()` returns NaN, and a NaN comparator result makes
+// Array.sort leave the element in place — which can park a junk-dated item at the
+// front of the capped feed. Content dates come from hand/LLM-authored frontmatter,
+// so malformed values are realistic.
+function publishTime(value: string | undefined): number {
+	if (!value) return 0
+	const t = new Date(value).getTime()
+	return Number.isNaN(t) ? 0 : t
+}
+
 export function generateRssFeed(
 	items: ContentItem[],
 	options: SeoOptionsWithResolvedSite,
@@ -24,7 +42,12 @@ export function generateRssFeed(
 	const language = defaults.locale.replace('_', '-').toLowerCase()
 	const lastBuildDate = new Date().toUTCString()
 
-	const itemsXml = items
+	// Newest first, then cap. Missing/unparseable dates sort last (time 0).
+	const recentItems = [...items]
+		.sort((a, b) => publishTime(b.datePublished) - publishTime(a.datePublished))
+		.slice(0, RSS_MAX_ITEMS)
+
+	const itemsXml = recentItems
 		.map((item) => {
 			const pubDate = item.datePublished ? toRfc822(item.datePublished) : ''
 			const pubDateTag = pubDate ? `\n      <pubDate>${escapeXml(pubDate)}</pubDate>` : ''

package/src/utils/sitemap.ts

@@ -105,9 +105,11 @@ ${entries}
 
 export function generateVideoSitemap(items: ContentItem[]): string {
 	const entries = items
-		.filter((item) => item.video)
+		.filter((item): item is ContentItem & { video: NonNullable<ContentItem['video']> } =>
+			Boolean(item.video && (item.video.contentUrl || item.video.embedUrl)),
+		)
 		.map((item) => {
-			const v = item.video!
+			const v = item.video
 			const contentUrlTag = v.contentUrl
 				? `\n      <video:content_loc>${escapeXml(v.contentUrl)}</video:content_loc>`
 				: ''

package/src/utils/validation.ts

@@ -7,6 +7,11 @@ export interface PageValidationOptions {
 	titleMaxLength: number
 	descriptionMaxLength: number
 	heroMinWidth?: number
+	pagePath?: string
+	requireH1?: boolean
+	requireHeroImage?: boolean
+	requireArticleSchema?: boolean
+	requireMaxImagePreviewLarge?: boolean
 }
 
 /**
@@ -139,7 +144,7 @@ export function validatePage(html: string, options: PageValidationOptions): Vali
 		html.match(/<meta\s[^>]*property=["']og:image["'][^>]*>/i) ??
 		html.match(/<meta\s[^>]*property=og:image[^>]*>/i)
 	if (!ogImageMatch) {
-		warnings.push('Missing og:image meta tag')
+		pushIssue(options.requireHeroImage, errors, warnings, 'Missing hero image og:image meta tag')
 	}
 
 	// og:image:width check against heroMinWidth
@@ -154,18 +159,27 @@ export function validatePage(html: string, options: PageValidationOptions): Vali
 			if (widthContentMatch) {
 				const width = Number(widthContentMatch[1])
 				if (!Number.isNaN(width) && width < options.heroMinWidth) {
-					warnings.push(`Hero image width ${width}px is below minimum ${options.heroMinWidth}px`)
+					pushIssue(
+						options.requireHeroImage,
+						errors,
+						warnings,
+						`Hero image width ${width}px is below minimum ${options.heroMinWidth}px`,
+					)
 				}
+			} else if (options.requireHeroImage) {
+				errors.push(`Hero image width is missing; minimum is ${options.heroMinWidth}px`)
 			}
+		} else if (options.requireHeroImage && ogImageMatch) {
+			errors.push(`Hero image width is missing; minimum is ${options.heroMinWidth}px`)
 		}
 	}
 
 	// H1 checks
 	const h1Matches = html.match(/<h1[\s>]/gi) ?? []
 	if (h1Matches.length === 0) {
-		warnings.push('Missing H1 tag')
+		pushIssue(options.requireH1, errors, warnings, 'Missing H1 tag')
 	} else if (h1Matches.length > 1) {
-		warnings.push(`Multiple H1 tags found (${h1Matches.length})`)
+		pushIssue(options.requireH1, errors, warnings, `Multiple H1 tags found (${h1Matches.length})`)
 	}
 
 	// JSON-LD presence check
@@ -174,9 +188,110 @@ export function validatePage(html: string, options: PageValidationOptions): Vali
 		warnings.push('Missing JSON-LD structured data')
 	}
 
+	if (
+		options.requireArticleSchema &&
+		isLikelyArticlePath(options.pagePath) &&
+		!hasArticleJsonLd(html)
+	) {
+		errors.push('Missing valid Article JSON-LD for article route')
+	}
+
+	// max-image-preview:large tells search engines to show large image previews
+	// in Discover / News results — meaningful only for INDEXABLE pages. A noindex
+	// page (404, login, account, etc.) is excluded from search entirely, so the
+	// directive is moot there. Requiring it would force every consumer's noindex
+	// layout to carry a contradictory `noindex, ..., max-image-preview:large`
+	// robots string just to satisfy the linter. Skip the check on noindex pages.
+	if (
+		options.requireMaxImagePreviewLarge &&
+		!isNoindexPage(html) &&
+		!hasMaxImagePreviewLarge(html)
+	) {
+		errors.push('Missing robots max-image-preview:large directive')
+	}
+
 	return { errors, warnings }
 }
 
+function pushIssue(
+	asError: boolean | undefined,
+	errors: string[],
+	warnings: string[],
+	message: string,
+) {
+	if (asError) errors.push(message)
+	else warnings.push(message)
+}
+
+function isLikelyArticlePath(pagePath: string | undefined): boolean {
+	if (!pagePath) return false
+	return /\/(article|articles|news|story|stories)\//i.test(pagePath)
+}
+
+function hasArticleJsonLd(html: string): boolean {
+	for (const rawJson of extractJsonLdBodies(html)) {
+		try {
+			const parsed = JSON.parse(rawJson) as unknown
+			if (hasArticleType(parsed)) return true
+		} catch {}
+	}
+	return false
+}
+
+function extractJsonLdBodies(html: string): string[] {
+	const bodies: string[] = []
+	const pattern = /<script\s[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi
+	for (const match of html.matchAll(pattern)) {
+		if (match[1]) bodies.push(match[1].trim())
+	}
+	return bodies
+}
+
+function hasArticleType(value: unknown): boolean {
+	if (Array.isArray(value)) return value.some(hasArticleType)
+	if (!isRecord(value)) return false
+
+	const type = value['@type']
+	if (type === 'Article' || type === 'NewsArticle' || type === 'BlogPosting') return true
+	if (
+		Array.isArray(type) &&
+		type.some((item) => item === 'Article' || item === 'NewsArticle' || item === 'BlogPosting')
+	) {
+		return true
+	}
+
+	return hasArticleType(value['@graph'])
+}
+
+function hasMaxImagePreviewLarge(html: string): boolean {
+	const metaTags = html.match(/<meta\s+[^>]*>/gi) ?? []
+	for (const tag of metaTags) {
+		if (getHtmlAttr(tag, 'name')?.toLowerCase() !== 'robots') continue
+		const content = getHtmlAttr(tag, 'content')?.toLowerCase() ?? ''
+		const directives = content.split(',').map((part) => part.trim())
+		if (directives.includes('max-image-preview:large')) return true
+	}
+	return false
+}
+
+function isNoindexPage(html: string): boolean {
+	const metaTags = html.match(/<meta\s+[^>]*>/gi) ?? []
+	for (const tag of metaTags) {
+		const name = getHtmlAttr(tag, 'name')?.toLowerCase()
+		// Per the robots spec a per-bot directive (e.g. name="googlebot") counts;
+		// `content="none"` is equivalent to `noindex, nofollow`.
+		if (name !== 'robots' && name !== 'googlebot') continue
+		const content = getHtmlAttr(tag, 'content')?.toLowerCase() ?? ''
+		const directives = content.split(',').map((part) => part.trim())
+		if (directives.includes('noindex') || directives.includes('none')) return true
+	}
+	return false
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null
+}
+
 function isNoindexMetaRefreshRedirect(html: string): boolean {
 	const metaTags = html.match(/<meta\s+[^>]*>/gi) ?? []
 	const hasRefresh = metaTags.some(

package/src/virtual.d.ts

@@ -6,3 +6,15 @@ declare module 'virtual:growth-labs/seo/config' {
 	export function getConfig(): ResolvedSeoOptions
 	export function getContentProvider(): ContentProvider | undefined
 }
+
+// Config-only twin: identical surface, but the generated module never imports
+// the consumer's contentProviderModule. Imported by the always-runtime SEO
+// middleware so the content store is not bundled into the deployed Worker.
+declare module 'virtual:growth-labs/seo/config-lite' {
+	import type { ResolvedSeoOptions } from '@growth-labs/seo'
+	import type { ContentProvider } from '@growth-labs/seo'
+
+	export const config: ResolvedSeoOptions
+	export function getConfig(): ResolvedSeoOptions
+	export function getContentProvider(): ContentProvider | undefined
+}

package/src/vite-plugin.ts

@@ -1,9 +1,34 @@
 import type { Plugin } from 'vite'
-import type { ResolvedSeoOptions } from './options.js'
+import { type ResolvedSeoOptions, resolveAeoTwins } from './options.js'
 
 const VIRTUAL_MODULE_ID = 'virtual:growth-labs/seo/config'
 const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`
 
+// Mode-aware twin of the virtual config module, imported by the always-runtime
+// SEO middleware and the head components (SeoHead/AeoHead). It seeds `_setConfig`
+// always, and seeds the contentProvider ONLY in non-static modes:
+//
+//   - STATIC mode (aeoTwins false/'static', no flexibleSampling): provider-free.
+//     The middleware runs in the DEPLOYED Worker on every request; importing the
+//     provider-bearing `config` here would pull the consumer's contentProviderModule
+//     — and transitively `astro:content` plus the whole content store (tens of MB
+//     on a large catalog) — into the runtime Worker, blowing Cloudflare's 10 MB
+//     limit even though the middleware only needs metadata. In static mode the
+//     middleware needs no provider (AEO twins are prerendered, members-gating is
+//     unavailable), so it stays out.
+//
+//   - NON-STATIC mode (aeoTwins 'middleware'/'both', or flexibleSampling): the
+//     middleware genuinely needs the provider at runtime (Accept: text/markdown
+//     negotiation, LLM-training-crawler 403 on members items). Route modules load
+//     lazily under the Cloudflare adapter, so we cannot rely on an SSR route's
+//     import to seed the provider before the middleware runs. Seeding it via THIS
+//     module — imported at the middleware's own module load — is deterministic.
+//     Bundling the store is acceptable here: non-static consumers serve dynamic
+//     content at runtime by design and are not the ones relying on prerender to
+//     stay under 10 MB.
+const VIRTUAL_LITE_ID = 'virtual:growth-labs/seo/config-lite'
+const RESOLVED_VIRTUAL_LITE_ID = `\0${VIRTUAL_LITE_ID}`
+
 export interface SeoVitePluginOptions {
 	config: ResolvedSeoOptions
 	/**
@@ -37,23 +62,37 @@ export function growthLabsSeoPlugin(opts: SeoVitePluginOptions | ResolvedSeoOpti
 			if (id === VIRTUAL_MODULE_ID) {
 				return RESOLVED_VIRTUAL_MODULE_ID
 			}
+			if (id === VIRTUAL_LITE_ID) {
+				return RESOLVED_VIRTUAL_LITE_ID
+			}
 		},
 		load(id) {
-			if (id !== RESOLVED_VIRTUAL_MODULE_ID) return
+			if (id !== RESOLVED_VIRTUAL_MODULE_ID && id !== RESOLVED_VIRTUAL_LITE_ID) return
+
+			// `config` always seeds the provider (when a module is wired). `config-lite`
+			// seeds the provider only in NON-static modes (see the module comment): in
+			// static mode it must stay provider-free so the always-runtime middleware
+			// doesn't drag the content store into the deployed Worker; in non-static
+			// modes the middleware needs the provider at runtime, so config-lite seeds
+			// it deterministically at the middleware's own load.
+			const aeo = resolveAeoTwins(config.aeoTwins)
+			const staticMode = (!aeo || aeo.mode === 'static') && !config.flexibleSampling.enabled
+			const isLite = id === RESOLVED_VIRTUAL_LITE_ID
+			const withProvider = Boolean(contentProviderModule) && (!isLite || !staticMode)
 
 			// The generated module seeds state via side-effect at import time.
-			// Routes/middleware that `import 'virtual:growth-labs/seo/config'` before
-			// calling getConfig() populate state in whatever environment they run —
-			// the main Worker AND the Cloudflare prerender worker.
+			// Routes/middleware that import it before calling getConfig() populate
+			// state in whatever environment they run — the main Worker AND the
+			// Cloudflare prerender worker.
 			const lines: string[] = [
-				`import { _setConfig, _setContentProvider } from '@growth-labs/seo/_internal/state';`,
+				`import { _setConfig${withProvider ? ', _setContentProvider' : ''} } from '@growth-labs/seo/_internal/state';`,
 			]
-			if (contentProviderModule) {
+			if (withProvider) {
 				lines.push(`import _cp from ${JSON.stringify(contentProviderModule)};`)
 			}
 			lines.push(`const config = ${JSON.stringify(staticConfig)};`)
 			lines.push(`_setConfig(config);`)
-			if (contentProviderModule) {
+			if (withProvider) {
 				lines.push(`_setContentProvider(_cp);`)
 			}
 			lines.push(`export { config };`)