Add a page

Example used to test this page: an /about page that lists the latest items with serverApi(), and a small form, shown to signed-in users, that adds an item through a Server Action.

frontend/app/settings/ is the reference: an async Server Component in page.tsx, a colocated actions.ts, a client island, and a colocated SASS module. Copy it.

Steps

1. Create frontend/app/<route>/page.tsx as an async Server Component (no 'use client'). Fetch with serverApi(), the way the backoffice email page does:

   const client = await serverApi();
   const { data, error } = await client.GET('/admin/email/stats');
   

   serverApi() attaches the session's bearer token on the server, so the token never reaches the browser. With no session it sends no header, so public routes still work. Always handle error or a missing data and render a message instead of throwing.

   To know who is signed in, call auth() from @/auth, as app/settings/page.tsx does (const session = await auth();).

   Set the title with export const metadata: Metadata = { title: '... | CrabStack' }. A private page also sets robots: { index: false, follow: false }, as settings does.

2. Put mutations in a colocated actions.ts that starts with 'use server'. Each action calls serverApi() itself, catches failures, and returns an error state, the way openBillingPortalAction in app/settings/actions.ts does:

   try {
     const client = await serverApi();
     const { data, error } = await client.POST('/billing/portal');
     if (error || !data) {
       return { error: 'Could not open the billing portal. Try again.' };
     }
   

   After a successful write, call revalidatePath('/<route>') from next/cache so the page shows the new data, as app/backoffice/users/actions.ts does. Validate form input in the action too; the browser's checks are not a security boundary.

3. Make the interactive part a client island: a separate file that starts with 'use client' and wires the action with React's useActionState, as app/settings/AccountSettings.tsx does:

   const [state, formAction, pending] = useActionState(
     deleteAccountAction,
     INITIAL_STATE,
   );
   

   The island gets data as props from the page and writes only through the action. Never import serverApi() into it. The build still passes if you do; the call then throws serverApi() must not be called from the browser at runtime.

4. Style it with a colocated <route>.module.scss that starts with @use '../styles/palette' as *;, or reuse app/styles/page-shell.module.scss, the shell the pricing and legal pages share.

5. Link to it. There is no shared site nav component. The landing page's top nav and footer are inline in frontend/app/page.tsx (<nav className={styles.nav}> and <footer>); add a <Link> there. Other pages carry only a logo link back to /. For a public page, add an entry to staticEntries in frontend/app/sitemap.ts.

6. Outside images and scripts are blocked until you allow them. buildCsp() in frontend/proxy.ts sets the Content-Security-Policy on every page:

   "img-src 'self' data: blob: https://images.unsplash.com",
   

   • An image through next/image from another host: add the host to images.remotePatterns in frontend/next.config.ts, never a wildcard.
   • A plain <img> or CSS url() from another host: add the host to img-src in buildCsp().
   • A third-party script: script-src is a per-request nonce plus 'strict-dynamic', so a script runs only if it carries this request's nonce or was loaded by a script that does. Browsers that support 'strict-dynamic' ignore host names in script-src, so adding the script's host there does nothing. Next's own scripts carry the nonce, so a script loaded with next/script runs, and so does everything it loads, with full access to the page. Nothing in frontend/proxy.ts has to change for that, so it is a security decision you make in your page code: load only a script you have chosen to trust. See Troubleshooting.
   • Browser requests go only to this site and the API origin (connect-src).

   A blocked resource shows up as a CSP error in the browser console, not as a build or test failure.

7. Pick the path with the gates in mind. proxy.ts 404s every /backoffice/* path for anyone who is not an admin, so do not put a user page there. For an admin page, see Add a backoffice screen.

8. Run ./verify.sh. The frontend stage runs format, lint, knip, the tests and next build; the build output lists the new route.

What the test run found

• /about with serverApi(), an actions.ts and a client island, plus the nav link and sitemap entry: verify all green, and the build listed ƒ /about.
• Importing serverApi into the client island did not fail the build, which is why step 3 is a rule to follow and not something verify catches.

Related

• Frontend NextAuth Setup - why the token stays server-side
• Consume from the frontend