feat: Implement App Router integration and 404 handling (#56915)

Co-authored-by: Copilot <[email protected]>

Author: wiinci

src/app/404/page.tsx

@@ -0,0 +1,105 @@
+import { getAppRouterContext } from '@/app/lib/app-router-context'
+import { AppRouterMainContextProvider } from '@/app/components/AppRouterMainContext'
+import { translate } from '@/languages/lib/translation-utils'
+import { CommentDiscussionIcon, MarkGithubIcon } from '@primer/octicons-react'
+import type { Metadata } from 'next'
+
+export const dynamic = 'force-dynamic'
+
+export const metadata: Metadata = {
+  title: '404 - Page not found',
+  other: { status: '404' },
+}
+
+export default async function Page404() {
+  // Get context with UI data
+  const appContext = await getAppRouterContext()
+
+  const siteTitle = translate(appContext.site.data.ui, 'header.github_docs', 'GitHub Docs')
+  const oopsTitle = translate(appContext.site.data.ui, 'meta.oops', 'Ooops!')
+
+  return (
+    <AppRouterMainContextProvider context={appContext}>
+      <div className="min-h-screen d-flex flex-column">
+        {/* Simple Header */}
+        <div className="border-bottom color-border-muted no-print">
+          <header className="container-xl p-responsive py-3 position-relative d-flex width-full">
+            <div className="d-flex flex-1 flex-items-center">
+              <a
+                href={`/${appContext.currentLanguage}`}
+                className="color-fg-default no-underline d-flex flex-items-center"
+              >
+                <MarkGithubIcon size={32} className="mr-2" />
+                <span className="f4 text-bold">{siteTitle}</span>
+              </a>
+            </div>
+          </header>
+        </div>
+
+        {/* Main Content */}
+        <div className="container-xl p-responsive py-6 width-full flex-1">
+          <article className="col-md-10 col-lg-7 mx-auto">
+            <h1>{oopsTitle}</h1>
+            <div className="f2 color-fg-muted mb-3" data-container="lead">
+              It looks like this page doesn't exist.
+            </div>
+            <p className="f3">
+              We track these errors automatically, but if the problem persists please feel free to
+              contact us.
+            </p>
+            <a id="support" href="https://support.github.com" className="btn btn-outline mt-2">
+              <CommentDiscussionIcon size="small" className="octicon mr-1" />
+              Contact support
+            </a>
+          </article>
+        </div>
+
+        <footer className="py-6">
+          <div className="container-xl px-3 px-md-6">
+            <ul className="d-flex flex-wrap list-style-none">
+              <li className="d-flex mr-xl-3 color-fg-muted">
+                <span>© 2025 GitHub, Inc.</span>
+              </li>
+              <li className="ml-3">
+                <a
+                  className="text-underline"
+                  href="/site-policy/github-terms/github-terms-of-service"
+                >
+                  Terms
+                </a>
+              </li>
+              <li className="ml-3">
+                <a
+                  className="text-underline"
+                  href="/site-policy/privacy-policies/github-privacy-statement"
+                >
+                  Privacy
+                </a>
+              </li>
+              <li className="ml-3">
+                <a className="text-underline" href="https://www.githubstatus.com/">
+                  Status
+                </a>
+              </li>
+              <li className="ml-3">
+                <a className="text-underline" href="https://github.com/pricing">
+                  Pricing
+                </a>
+              </li>
+              <li className="ml-3">
+                <a className="text-underline" href="https://services.github.com/">
+                  Expert services
+                </a>
+              </li>
+              <li className="ml-3">
+                <a className="text-underline" href="https://github.blog/">
+                  Blog
+                </a>
+              </li>
+            </ul>
+          </div>
+        </footer>
+      </div>
+    </AppRouterMainContextProvider>
+  )
+}

src/app/_not-found/page.tsx

@@ -0,0 +1,7 @@
+import { notFound } from 'next/navigation'
+
+// This page handles internal /_not-found redirects from Express middleware
+export default function InternalNotFound() {
+  // This will trigger Next.js to render the not-found.tsx page
+  notFound()
+}

src/app/client-layout.tsx

@@ -0,0 +1,126 @@
+'use client'
+
+import { ThemeProvider } from '@primer/react'
+import { useEffect, useMemo, useState } from 'react'
+
+import { LocaleProvider } from '@/app/lib/locale-context'
+import { useDetectLocale } from '@/app/lib/use-detect-locale'
+import { useTheme } from '@/color-schemes/components/useTheme'
+import { initializeEvents } from '@/events/components/events'
+import { CTAPopoverProvider } from '@/frame/components/context/CTAContext'
+import { SharedUIContextProvider } from '@/frame/components/context/SharedUIContext'
+import { LanguagesContext, LanguagesContextT } from '@/languages/components/LanguagesContext'
+import { clientLanguages, type ClientLanguageCode } from '@/languages/lib/client-languages'
+import { MainContextProvider } from '@/app/components/MainContextProvider'
+import { createMinimalMainContext } from '@/app/lib/main-context-adapter'
+import type { AppRouterContext } from '@/app/lib/app-router-context'
+
+interface ClientLayoutProps {
+  readonly children: React.ReactNode
+  readonly appContext?: AppRouterContext
+  readonly pageData?: {
+    title?: string
+    fullTitle?: string
+    introPlainText?: string
+    topics?: string[]
+    documentType?: string
+    type?: string
+    hidden?: boolean
+  }
+}
+
+export function ClientLayout({ children, appContext, pageData }: ClientLayoutProps): JSX.Element {
+  const { theme } = useTheme()
+  const locale: ClientLanguageCode = useDetectLocale()
+  const [isInitialized, setIsInitialized] = useState(false)
+  const [initializationError, setInitializationError] = useState<Error | null>(null)
+
+  const languagesContext: LanguagesContextT = useMemo(
+    () => ({
+      languages: clientLanguages,
+    }),
+    [],
+  )
+
+  // Create MainContext-compatible data for App Router
+  const mainContext = useMemo(
+    () => createMinimalMainContext(pageData, appContext),
+    [pageData, appContext],
+  )
+
+  useEffect(() => {
+    const initializeTheme = async (): Promise<void> => {
+      try {
+        const html = document.documentElement
+
+        if (theme.css?.colorMode) {
+          html.setAttribute('data-color-mode', theme.css.colorMode)
+        }
+
+        if (theme.css?.darkTheme) {
+          html.setAttribute('data-dark-theme', theme.css.darkTheme)
+        }
+
+        if (theme.css?.lightTheme) {
+          html.setAttribute('data-light-theme', theme.css.lightTheme)
+        }
+
+        if (!isInitialized) {
+          await initializeEvents()
+          setIsInitialized(true)
+        }
+      } catch (error) {
+        console.error('Failed to initialize theme:', error)
+        setInitializationError(error as Error)
+      }
+    }
+
+    initializeTheme()
+  }, [theme, isInitialized])
+
+  if (initializationError) {
+    return (
+      <div
+        role="alert"
+        className="min-h-screen flex items-center justify-center bg-canvas-default p-4"
+      >
+        <div className="max-w-md text-center">
+          <h2 className="text-xl font-semibold mb-4 text-danger-fg">Something went wrong</h2>
+          <p className="text-fg-muted mb-4">Please try refreshing the page.</p>
+          <button
+            onClick={() => {
+              setInitializationError(null)
+              setIsInitialized(false)
+            }}
+            className="btn btn-primary"
+            type="button"
+            aria-label="Try again"
+          >
+            Try again
+          </button>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <LocaleProvider locale={locale}>
+      <LanguagesContext.Provider value={languagesContext}>
+        <MainContextProvider value={mainContext}>
+          <ThemeProvider
+            colorMode={theme.component.colorMode}
+            dayScheme={theme.component.dayScheme}
+            nightScheme={theme.component.nightScheme}
+            preventSSRMismatch
+          >
+            <SharedUIContextProvider>
+              <CTAPopoverProvider>
+                <div className="min-h-screen flex flex-col">{children}</div>
+              </CTAPopoverProvider>
+            </SharedUIContextProvider>
+          </ThemeProvider>
+        </MainContextProvider>
+      </LanguagesContext.Provider>
+    </LocaleProvider>
+  )
+}

src/app/components/AppRouterMainContext.tsx

@@ -0,0 +1,52 @@
+'use client'
+import type { AppRouterContext } from '@/app/lib/app-router-context'
+import type { MainContextT } from '@/frame/components/context/MainContext'
+import { adaptAppRouterContextToMainContext } from '@/app/lib/main-context-adapter'
+import { createContext, ReactNode, useContext, useMemo } from 'react'
+
+export const AppRouterMainContext = createContext<AppRouterContext | null>(null)
+
+// Provides MainContext-compatible data
+export const AppRouterCompatMainContext = createContext<MainContextT | null>(null)
+
+export function AppRouterMainContextProvider({
+  children,
+  context,
+}: {
+  children: ReactNode
+  context: AppRouterContext
+}) {
+  // Create a MainContext-compatible version for existing components
+  const mainContextCompat = useMemo(() => adaptAppRouterContextToMainContext(context), [context])
+
+  return (
+    <AppRouterMainContext.Provider value={context}>
+      <AppRouterCompatMainContext.Provider value={mainContextCompat}>
+        {children}
+      </AppRouterCompatMainContext.Provider>
+    </AppRouterMainContext.Provider>
+  )
+}
+
+export function useAppRouterMainContext(): AppRouterContext {
+  const context = useContext(AppRouterMainContext)
+
+  if (!context) {
+    throw new Error('useAppRouterMainContext must be used within AppRouterMainContextProvider')
+  }
+
+  return context
+}
+
+// Hook for components that need MainContext compatibility
+export function useAppRouterCompatMainContext(): MainContextT {
+  const context = useContext(AppRouterCompatMainContext)
+
+  if (!context) {
+    throw new Error(
+      'useAppRouterCompatMainContext must be used within AppRouterMainContextProvider',
+    )
+  }
+
+  return context
+}

src/app/components/MainContextProvider.tsx

@@ -0,0 +1,17 @@
+'use client'
+
+import type { ReactNode } from 'react'
+import { MainContext, type MainContextT } from '@/frame/components/context/MainContext'
+
+interface MainContextProviderProps {
+  children: ReactNode
+  value: MainContextT
+}
+
+/**
+ * App Router compatible MainContext provider
+ * This allows reusing existing components that depend on MainContext
+ */
+export function MainContextProvider({ children, value }: MainContextProviderProps) {
+  return <MainContext.Provider value={value}>{children}</MainContext.Provider>
+}