Skip to content

fix(core): adds root-level not found page#2947

Merged
jorgemoya merged 1 commit intocanaryfrom
catalyst-689-fix-404-prod
Mar 24, 2026
Merged

fix(core): adds root-level not found page#2947
jorgemoya merged 1 commit intocanaryfrom
catalyst-689-fix-404-prod

Conversation

@jorgemoya
Copy link
Copy Markdown
Contributor

@jorgemoya jorgemoya commented Mar 23, 2026

What/Why?

When navigating to /404 in production, Catalyst renders the default Vercel/Next.js error screen instead of a branded page. This happens because not-found.tsx only exists inside the [locale] segment, so routes that fall outside that
segment (like the root /404) have no custom not-found page.

This PR:

  • Adds a root-level app/layout.tsx that owns the and tags (with fonts and global CSS)
  • Moves the / out of app/[locale]/layout.tsx (now renders a fragment)
  • Adds app/not-found.tsx with a branded not-found page styled to match the Vibes NotFound section and ButtonLink primary variant

Testing

  • Run pnpm dev and navigate to /404 — should show the branded not-found page with "Not found" heading, subtitle, and "Go to homepage" button
  • Navigate to a non-existent route (e.g., /nonexistent) — should also render the branded page
  • Verify existing locale not-found pages still work (e.g., /en/nonexistent)
  • Verify the homepage and other pages render correctly (fonts, global styles still applied)
Screenshot 2026-03-23 at 10 05 12 AM

Migration

  • app/[locale]/layout.tsx no longer renders or — it now returns a fragment
  • A new app/layout.tsx has been added as the root layout. If you have customized the or tags, move those customizations to app/layout.tsx

@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented Mar 23, 2026

🦋 Changeset detected

Latest commit: c48e1bb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@bigcommerce/catalyst-core Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@vercel
Copy link
Copy Markdown

vercel Bot commented Mar 23, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
catalyst Ready Ready Preview, Comment Mar 23, 2026 3:04pm

Request Review

@github-actions
Copy link
Copy Markdown
Contributor

Bundle Size Report

Comparing against baseline from 4479964 (2026-03-23).

No bundle size changes detected.

@github-actions
Copy link
Copy Markdown
Contributor

Unlighthouse Performance Comparison — Vercel

Comparing PR preview deployment Unlighthouse scores vs production Unlighthouse scores.

Summary Score

Aggregate score across all categories as reported by Unlighthouse.

Prod Desktop Prod Mobile Preview Desktop Preview Mobile
Score 92 95 91 94

Category Scores

Category Prod Desktop Prod Mobile Preview Desktop Preview Mobile
Performance 75 75 77 94
Accessibility 95 95 95 98
Best Practices 100 100 95 100
SEO 100 100 100 100

Core Web Vitals

Metric Prod Desktop Prod Mobile Preview Desktop Preview Mobile
LCP 3.5 s 4.1 s 3.3 s 3.0 s
CLS 0.05 0.239 0.05 0
FCP 1.2 s 1.2 s 1.2 s 1.2 s
TBT 20 ms 0 ms 10 ms 10 ms
Max Potential FID 80 ms 40 ms 70 ms 60 ms
Time to Interactive 3.6 s 4.1 s 3.9 s 3.9 s

Full Unlighthouse report →

@jorgemoya jorgemoya marked this pull request as ready for review March 23, 2026 16:13
@jorgemoya jorgemoya requested a review from a team as a code owner March 23, 2026 16:13
@jorgemoya jorgemoya added this pull request to the merge queue Mar 24, 2026
Merged via the queue into canary with commit e198d89 Mar 24, 2026
18 of 19 checks passed
@jorgemoya jorgemoya deleted the catalyst-689-fix-404-prod branch March 24, 2026 13:23
jorgemoya added a commit that referenced this pull request Apr 24, 2026
The root <html> tag was hardcoded to lang="en" for all locales because
#2947 moved <html>/<body> ownership from app/[locale]/layout.tsx up to
a new root app/layout.tsx to enable the branded /404 page. That fix
solved the 404 but regressed the lang attribute.

Adopt next-intl's documented pattern:
- app/layout.tsx is now a passthrough (returns children) — required by
  Next.js but owns no markup.
- app/[locale]/layout.tsx owns <html lang={locale}> and <body> again,
  so localized pages get the correct language.
- app/not-found.tsx owns its own <html>/<body>, fonts, and global CSS
  so the branded 404 still renders for non-localized requests.

Verified parity with canary on runtime 404 behavior (both serve the
Next.js error-fallback shell for dynamic 404s) and clean output in the
prerendered _not-found.html static file.

Fixes LTRAC-578

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants