nextjs-landing-page
Build the page in Next.js App Router with client boundaries at the leaves, so the
bundle stays small and the copy stays server-rendered.
The failure this fixes
The single most-documented Next.js failure: putting "use client" too high — at
a layout.tsx or page shell. Because the directive is a module boundary,
everything imported below it (and everything those imports pull in) gets bundled
for the browser — community reports describe 200-400KB+ of dead client JS. Worse
for a landing page: a client-boundary layout strips server-rendered copy and
blocks metadata/generateMetadata (mutually exclusive with "use client" in
one file), so the initial HTML ships with a blank/late <head> and unindexed
content — the whole SEO point of Next.js, gone.
When to use / when NOT to use
Use to implement/scaffold/fix a Next.js App Router landing page: RSC boundaries,
shadcn/Tailwind setup, next/image/next/font, rendering strategy, and the
framework gotchas.
Not for: copy (landing-page-copywriting), section order
(landing-page-structure), palette/type (visual-design-system), animation
design (scroll-motion — this skill only wires the "use client" boundary it
needs), Core Web Vitals / SEO strategy (web-vitals-and-seo), or WCAG
(landing-page-accessibility).
Workflow
- Default to Server Components; push
"use client" to leaves. Every app/
file is a Server Component (0 KB JS) unless marked. Keep hero copy, proof,
pricing, and FAQ server-rendered; mark only the interactive leaf (a button, a
form, the animated element). Auditing boundary placement is the highest-leverage
bundle fix.
- Keep server subtrees server-rendered inside client parents. Pass Server
Components as
children to a Client Component and they stay on the server — the
escape hatch for heavy/server-only logic. Use next/dynamic for heavy
client-only libs (charts, the motion API); optimizePackageImports for
many-export packages.
- Choose rendering: SSG/ISR by default for marketing; SSR only for
genuinely personalized content; PPR /
use cache (Next 16) for mixed
static+dynamic. Stream content, never stream metadata — an async
generateMetadata that resolves late injects the <head> after the initial
HTML (an SEO bug). Keep metadata synchronous/fast.
- Set up shadcn/Tailwind correctly. shadcn is open code (
npx shadcn add
vendors source into your repo — you own it, upstream sync is manual). The July
2026 Base UI default, Tailwind v4 @theme inline, and the layering model are
version-dependent — see references/nextjs-implementation.md and verify against
the changelog.
- Wire images and fonts for zero CLS.
next/image with priority on the LCP
hero and sizes set; next/font self-hosts and generates fallback metrics.
Details in the reference.
- Patch the critical CVE. Verify the app is on a Next.js/React version fixed
for CVE-2025-55182 ("React2Shell") — see the reference and the official
advisory.
The rules
"use client" is contagious up the import tree — it bundles the whole
subtree, not just the leaf."use client" and metadata/generateMetadata cannot coexist in one file.- Children-as-props keeps subtrees server-rendered even inside a client parent.
- SSG/ISR is the marketing default; server-only libs (markdown, formatting)
ship zero bytes when kept in Server Components.
- Stream content, not metadata.
- shadcn output needs de-defaulting — v0/Cursor emit stock "grayscale PDF"
shadcn; theme the tokens (the aesthetic choices are
visual-design-system).
- Vercel coupling is real — PPR/edge features are Vercel-tuned; note portability
cost. For a zero-interactivity page, Astro's islands (~0-15 KB) beat Next's
baseline — point there when the page won't grow into an app.
Output
A Next.js App Router landing page with client boundaries at the leaves, metadata
server-rendered and synchronous, next/image/next/font wired for zero CLS,
shadcn/Tailwind set up with themed tokens, SSG/ISR rendering, and version-gated
claims (Base UI, Tailwind v4, PPR, the CVE) checked against current docs.
References
references/nextjs-implementation.md - RSC boundary patterns, shadcn open-code
- Base UI switch + Tailwind v4 gotchas, image/font specifics, PPR/rendering,
CVE-2025-55182 details with fixed versions, and the fact ledger.
1---2name: nextjs-landing-page3description: Implements a landing page in Next.js App Router with React + shadcn/ui + Tailwind - RSC/client-component boundaries, shadcn setup, next/image & next/font, and the streaming-metadata gotcha. Use when asked to build, scaffold, or fix a Next.js landing page, resolve 'use client' errors, set up shadcn, or fix a blank-head/unindexed page. Not for copy, visual design, animation, or SEO strategy.4---56# nextjs-landing-page78Build the page in Next.js App Router with client boundaries at the leaves, so the9bundle stays small and the copy stays server-rendered.1011## The failure this fixes1213The single most-documented Next.js failure: putting `"use client"` too high — at14a `layout.tsx` or page shell. Because the directive is a *module boundary*,15everything imported below it (and everything those imports pull in) gets bundled16for the browser — community reports describe 200-400KB+ of dead client JS. Worse17for a landing page: a client-boundary layout strips server-rendered copy and18blocks `metadata`/`generateMetadata` (mutually exclusive with `"use client"` in19one file), so the initial HTML ships with a blank/late `<head>` and unindexed20content — the whole SEO point of Next.js, gone.2122## When to use / when NOT to use2324Use to implement/scaffold/fix a Next.js App Router landing page: RSC boundaries,25shadcn/Tailwind setup, `next/image`/`next/font`, rendering strategy, and the26framework gotchas.2728Not for: copy (`landing-page-copywriting`), section order29(`landing-page-structure`), palette/type (`visual-design-system`), animation30design (`scroll-motion` — this skill only wires the `"use client"` boundary it31needs), Core Web Vitals / SEO strategy (`web-vitals-and-seo`), or WCAG32(`landing-page-accessibility`).3334## Workflow35361. **Default to Server Components; push `"use client"` to leaves.** Every `app/`37 file is a Server Component (0 KB JS) unless marked. Keep hero copy, proof,38 pricing, and FAQ server-rendered; mark only the interactive leaf (a button, a39 form, the animated element). Auditing boundary placement is the highest-leverage40 bundle fix.412. **Keep server subtrees server-rendered inside client parents.** Pass Server42 Components as `children` to a Client Component and they stay on the server — the43 escape hatch for heavy/server-only logic. Use `next/dynamic` for heavy44 client-only libs (charts, the `motion` API); `optimizePackageImports` for45 many-export packages.463. **Choose rendering: SSG/ISR by default** for marketing; SSR only for47 genuinely personalized content; PPR / `use cache` (Next 16) for mixed48 static+dynamic. **Stream content, never stream metadata** — an async49 `generateMetadata` that resolves late injects the `<head>` after the initial50 HTML (an SEO bug). Keep metadata synchronous/fast.514. **Set up shadcn/Tailwind correctly.** shadcn is *open code* (`npx shadcn add`52 vendors source into your repo — you own it, upstream sync is manual). The July53 2026 Base UI default, Tailwind v4 `@theme inline`, and the layering model are54 version-dependent — see `references/nextjs-implementation.md` and verify against55 the changelog.565. **Wire images and fonts for zero CLS.** `next/image` with `priority` on the LCP57 hero and `sizes` set; `next/font` self-hosts and generates fallback metrics.58 Details in the reference.596. **Patch the critical CVE.** Verify the app is on a Next.js/React version fixed60 for **CVE-2025-55182 ("React2Shell")** — see the reference and the official61 advisory.6263## The rules6465- **`"use client"` is contagious up the import tree** — it bundles the whole66 subtree, not just the leaf.67- **`"use client"` and `metadata`/`generateMetadata` cannot coexist** in one file.68- **Children-as-props keeps subtrees server-rendered** even inside a client parent.69- **SSG/ISR is the marketing default;** server-only libs (markdown, formatting)70 ship zero bytes when kept in Server Components.71- **Stream content, not metadata.**72- **shadcn output needs de-defaulting** — v0/Cursor emit stock "grayscale PDF"73 shadcn; theme the tokens (the aesthetic choices are `visual-design-system`).74- **Vercel coupling is real** — PPR/edge features are Vercel-tuned; note portability75 cost. For a zero-interactivity page, Astro's islands (~0-15 KB) beat Next's76 baseline — point there when the page won't grow into an app.7778## Output7980A Next.js App Router landing page with client boundaries at the leaves, metadata81server-rendered and synchronous, `next/image`/`next/font` wired for zero CLS,82shadcn/Tailwind set up with themed tokens, SSG/ISR rendering, and version-gated83claims (Base UI, Tailwind v4, PPR, the CVE) checked against current docs.8485## References8687- `references/nextjs-implementation.md` - RSC boundary patterns, shadcn open-code88 + Base UI switch + Tailwind v4 gotchas, image/font specifics, PPR/rendering,89 CVE-2025-55182 details with fixed versions, and the fact ledger.
Paldom