Skip to main content

Frontend Conventions (Next.js)

Paved Path

  • App Router with route segments (app/)
  • Data fetching: React Query
  • Client state: Zustand (default) + Context for auth/theme
    • Use Redux Toolkit only when ≥2 triggers apply (middleware, heavy selectors, normalized non‑server graphs, persistence, time‑travel)
  • Forms: Formik + Yup
  • Design System: Storybook
  • Accessibility: Manual/basic checks
  • i18n: next-intl
  • Assets: next/image & next/font
  • Errors: error.tsx + not-found.tsx per route segment
  • Performance budgets: LCP < 2.5s, CLS < 0.1, TTI < 3.5s (CI gate)
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body className="min-h-screen bg-white text-slate-900">{children}</body>
    </html>
  );
}
import create from 'zustand';

type UserState = { id?: string; setId: (id?: string) => void };
export const useUser = create<UserState>((set) => ({ id: undefined, setId: (id) => set({ id }) }));

LLM Notes

  • Prefer server components where possible; use client components only when needed (state, effects, refs).

Folder Structure and Responsibilities​

  • Pages/route segments (src/app/**): layout/composition and UX only. Keep them thin.
    • Do not place business logic or direct network calls in pages.
    • Use hooks/services for data fetching and side-effects; pages wire UI + handlers.
  • Feature modules (src/features/<feature>/): colocate domain logic.
    • hooks/: React Query hooks, mutation/query wrappers, side-effects.
    • services/: fetchers/SDK wrappers, pure functions for network I/O.
    • components/: feature-specific UI pieces.
    • types.ts: feature-specific types.
  • Shared UI (src/components/**): presentational, reusable components (no business logic).
  • Context (src/context/**): app-wide providers (auth, theme, integrations state view).
  • Lib (src/lib/**): utilities and clients (firebase, stripe, dates, api helpers).
  • State (src/state/**): Zustand stores and feature flags.

Standard file tree (reference)​

social-poster/
  apps/
    web/                           # Next.js frontend (App Router)
      package.json
      next.config.js
      tsconfig.json
      src/
        app/                       # pages/layouts/route handlers
          (groups)/                # optional route groups
          api/                     # server route handlers
        features/                   # feature modules
          <feature>/
            hooks/
            services/
            components/
            types.ts
        components/
          ui/
        context/
        lib/
        state/
  functions/                        # Firebase Functions (v2) backend
    package.json
    tsconfig.json
    src/
      index.ts
      config.ts
      utils/
      providers/

Conventions:

  • Keep pages thin: wire UI and call hooks; no direct fetch in pages.
  • Prefer features/<feature>/hooks + services over ad-hoc utils.
  • UI-only components belong in components/ (no business logic).
  • Cross-cutting helpers go in lib/; app state in state/; providers in context/.
  • If a page grows beyond simple wiring, extract to src/features/** and keep pages declarative.