pseo-performance

pSEO Performance Optimization

Optimize the application for fast builds, excellent Core Web Vitals, and reliable performance at 1000+ page scale.

Scope parameter

Value	Sections
build	1, 2, 7, 8
cwv	3, 6, 9
bundle	4
caching	5
all	everything

Core Principles

1. Static first: Pre-render as many pages as possible at build time
2. Incremental where needed: Use ISR for pages that change frequently
3. Minimal JavaScript: Pages should be functional with minimal client-side JS
4. Image optimization: All images processed, sized, and lazy-loaded
5. Cache aggressively: Cache data fetches, API calls, and rendered output

Optimization Areas

1. Static Generation Strategy

Choose the right rendering strategy for scale:

Page Count	Strategy	Implementation
< 500	Full SSG	Generate all pages at build time
500-5000	SSG + ISR	Generate high-traffic pages at build, ISR for rest
5000+	ISR + on-demand	Generate on first request, revalidate periodically

Next.js App Router (without Cache Components, Next.js 15 style and still valid in 16):

// Generate most important pages at build time
export async function generateStaticParams() {
  const topPages = await getTopPages(500);
  return topPages.map((p) => ({ slug: p.slug }));
}

// ISR for the rest
export const revalidate = 86400; // 24 hours

Next.js 16.4.x (>= 16.4.1 for security fixes) with Cache Components (cacheComponents: true, enabled by default in create-next-app from 16.4, planned default in Next.js 17). Caching is opt-in via "use cache", and dynamic is the default:

import { cacheLife, cacheTag } from "next/cache";
import { notFound } from "next/navigation";

export async function generateStaticParams() {
  // With Cache Components this MUST return at least one param.
  // An empty array is a build error.
  const topPages = await getTopPages(500);
  return topPages.map((p) => ({ slug: p.slug }));
}

async function getPage(slug: string) {
  "use cache";
  cacheLife("days");
  cacheTag(`page:${slug}`);
  return fetchSinglePage(slug);
}

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params; // params is async-only in Next.js 16
  const page = await getPage(slug);
  if (!page) notFound(); // see "Status codes with streaming" below
  return <PageView page={page} />;
}

• If you can't list any real params, return one placeholder param and call notFound() for it (the documented workaround).
• ensureStatic (requires cacheComponents): only "navigation" adds build validation (the build fails if dynamic content sneaks in), and it requires generateStaticParams to return every param. "shell" and "prefetch" add no build validation. With seeded params and on-demand rest, do not claim ensureStatic validates anything. Details: https://github.com/lisbeth718/pseo-skills/blob/main/docs/research-2026-10.md (section 11.4).
• Invalidate with revalidateTag(tag, profile) (a cache-life profile is required in Next.js 16), updateTag(tag) for read-your-writes in Server Actions, or refresh().
• Turbopack is the default bundler in Next.js 16. next build no longer runs lint, so run your linter in a pre-push or post-build step.
• Next.js 16.3 added a better ISR path: URLs omitted from build-time prerendering can serve an instant loading shell to the first visitor. Mind the status-code caveat below.