Frontend SSR & Build Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• assets/entry.client.tsx
• assets/entry.server.tsx
• assets/router.tsx
• vite.config.ts
• assets/package.json
• assets/src/relay/fetch-graphql.ts
• assets/stylex-plugin.ts
• ARCHITECTURE.md

Introduction

The ProductCompare frontend is built as a high-performance React application utilizing Server-Side Rendering (SSR) to ensure fast initial page loads and SEO compatibility. The architecture leverages Bun as the runtime and Vite as the primary build tool, integrating React Router for navigation and Relay for GraphQL data management.

The system is designed as a hybrid model where Phoenix (the Elixir backend) serves as the session authority and GraphQL provider, while the React application handles the presentation layer and browser UX. This documentation covers the build pipeline, the SSR lifecycle, and the network layer used to bridge the client and server environments. Sources: ARCHITECTURE.md:14-16, assets/package.json:1-30

Build Pipeline & Configuration

The project uses Vite to orchestrate the build process for both the client-side bundle and the SSR server bundle. The build is split into two distinct outputs to support the different requirements of the browser and the server environments.

Build Scripts

The package.json defines a multi-stage build process:

• Client Build: Standard Vite build for browser assets.
• Server Build: A specialized Vite build targeting SSR, using src/entry.server.tsx as the entry point and outputting to dist/server. Sources: assets/package.json:7-16

Styling & Optimization

The project integrates @stylexjs/stylex for type-safe CSS-in-JS. A custom Vite plugin configuration (reactWithStyleX) handles the Babel transformations required for StyleX during both development and production builds. Sources: assets/stylex-plugin.ts:7-29, assets/package.json:33

Tool	Purpose	Source
Vite	Module bundling and dev server	assets/package.json:23
React Router 7	Routing and SSR data loading	assets/package.json:38
Relay	GraphQL data fetching and caching	assets/package.json:37
StyleX	Atomic CSS-in-JS	assets/stylex-plugin.ts:1-29

SSR Architecture

The Server-Side Rendering flow is managed by entry.server.tsx, which converts the React component tree into a readable stream for the browser.

The SSR Lifecycle

When a request hits the server:

1. Context Initialization: An SSRContext is created, containing the original Request and cookies.
2. Relay Environment: A per-request Relay environment is instantiated to ensure data isolation.
3. Static Routing: React Router's createStaticHandler matches the URL and prepares the data routes.
4. Streaming: renderToReadableStream generates the HTML, allowing the browser to start parsing the document before the full render is complete.

SSR Context & Cookie Forwarding

Because the backend uses cookie-backed sessions, the SSR layer must explicitly forward cookies from the user's browser to the internal GraphQL fetch calls. The fetchGraphQL utility extracts the cookieString from the SSRContext and injects it into the headers of the outgoing POST request to /api/graphql. Sources: assets/src/relay/fetch-graphql.ts:25-50, ARCHITECTURE.md:14-16

Client Hydration

The client-side entry point (entry.client.tsx) is responsible for "hydrating" the server-rendered HTML, making it interactive.

Network & Data Layer

The network layer is unified through the fetchGraphQL function, which resolves the API endpoint based on the environment.

Endpoint Resolution

The system dynamically determines the GraphQL endpoint:

• Production: Uses the VITE_API_BASE_URL environment variable.
• Development: Defaults to http://localhost:4000 (the standard Phoenix port) or derives the host from window.location.origin if available.

Request Configuration

• Browser: Sets credentials: "include" to allow the browser to automatically manage session cookies.
• SSR: Sets credentials: undefined because cookies are manually injected into the headers from the SSRContext.

Sources: assets/src/relay/fetch-graphql.ts:54-95, assets/src/relay/tests/fetch-graphql.test.ts:4-30

Conclusion

The ProductCompare Frontend SSR & Build Architecture provides a robust foundation for a modern web application. By combining Vite's efficient build pipeline with React Router's SSR capabilities and a custom Relay network layer, the system achieves a seamless transition from server-rendered content to a fully interactive client-side experience, while maintaining strict session security through the Phoenix backend.