Migrate from Next.js Pages Router to App Router

app/README.md

@@ -10,15 +10,15 @@
 ```
 ├── .storybook        # Storybook configuration
 ├── public            # Static assets
-│   └── locales       # Internationalized content
 ├── src               # Source code
+│   ├── app           # Routes, layouts, and loading screens
+│   │   ├── api       # Custom request handlers
+│   │   ├── layout.tsx # Root layout, wraps every page
+│   │   └── page.tsx  # Homepage
 │   ├── components    # Reusable UI components
 │   ├── i18n          # Internationalization
 │   │   ├── config.ts # Supported locales, timezone, and formatters
 │   │   └── messages  # Translated strings
-│   ├── pages         # Page routes and data fetching
-│   │   ├── api       # API routes (optional)
-│   │   └── _app.tsx  # Global entry point
 │   ├── styles        # Sass & design system settings
 │   └── types         # TypeScript type declarations
 ├── stories           # Storybook pages
@@ -27,9 +27,7 @@
 
 ## 💻 Development
 
-[Next.js](https://nextjs.org/docs) provides the React framework for building the web application. Pages are defined in the `pages/` directory. Pages are automatically routed based on the file name. For example, `pages/index.tsx` is the home page.
-
-Files in the `pages/api` are treated as [API routes](https://nextjs.org/docs/api-routes/introduction). An example can be accessed at [localhost:3000/api/hello](http://localhost:3000/api/hello) when running locally.
+[Next.js](https://nextjs.org/docs) provides the React framework for building the web application. Routes are defined in the `app/` directory. Pages are automatically routed based on the directory name. For example, `app/[locale]/about/page.tsx` would render at `/about` (for English) or `/es-US/about` (for Spanish).
 
 [**Learn more about developing Next.js applications** ↗️](https://nextjs.org/docs)
 
@@ -106,9 +104,7 @@ From the `app/` directory:
 
 ## 🐛 Testing
 
-[Jest](https://jestjs.io/docs/getting-started) is used as the test runner and [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) provides React testing utilities.
-
-Tests are manged as `.test.ts` (or `.tsx`) files in the the `tests/` directory.
+[Jest](https://jestjs.io/docs/getting-started) is used as the test runner. Tests are manged as `.test.ts` (or `.tsx`) files in the the `tests/` directory.
 
 To run tests:
 
@@ -122,6 +118,25 @@ A subset of tests can be ran by passing a pattern to the script. For example, to
 npm run test-watch -- pages
 ```
 
+### Testing React components
+
+[React Testing Library (RTL)](https://testing-library.com/docs/react-testing-library/intro) provides the utilities for rendering and querying, and [`jest-axe`](https://www.npmjs.com/package/jest-axe) is used for accessibility testing. Refer to their docs to learn more about their APIs, or view an existing test for examples.
+
+`@testing-library/react` methods should be imported from `tests/react-utils` in order for internationalization to work within your tests:
+
+```diff
+- import { render, screen } from '@testing-library/react';
++ import { render, screen } from 'tests/react-utils';
+
+it("renders submit button", () => {
+  render(<Page />)
+
+  expect(
+    screen.getByRole("button", { name: "Submit" })
+  ).toBeInTheDocument()
+})
+```
+
 ## 🤖 Type checking, linting, and formatting
 
 - [TypeScript](https://www.typescriptlang.org/) is used for type checking.

app/jest.config.js

@@ -9,10 +9,7 @@ const createJestConfig = nextJest({
 // Add any custom config to be passed to Jest
 /** @type {import('jest').Config} */
 const customJestConfig = {
-  setupFilesAfterEnv: [
-    "<rootDir>/tests/jest.setup.ts",
-    "<rootDir>/tests/jest-i18n.ts",
-  ],
+  setupFilesAfterEnv: ["<rootDir>/tests/jest.setup.ts"],
   testEnvironment: "jsdom",
   // if using TypeScript with a baseUrl set to the root directory then you need the below for alias' to work
   moduleDirectories: ["node_modules", "<rootDir>/"],

app/next-env.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
+/// <reference types="next/navigation-types/compat/navigation" />
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/basic-features/typescript for more information.

app/next.config.js

@@ -1,5 +1,5 @@
 // @ts-check
-const withNextIntl = require("next-intl/plugin")("./src/i18n/config.ts");
+const withNextIntl = require("next-intl/plugin")("./src/i18n/server.ts");
 const sassOptions = require("./scripts/sassOptions");
 
 /**
@@ -15,10 +15,6 @@ const appSassOptions = sassOptions(basePath);
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   basePath,
-  i18n: {
-    locales: ["en-US", "es-US"],
-    defaultLocale: "en-US",
-  },
   reactStrictMode: true,
   // Output only the necessary files for a deployment, excluding irrelevant node_modules
   // https://nextjs.org/docs/app/api-reference/next-config-js/output

app/package.json

@@ -19,11 +19,11 @@
     "ts:check": "tsc --noEmit"
   },
   "dependencies": {
-    "@trussworks/react-uswds": "^6.0.0",
+    "@trussworks/react-uswds": "^6.1.0",
     "@uswds/uswds": "3.7.0",
     "lodash": "^4.17.21",
-    "next": "^14.0.0",
-    "next-intl": "^3.2.0",
+    "next": "^14.0.3",
+    "next-intl": "^3.2.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
@@ -40,8 +40,8 @@
     "@types/jest-axe": "^3.5.5",
     "@types/lodash": "^4.14.202",
     "@types/node": "^20.0.0",
-    "@types/react": "^18.0.28",
-    "@types/react-dom": "^18.0.11",
+    "@types/react": "^18.2.42",
+    "@types/react-dom": "^18.2.17",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
     "eslint": "^8.36.0",

app/src/app/[locale]/health/page.tsx

@@ -0,0 +1,3 @@
+export default function Page() {
+  return <>healthy</>;
+}

app/src/app/[locale]/layout.tsx

@@ -0,0 +1,32 @@
+/**
+ * Root layout component, wraps all pages.
+ * @see https://nextjs.org/docs/app/api-reference/file-conventions/layout
+ */
+import { Metadata } from "next";
+
+import Layout from "src/components/Layout";
+
+import "src/styles/styles.scss";
+
+export const metadata: Metadata = {
+  icons: [`${process.env.NEXT_PUBLIC_BASE_PATH ?? ""}/img/logo.svg`],
+};
+
+interface LayoutProps {
+  children: React.ReactNode;
+  params: {
+    locale: string;
+  };
+}
+
+export default function RootLayout({ children, params }: LayoutProps) {
+  return (
+    <html lang={params.locale}>
+      <body>
+        {/* Separate layout component for the inner-body UI elements since Storybook
+            and tests trip over the fact that this file renders an <html> tag */}
+        <Layout locale={params.locale}>{children}</Layout>
+      </body>
+    </html>
+  );
+}