Skip to main content

Frontend development

The Evolve frontend is a Next.js 15 application with React 19, Tailwind CSS, and TypeScript. It connects to the backend through the GraphQL gateway and supports server-side rendering, static generation, and client-side interactivity.

Project structure​

The frontend lives in frontend/site/ and follows the Next.js App Router conventions:

frontend/site/
├── src/
│   ├── app/              # App Router pages and layouts
│   ├── components/       # Shared UI components
│   ├── generated/        # GraphQL Code Generator output
│   ├── hooks/            # Shared React hooks
│   ├── lib/              # Utilities, i18n config, store config
│   └── messages/         # Translation files per locale
├── public/               # Static assets
└── next.config.ts        # Next.js configuration

Rendering strategy​

The storefront uses a mix of rendering approaches:

  • Static generation with ISR: product pages, category pages, and content pages are statically generated and revalidated on a regular interval (typically 15 minutes)
  • Server-side rendering: pages that depend on user context (cart, account, checkout) render on the server per request
  • Client-side interactivity: add-to-cart actions, search autocomplete, and other interactive elements use client components with optimistic updates

Component approach​

Components follow a headless UI pattern using Radix UI primitives for accessibility, styled with Tailwind CSS and composed in the style of shadcn/ui. This gives you full control over markup and styling while maintaining accessible behavior out of the box.

Forms use React Hook Form with Zod validation schemas. Interactive state (cart updates, wishlist changes) uses React 19's useActionState and useOptimistic hooks for immediate feedback.

Data fetching​

The frontend fetches data from the GraphQL gateway using generated typed queries. GraphQL Code Generator produces TypeScript types from the supergraph schema, so queries are type-safe end to end.

Server components fetch data directly during rendering. Client components use TanStack Query for cache management and background refetching.

Key patterns​

  • Internationalization: translations are managed through next-intl with automatic label extraction. See Translations for details.
  • Testing: components are tested through Storybook with Vitest in browser mode. See Testing for the full strategy.
  • Icons: Lucide React icons with custom icon generation for project-specific assets.