React (Web)

Next.js 15 platform with a pnpm + Turborepo monorepo, ShadCn/Radix component library, TanStack Query data layer, and server-side auth — giving you a fully wired web application foundation.

What It Does

The React web platform lives in sdks-react alongside React Native. It provides:

~24 shared Foundation packages covering auth, data, theming, error handling, files, messaging, notifications, maps, search, and more
~45 web UI components built on Radix primitives with Tailwind v4 and CVA variants
A showcase starter app (Next.js 15) demonstrating every Foundation SDK with mock mode for offline development
CI/CD pipelines deploying to GCP Cloud Run with Storybook on Firebase Hosting

Key Capabilities

Capability	Description
Next.js 15 + App Router	Server-side rendering with Turbopack, file-based routing, and server-side auth middleware
pnpm + Turborepo	Dependency-aware build orchestration with task caching across ~24 packages
ShadCn/Radix UI Library	~45 accessible components with CVA variants, dark mode, and Tailwind v4
TanStack Query	Declarative data fetching with caching, invalidation, realtime subscriptions, and infinite scroll
Platform Abstraction	`IRepository`, `IAuthService`, `IStorage` interfaces — code against abstractions, swap implementations
Firebase Integration	Full wrappers for Auth, Firestore, Storage, Remote Config, Analytics, and App Check
Server-Side Auth	`next-firebase-auth-edge` middleware validates tokens on every request with role-based redirects
Mock Mode	`MockRepository` swaps in for Firestore — fully offline frontend development
Dependency Injection	Awilix-style container with `useRegisterProviders` and `useContainer` hooks
Changesets	Automated versioning and publishing to GitHub Packages
Storybook	38 documented stories with a11y testing and Chromatic visual regression

How It Fits Together


┌─────────────────────────────────────────────┐
│  Product App (apps/web — Next.js 15)         │
│  Providers → Pages → Feature Components      │
├─────────────────────────────────────────────┤
│  Feature SDKs                                │
│  auth · user · files · messaging ·           │
│  notifications · maps · multimedia ·         │
│  access · registration · search · config     │
├─────────────────────────────────────────────┤
│  Foundation APIs                             │
│  platform · firebase · rest-client ·         │
│  di · error · theme · tenant-bootstrap       │
├─────────────────────────────────────────────┤
│  UI Components (@engineering11/react-ui)     │
│  ~45 ShadCn/Radix components + Tailwind v4   │
└─────────────────────────────────────────────┘

Foundation packages define abstract interfaces. Firebase packages provide concrete implementations. Feature SDKs compose them into domain capabilities. The product app wires everything together through nested providers.

Architecture

Provider Composition

The app composes Foundation capabilities through ordered providers:


<PlatformProvider platformContainer={platformContainer}>
  <PlatformAuthProvider user={user}>
    <TanstackQueryWebFirebaseProvider>
      <FirebaseProvider {...firebaseConfig}>
        <PermissionProvider>
          <ConfigProvider>
            <UIComponentProvider linkComponent={NextLink}>
              <FilesProvider uploadConfig={uploadConfig}>
                {children}
              </FilesProvider>
            </UIComponentProvider>
          </ConfigProvider>
        </PermissionProvider>
      </FirebaseProvider>
    </TanstackQueryWebFirebaseProvider>
  </PlatformAuthProvider>
</PlatformProvider>

Data Fetching

All data flows through TanStack Query hooks wrapping the IRepository abstraction:


Component → useFeatureHook() → useDocumentQuery / useMutation
  → IRepository._get / _query → BaseFirestoreRepository (injected via DI)

Hooks include useDocumentQuery, useCollectionQuery, useCollectionInfiniteQuery, and mutation hooks for add/update/delete/set/transaction/batch. All support realtime subscriptions via _getValueChanges and _queryValueChanges.

Shared Code with React Native

Packages split exports by platform:

Export	Target	Content
`"."` (lib)	Web + Mobile	Models, services, repositories, utilities — pure TypeScript
`"./react"`	Web only	React hooks, providers, web components
`"./rn"`	Mobile only	RN hooks, providers, native components

What You Don’t Have to Build

Platform abstraction layer (repository, auth, storage interfaces)
Firebase integration (Auth, Firestore, Storage, Remote Config, Analytics, App Check)
TanStack Query hooks for Firestore (documents, collections, infinite scroll, aggregations, realtime)
Server-side auth middleware with role-based redirects
REST client with auth token injection, retry, and tenant headers
~45 accessible UI components with dark mode and Tailwind v4
Structured error handling with Rollbar integration
White-label tenant theming with runtime brand switching
DI container with provider hooks
Storybook with 38 stories, a11y testing, and Chromatic visual regression
Mock mode for fully offline frontend development
CI/CD to Cloud Run with automated Storybook deployments
Package publishing with Changesets to GitHub Packages

What You Build

Product-specific screens, features, and business logic
Product-specific data models (persisted via the repository layer)
Custom navigation/routing and page hierarchy
Brand theming overrides per tenant
Feature flag configuration
Product-specific notification handlers
Environment-specific configuration (API endpoints, keys)

Next Steps

React Native — The mobile counterpart sharing the same Foundation
Platforms Overview — Compare all frontend platforms
Architecture — Cross-platform architecture patterns
Capabilities — Authentication, theming, error handling, state, and more