style: better landing

Author: asmyshlyaev177

AGENTS.md

@@ -146,7 +146,8 @@ nothing but the `(tests)` group). It audits the production build: `build:demo`
 `dist/`) then `next start --port 3012`. Port 3012, not the demo's own 3002, so a
 server left over from `pnpm run dev` cannot be silently accepted in place of it.
 
-**Only the four public pages** — `/`, `/react-router`, `/remix`, `/astro`. The app also
+**Only the four demo pages** — `/`, `/react-router`, `/remix`, `/astro` (`/nextjs` and
+`/vs/nuqs` are prerendered prose pages and are audited by the a11y suite instead). The app also
 serves `/useUrlState`, `/test-ssr` and the rest of the `(tests)` group, but those
 are e2e fixtures that happen to be deployed: they exist to be asserted against,
 not read, and several render in ways no real page would.
@@ -177,6 +178,7 @@ answers agents in four overlapping ways — they disagree about which to try:
 | `/llms.txt` | `public/llms.txt` — the single source |
 | `/` under `Accept: text/markdown`, or a known agent user-agent — 307 to `/index.md` | `src/proxy.ts` |
 | `/index.md`, `/react-router.md`, `/remix.md`, `/astro.md` | `src/app/<route>.md/route.ts`, all four through `src/app/llmsTxtResponse.ts` |
+| `/nextjs.md`, `/vs/nuqs.md` | built from the page's own copy module and samples — those pages have content of their own |
 | `<link rel="alternate">` and a `Link:` response header | `src/app/seoStuff.ts` (`markdownAlternates`), `next.config.mjs` |
 
 All three `.md` mirrors serve the same document, deliberately: this site is one

packages/example-nextjs16/next.config.mjs

@@ -65,6 +65,18 @@ const nextConfig = {
     // !! WARN !!
     ignoreBuildErrors: true,
   },
+  async redirects() {
+    // `www.` served the whole site as a second host; canonical tags pointed
+    // at the apex but nothing sent a reader there. One 308 does.
+    return [
+      {
+        source: '/:path*',
+        has: [{ type: 'host', value: 'www.state-in-url.dev' }],
+        destination: 'https://state-in-url.dev/:path*',
+        permanent: true,
+      },
+    ];
+  },
   async headers() {
     // A `Link:` header survives a HEAD request and reaches clients that never
     // parse markup. Per documented page, not globbed, so it can't end up on
@@ -129,7 +141,7 @@ const nextConfig = {
     // and `<Link>` prefetch revalidates on a loop, measured at ~26 requests a
     // second from one idle tab. Its layout's `revalidate` caches it for a week.
     const demoPages = ['', '/react-router', '/remix', '/astro'];
-    const pages = [...demoPages, '/vs/nuqs'];
+    const pages = [...demoPages, '/nextjs', '/vs/nuqs'];
     const prefixes = ['', ...LOCALES.map((locale) => `/${locale.dir}`)];
 
     return [

packages/example-nextjs16/public/llms.txt

@@ -301,6 +301,8 @@ Same module-scoped default-state-identity rule. Use only when URL sync is explic
 
 ## Documentation resources
 
+- Next.js App Router guide (searchParams forwarding, layouts, history, FAQ): https://state-in-url.dev/nextjs — Markdown at https://state-in-url.dev/nextjs.md
+- Comparison with nuqs, TanStack Router, use-query-params: https://state-in-url.dev/vs/nuqs — Markdown at https://state-in-url.dev/vs/nuqs.md
 - Full README (humans): https://github.com/asmyshlyaev177/state-in-url/blob/master/README.md
 - URL size limits: https://github.com/asmyshlyaev177/state-in-url/blob/master/Limits.md
 - Working examples per framework: `packages/example-nextjs{14,15,16}`, `packages/example-react-router{6,7}`, `packages/example-remix2`, `packages/example-astro`

packages/example-nextjs16/src/app/(en)/nextjs/page.tsx

@@ -0,0 +1,32 @@
+import { copy } from '../../i18n/copy/en';
+import { breadcrumbListJsonLd, faqPageJsonLd, jsonLdScript } from '../../jsonLd';
+import { NextjsPage } from '../../pages/NextjsPage';
+import { pageMetadata } from '../../seoStuff';
+
+export const metadata = pageMetadata({
+  path: '/nextjs',
+  title: copy.meta.nextjs.title,
+  description: copy.meta.nextjs.description,
+});
+
+export default async function Nextjs() {
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{
+          __html: jsonLdScript([
+            faqPageJsonLd(copy.nextjs.faq.items),
+            breadcrumbListJsonLd({
+              homeName: copy.chrome.home,
+              homeHref: '/',
+              name: copy.nextjs.crumb,
+              path: '/nextjs',
+            }),
+          ]),
+        }}
+      />
+      <NextjsPage copy={copy} homeHref="/" vsHref="/vs/nuqs" />
+    </>
+  );
+}

packages/example-nextjs16/src/app/(en)/page.tsx

@@ -1,14 +1,22 @@
 import { CodeBlocks } from '../CodeBlocksNext';
 import { copy } from '../i18n/copy/en';
+import { faqPageJsonLd, jsonLdScript } from '../jsonLd';
 import { DemoPage } from '../pages/DemoPage';
 
 export default async function Home({ searchParams }: { searchParams: Promise<object> }) {
   return (
-    <DemoPage
-      searchParams={searchParams}
-      copy={copy}
-      codeBlocks={<CodeBlocks copy={copy.quickStart} />}
-      aiSkills
-    />
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: jsonLdScript([faqPageJsonLd(copy.faq.items)]) }}
+      />
+      <DemoPage
+        searchParams={searchParams}
+        copy={copy}
+        codeBlocks={<CodeBlocks copy={copy.quickStart} />}
+        aiSkills
+        faq
+      />
+    </>
   );
 }

