Page Structure

Source: .agents/references/coding-standard/page-structure.md

Content

Page Structure

Use this guidance when adding new pages, substantially refactoring page-owned code, extracting shared UI, adding API/service contracts, or creating shared utilities.

This standard applies to new and substantially changed work. Do not migrate existing legacy page layouts only to satisfy this document unless the user explicitly asks for that migration.

Before creating files

• Search for existing implementations before adding a new component, service, hook, utility, type, or page helper.
• Prefer reusing or extending established code when it matches the requirement and does not create awkward coupling.
• Check nearby page files first, then shared folders:
  • Page-local files under src/pages/{specific-page}/
  • Shared components under src/components/
  • Shared services under src/services/
  • Shared utilities under src/utility/
  • Shared hooks under src/hooks/
  • Shared types under src/types/
• Use rtk rg or rtk find when RTK is available. If RTK is unavailable, use plain rg or find.
• Record the reuse decision in implementation notes or review summaries for large changes.

New pages

• Put new user-facing pages under src/pages/{specific-page}/.
• Put the primary page implementation in src/pages/{specific-page}/index.page.tsx.
• Prefer TypeScript for new page files:
  • .tsx for React files with JSX.
  • .ts for constants, types, utilities, hooks, and services.
• Keep Next.js dynamic route folder names when the route requires them, for example src/pages/[communityLink]/.
• API routes still belong under src/pages/api/. Do not move Next API route handlers into src/services/.

Page-local code

Use page-local files when code is specific to one page or route family.

• Page-owned components: src/pages/{specific-page}/components/
• Page-owned constants: src/pages/{specific-page}/constants.ts
• Page-owned shared types: src/pages/{specific-page}/types.ts
• Page-owned helper functions: src/pages/{specific-page}/utils.ts

Do not create a page-local abstraction if only one component uses it and keeping it inline is clearer. Extract when it improves readability, supports multiple page files/components, or matches an existing local pattern.

Shared components

• Put reusable UI components under src/components/.
• Move a component to src/components/ only when it is genuinely shared across pages or product areas.
• Keep page-specific UI under src/pages/{specific-page}/components/ until there is real cross-page reuse.
• Before adding a shared component, search for similarly named components, matching UI patterns, and existing NPL/component-library options.
• Avoid thin re-export/index files; put the implementation in the primary component file.

Services and API contracts

• Put API contracts, service-facing request/response types, and service modules under src/services/.
• Keep UI-specific view models and page-only derived types in the relevant page types.ts.
• Service callers should use the repo's { data, error } service response pattern and follow .agents/rules/no-try-catch-service-api.mdc.
• Do not hide a service boundary inside a page utility when the code represents a reusable API contract.

Shared utilities

• Put reusable, non-UI utility code under src/utility/.
• Keep page-only helpers in src/pages/{specific-page}/utils.ts.
• Before adding a utility, search for existing helpers by behavior and domain terms, not only by the desired function name.
• Prefer small, typed functions with explicit inputs and return values.

Large-change checklist

For substantial feature work, record these decisions before implementation starts:

• Which files or folders are page-local.
• Which pieces are shared and why they belong in src/components/, src/services/, or src/utility/.
• What duplication search was performed.
• Which existing code will be reused or extended.
• Which task owner or worktree owns each write scope when using coordinated implementation.