feat: add NotFoundPage and route error handling for 404s

Replace React Router's default developer-facing error screen with
a user-friendly NotFoundPage for 404 errors, falling back to the
existing ErrorPage for other route errors.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: arbrandes

runtime/react/NotFoundPage.jsx

@@ -0,0 +1,56 @@
+import React, { useState } from 'react';
+import {
+  Container, Row, Col, Hyperlink,
+} from '@openedx/paragon';
+
+import { useSiteEvent } from './hooks';
+import {
+  FormattedMessage,
+  IntlProvider,
+  getMessages,
+  getLocale,
+  LOCALE_CHANGED,
+} from '../i18n';
+
+
+function NotFoundPage() {
+  const [locale, setLocale] = useState(getLocale());
+
+  useSiteEvent(LOCALE_CHANGED, () => {
+    setLocale(getLocale());
+  });
+
+  return (
+    <IntlProvider locale={locale} messages={getMessages()}>
+      <Container fluid className="py-5 justify-content-center align-items-start text-center">
+        <Row>
+          <Col>
+            <p className="h2 mb-3">
+              <FormattedMessage
+                id="not.found.page.heading"
+                defaultMessage="404"
+                description="heading for page not found"
+              />
+            </p>
+            <p className="text-muted">
+              <FormattedMessage
+                id="not.found.page.message"
+                defaultMessage="The page you're looking for could not be found."
+                description="message displayed when a page is not found"
+              />
+            </p>
+            <Hyperlink destination="/">
+              <FormattedMessage
+                id="not.found.page.link.text"
+                defaultMessage="Go to the homepage"
+                description="link text to navigate to the homepage from a 404 page"
+              />
+            </Hyperlink>
+          </Col>
+        </Row>
+      </Container>
+    </IntlProvider>
+  );
+}
+
+export default NotFoundPage;

runtime/react/index.ts

@@ -14,6 +14,7 @@ export { default as AuthenticatedPageRoute } from './AuthenticatedPageRoute';
 export { default as Divider } from './Divider';
 export { default as ErrorBoundary } from './ErrorBoundary';
 export { default as ErrorPage } from './ErrorPage';
+export { default as NotFoundPage } from './NotFoundPage';
 export { useSiteEvent, useAuthenticatedUser, useSiteConfig, useAppConfig } from './hooks';
 export { default as LoginRedirect } from './LoginRedirect';
 export { default as PageWrap } from './PageWrap';

shell/router/createRouter.test.tsx

@@ -36,6 +36,7 @@ describe('createRouter', () => {
       [
         {
           Component: Shell,
+          errorElement: expect.anything(),
           children: mockRoutes,
         },
       ],

shell/router/createRouter.ts

@@ -0,0 +1,30 @@
+import { createBrowserRouter, isRouteErrorResponse, useRouteError } from 'react-router-dom';
+
+import { getBasename } from '../../runtime/initialize';
+import ErrorPage from '../../runtime/react/ErrorPage';
+import NotFoundPage from '../../runtime/react/NotFoundPage';
+import Shell from '../Shell';
+
+import getAppRoutes from './getAppRoutes';
+
+function RouteError() {
+  const error = useRouteError();
+
+  if (isRouteErrorResponse(error) && error.status === 404) {
+    return <NotFoundPage />;
+  }
+
+  return <ErrorPage />;
+}
+
+export default function createRouter() {
+  return createBrowserRouter([
+    {
+      Component: Shell,
+      errorElement: <RouteError />,
+      children: getAppRoutes(),
+    }
+  ], {
+    basename: getBasename(),
+  });
+}