packages/example-nextjs16/src/app/[locale]/nextjs/page.tsx

@@ -0,0 +1,48 @@
+import { notFound } from 'next/navigation';
+
+import { localeFromParam } from '../../i18n';
+import { copyFor } from '../../i18n/copy';
+import { breadcrumbListJsonLd, faqPageJsonLd, jsonLdScript } from '../../jsonLd';
+import { NextjsPage } from '../../pages/NextjsPage';
+import { localeMetadata } from '../../seoStuff';
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ locale: string }>;
+}) {
+  const { locale } = await params;
+  return localeMetadata({ localeDir: locale, path: '/nextjs' });
+}
+
+export default async function Nextjs({
+  params,
+}: {
+  params: Promise<{ locale: string }>;
+}) {
+  const { locale: dir } = await params;
+  const locale = localeFromParam(dir);
+  if (!locale) notFound();
+
+  const copy = copyFor(locale.code);
+
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{
+          __html: jsonLdScript([
+            faqPageJsonLd(copy.nextjs.faq.items),
+            breadcrumbListJsonLd({
+              homeName: copy.chrome.home,
+              homeHref: `/${dir}`,
+              name: copy.nextjs.crumb,
+              path: '/nextjs',
+            }),
+          ]),
+        }}
+      />
+      <NextjsPage copy={copy} homeHref={`/${dir}`} vsHref={`/${dir}/vs/nuqs`} />
+    </>
+  );
+}

packages/example-nextjs16/src/app/[locale]/page.tsx

@@ -3,6 +3,7 @@ import { notFound } from 'next/navigation';
 import { CodeBlocks } from '../CodeBlocksNext';
 import { localeFromParam } from '../i18n';
 import { copyFor } from '../i18n/copy';
+import { faqPageJsonLd, jsonLdScript } from '../jsonLd';
 import { DemoPage } from '../pages/DemoPage';
 import { localeMetadata } from '../seoStuff';
 
@@ -25,11 +26,20 @@ export default async function Home({
   const copy = copyFor(locale.code);
 
   return (
-    <DemoPage
-      searchParams={searchParams}
-      copy={copy} vsHref={`/${dir}/vs/nuqs`}
-      codeBlocks={<CodeBlocks copy={copy.quickStart} />}
-      aiSkills
-    />
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: jsonLdScript([faqPageJsonLd(copy.faq.items)]) }}
+      />
+      <DemoPage
+        searchParams={searchParams}
+        copy={copy}
+        vsHref={`/${dir}/vs/nuqs`}
+        nextjsHref={`/${dir}/nextjs`}
+        codeBlocks={<CodeBlocks copy={copy.quickStart} />}
+        aiSkills
+        faq
+      />
+    </>
   );
 }

