GameStore Frontend (Next.js 16 App Router)

TL;DR

GameStore Frontend (Next.js 16 App Router)

• Built a high-performance Steam-inspired game store frontend with Next.js 16 (App Router), featuring responsive dark UI, infinite scroll catalog with 100+ procedurally generated games, and debounced client-side search.

• Implemented hybrid rendering strategy: async server components for core pages + client islands for interactive elements (cart, forms), with IntersectionObserver-based lazy loading and next/image optimization for localized asset delivery.

• Engineered secure, server-first state management: HTTP-only-style session cookies read server-side, signed cart cookies with server actions + optimistic UI updates, and client-side form validation before server submission.

• Delivered full internationalization (English/Bahasa Indonesia) via language-prefixed routing (/{lang}/) with localized metadata, translations, and server-side locale resolution.

• Established comprehensive QA: Vitest for unit testing hooks/state/i18n, Playwright for cross-browser E2E flows (Chrome/Firefox/Safari), plus auto-formatting CI on merge.

• Tech Stack: Next.js 16 (Turbopack), React 19, Tailwind CSS 4, Bun runtime, React Context + Server Actions, mock API layer for auth/catalog/checkout.

• Outcome: Production-ready storefront architecture balancing SSR performance, client interactivity, and developer experience — with detailed ADRs, HLD/LLD docs, and environment-aware configuration for debug/staging/prod workflows.

A modern, high-performance Game Store frontend built with Next.js 16 (App Router), mimicking the iconic Steam Store aesthetic and functionality.

For live demo, visit: https://dm-gmstr.prothegee.dev/

Key Features

• Steam-Inspired UI: High-fidelity dark theme with responsive layouts for desktop and mobile.
• Internationalization (I18n): Full support for English (en) and Bahasa Indonesia (id) using language-prefixed routing (/{lang}/).
• Infinite Store Catalog: 100+ unique procedurally generated game entries with localized metadata.
• Smart Search: Debounced, client-side search filtering across titles and tags.
• Lazy Loading: Performance-optimized infinite scroll implementation on the store page using IntersectionObserver.
• Hybrid Rendering: Mix of async server components for core pages and 'use client' for interactive islands and the infinite-scroll store.
• Secure Session: Auth managed via HTTP-only-style cookie, read server-side on every request.
• Server-Side Cart: Cart persisted in a signed cookie, hydrated server-side on layout load, updated via server actions with optimistic client-side feedback.
• Optimistic UI: Cart mutations apply instantly on the client and call server actions in the background.
• Client-Side Form Validation: Login and register forms validate fields before the server action fires, with inline error messages.
• Image Optimization: Utilizes next/image with remote patterns for high-performance localized asset delivery.
• Mock Integration: Ready-to-use mock API layer for account management, product catalogs, and checkout flows.
• Environment Management: Multi-environment support (debug, staging, prod) via unified environment variables.

Technical Stack

• Framework: Next.js 16 (App Router, Turbopack)
• Library: React 19
• Styling: Tailwind CSS 4
• Testing: Vitest + Playwright
• State Management: React Context + Server Actions + Optimistic UI
• Runtime: Bun (Recommended) or Node.js

Documentation

Detailed technical documentation is available in the docs/ directory:

Core Architecture

• Project Overview: High-level goals, core mandates, and project structure.
• High-Level Design (HLD): System architecture, routing flows, and service integration.
• Low-Level Design (LLD): Path definitions, component mapping, and API logic.
• Hybrid Architecture: Detailed breakdown of the server-first hybrid strategy (SSR + streaming + client islands).

Feature Specifications

• Authentication: User registration, login lifecycle, and profile management.
• Internationalization: Implementation details for multi-language support.
• Store & Checkout: Game browsing, server-side cart, and purchase flows.

Exceptions & Compatibility

• Exceptions: Known third-party extension conflicts and workarounds.
• Importants: Critical development notes and troubleshooting history.

Quality Assurance

• Unit Testing (Vitest): Strategy for testing hooks, state, and translations.
• E2E Testing (Playwright): Cross-browser automation for core user flows (Chrome, Firefox, Safari).

CI/CD

• Format on Merge: Auto-formats code with ESLint on every merge to main.

Decisions & History

• Architecture Decision Records (ADR): Documented architectural choices and their rationales.

Getting Started

Prerequisites

• Bun or Node.js (v18+)

Installation

1. Clone the repository.
2. Install dependencies:

   bun install

3. Copy the environment template and configure:

   cp .env.template .env

Running Debug Server

bun dev

Open http://localhost:9007 to see the result.

Running Tests

Detailed instructions available in the Vitest and Playwright documentation.

bun run test              # Run unit tests (Vitest)
bun run test:e2e          # Run all E2E tests (cross-browser)
bun run test:e2e --project=chromium   # Chromium only
bun run test:e2e --project=firefox    # Firefox only

Project Structure

├── app/                  # Next.js App Router (localized pages)
│   └── [lang]/
│       ├── layout.tsx    # Server layout — reads session + cart from cookies
│       ├── store/        # Store page with Suspense streaming
│       ├── game/[id]/    # Game detail — AddToCartButton (client island)
│       ├── login/        # Server page + LoginForm (client validation)
│       ├── register/     # Server page + RegisterForm (client validation)
│       ├── cart/         # Cart page (client — reads CartProvider)
│       ├── checkout/     # Checkout page (client)
│       └── profile/      # Server page — server-side auth guard
├── components/           # Shared UI components (Navbar, GameCard, etc.)
├── docs/                 # Technical documentation & ADRs
├── lib/
│   ├── api/
│   │   ├── account.ts    # Auth server actions (login, logout, getSession)
│   │   ├── cart.ts       # Cart server actions (getCart, addToCartAction, …)
│   │   ├── auth-context.tsx  # AuthProvider (client)
│   │   └── dummy-data.ts # Mock game catalog
│   ├── hooks/
│   │   └── useCart.tsx   # CartProvider — optimistic state + server actions
│   └── i18n/             # Localization (translations, context, server util)
├── public/               # Static assets
└── tests/
    ├── cart.test.tsx     # useCart hook unit tests
    ├── i18n.test.ts      # Translation key parity tests
    ├── setup.ts          # jsdom mocks (next/navigation, next/headers)
    └── e2e/
        └── store.spec.ts # Playwright full-flow E2E tests

Notes

See .TODO.md for remaining tasks.

Preview/Screeshot

---

end of readme