FAQ & Troubleshooting

Short problem/cause/fix entries for the non-obvious gotchas in this template.

`params`/`searchParams` are Promises

Problem: params.slug (or similar) is undefined, or TypeScript complains that params isn’t the shape you expected.

Cause: In Next 16, params and searchParams are Promises in Server Components, not plain objects — a change from older Next versions.

Fix: await them before use:


export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  // ...
}

Same applies inside generateMetadata. See app/blog/[slug]/page.tsx for the reference pattern — every dynamic route in this template follows it.

“Edit the home page” is ambiguous

Problem: You changed app/page.tsx expecting it to affect the live marketing site, and nothing looked right — or vice versa.

Cause: app/page.tsx is the template’s own showcase/demo page (uses content/showcase.tsx). app/home/page.tsx is the actual marketing home page for a site built from this template (uses content/home.tsx). They’re separate routes with separate content.

Fix: Confirm which one is meant before editing. See Content Editing.

Removing `gsap-intro-pending` breaks intro animations

Problem: After removing the gsap-intro-pending class (or the logic that removes it) from app/layout.tsx, intro-animated elements flash visible before animating, or never animate at all.

Cause: app/globals.css has a CSS rule keyed off html.gsap-intro-pending that hides intro-animation targets until SiteAnimations removes the class once fonts are ready. The class and the CSS rule are a matched pair.

Fix: Don’t remove the class from layout.tsx without also removing/updating the corresponding rule in globals.css. See Animation System.

Copy changes not showing up

Problem: You edited a component file directly to change some text, and it feels wrong / gets overwritten-feeling on the next content pass.

Cause: This template deliberately separates content from components — copy belongs in content/*.tsx, not hardcoded into organisms/molecules/atoms components. Editing a component directly works, but breaks the “one file per route” mental model and makes the change easy to lose track of.

Fix: Find the content file for that route (content/<route>.tsx) and edit the matching field there instead. See Content Editing.

`footerVariant` only accepts `"full"` or `"minimal"`

Problem: You set footerVariant="dark" / "light" (from older docs or muscle memory) and got a TypeScript error, or the footer isn’t what you expected.

Cause: FooterVariant is "full" | "minimal" (components/organisms/footer.tsx). "full" is the four-column marketing footer used by every real page; "minimal" is the stripped single-row footer used only by the template’s own showcase page (app/page.tsx), and picking it also switches the header to the showcase nav.

Fix: Use "full" for real site pages. If you need a genuinely different footer design, that’s a change to components/organisms/footer.tsx, not a content or prop change. See Component Architecture.

Your AI coding assistant ignores the template’s conventions

Problem: Cursor, Claude Code, Copilot or similar writes copy directly into components instead of content/*.tsx, uses pre-Next-16 APIs, or invents its own animation wiring.

Cause: The template ships a root AGENTS.md describing its architecture — the content/presentation split, the article pipeline, the atomic-design layers, the data-* animation attributes, and the next@16.3.1 pin. Your tool may not be reading it. Most agents look for AGENTS.md, but Claude Code reads CLAUDE.md instead, which is why the template also ships a one-line CLAUDE.md containing @AGENTS.md that imports it.

Fix: Keep both files at the repo root. If you delete CLAUDE.md, Claude Code will silently read nothing — AGENTS.md alone won’t be picked up, and Next won’t recreate the pointer for you. For any other tool, point it at AGENTS.md using whatever mechanism it provides.

Two things worth knowing if you edit AGENTS.md:

It ends with a  block that next dev manages. Leave it alone; Next re-adds it if removed. The shipped .prettierignore keeps Prettier from reflowing it, which would make Next rewrite the file on every dev run.
Everything above that block is yours. As you change the template, keep it current — a stale AGENTS.md actively misleads whichever agent reads it.