packages/example-nextjs16/src/app/components/Breadcrumbs.tsx

@@ -11,10 +11,11 @@ import type { SiteCopy } from '../i18n/copy/types';
  * subpages get their trail right under the top bar, above the hero.
  *
  * The matching BreadcrumbList JSON-LD is emitted by each subpage's route
- * (see `breadcrumbJsonLd` in VsNuqsPage) — keep the two in step.
+ * (`breadcrumbListJsonLd` in jsonLd.ts) — keep the two in step.
  */
 const CRUMB_OF: Record<string, (copy: SiteCopy) => string> = {
   '/vs/nuqs': (copy) => copy.comparison.title,
+  '/nextjs': (copy) => copy.nextjs.crumb,
 };
 
 export const Breadcrumbs = ({

packages/example-nextjs16/src/app/components/Description.tsx

@@ -1,8 +1,9 @@
+import { Link } from "./Link"
 import { Share } from "./Share"
 import { Word } from "./Word"
 import type { SiteCopy } from "../i18n/copy/types"
 
-export const Description = ({ copy }: { copy: SiteCopy }) => (
+export const Description = ({ copy, nextjsHref }: { copy: SiteCopy; nextjsHref: string }) => (
   <section className='flex flex-col items-start w-full max-w-[640px] mt-4'>
     <h2 className='text-3xl mt-12 mb-4 font-bold font-display text-ink'>
       {copy.description.title}
@@ -16,6 +17,9 @@ export const Description = ({ copy }: { copy: SiteCopy }) => (
 
     <h3 className='mt-8 mb-2 font-bold text-lg font-display text-ink'>{copy.description.suspenseTitle}</h3>
     <p className='text-base leading-relaxed text-ink2'>{copy.description.suspenseLead} <Word>useSearchParams</Word>{copy.description.suspenseAfterHook} <Word>Suspense</Word> {copy.description.suspenseAfterBoundary} <Word>cacheComponents</Word> {copy.description.suspenseAfterFlag} <Word>history.pushState</Word> {copy.description.suspenseTail}</p>
+    <p className='mt-3 text-base leading-relaxed'>
+      <Link href={nextjsHref} className="font-semibold text-[var(--accent-on-soft)] hover:underline">{copy.nextjs.crumb}</Link>
+    </p>
 
     <h3 className='mt-8 mb-2 font-bold text-lg font-display text-ink'>{copy.description.otherTitle}</h3>
     <p className='text-base leading-relaxed text-ink2'>{copy.description.helpersLead} <Word>encodeState</Word> / <Word>decodeState</Word> {copy.description.helpersTail}</p>

packages/example-nextjs16/src/app/components/Faq.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+
+import type { FaqCopy } from '../i18n/copy/types';
+
+/**
+ * A FAQ block, rendered as a definition list so the question/answer pairing
+ * survives without styling. The same items go out as FAQPage JSON-LD through
+ * `faqPageJsonLd` in `jsonLd.ts`; routes emit that, this renders the DOM, and
+ * both read one copy object so they cannot disagree.
+ */
+export const Faq = ({ copy, id }: { copy: FaqCopy; id: string }) => (
+  <section
+    className="flex w-full max-w-[640px] flex-col items-start"
+    aria-labelledby={id}
+  >
+    <h2
+      id={id}
+      className="font-display text-ink mb-4 mt-12 text-3xl font-bold"
+    >
+      {copy.title}
+    </h2>
+    <dl className="w-full">
+      {copy.items.map((item) => (
+        <div
+          key={item.q}
+          className="border-b border-[var(--line)] py-4 last:border-b-0"
+        >
+          <dt className="text-ink font-semibold">{item.q}</dt>
+          <dd className="text-ink2 mt-2 text-base leading-relaxed">{item.a}</dd>
+        </div>
+      ))}
+    </dl>
+  </section>
+);