SSR and Prefetching

Relevant source files

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

• README.md
• src/react/use-beverage-label-map.ts
• src/vue/use-beverage-label-map.ts
• src/angular/beverage-label-map.service.ts
• src/label-map.ts
• src/types.ts

SSR (Server-Side Rendering) and Prefetching in @cellarnode/beverage-utils are facilitated through standardized TanStack Query options. These utilities allow developers to fetch, cache, and hydrate beverage classification data across different environments, ensuring that human-readable labels are available immediately upon page load without client-side waterfalls.

The system relies on a central classification API to retrieve category and subtype metadata, which is then transformed into a high-performance lookup map. By using staleTime: Infinity, the library optimizes for data that changes infrequently, making it an ideal candidate for prefetching during the server-render cycle or in route loaders.

Sources: README.md:46-48, src/react/use-beverage-label-map.ts:16, src/vue/use-beverage-label-map.ts:16

Query Architecture

The prefetching logic is encapsulated in beverageLabelMapOptions, a function available for React, Vue, and Angular adapters. This function returns a configuration object compatible with TanStack Query's prefetchQuery and fetchQuery methods.

Data Flow for SSR

When performing SSR, the server executes the query function, fetches data from the CellarNode API, and builds the LabelMap. This map is then serialized and sent to the client as part of the initial HTML payload.

This diagram illustrates the sequence of operations required to populate the cache on the server before client hydration.
Sources: src/react/use-beverage-label-map.ts:7-17, README.md:65-69

Framework-Specific Implementation

Each framework provides a standard way to access query options for prefetching.

Prefetching Options

All adapters export a beverageLabelMapOptions(apiBaseUrl) function. This function configures the following:

Property	Value	Description
queryKey	["beverage-classifications"]	Standardized key for cache lookups.
queryFn	async () => Promise<LabelMap>	Fetches data and executes buildLabelMap.
staleTime	Infinity	Prevents unnecessary refetching as classifications are static.

Sources: src/react/use-beverage-label-map.ts:7-18, src/vue/use-beverage-label-map.ts:7-18, src/angular/beverage-label-map.service.ts:6-17

Usage in React and Vue

In React and Vue, the options are typically used within server-side loaders (like Next.js getServerSideProps or TanStack Router loaders) to prime the cache.

// Example for React/Next.js or Vue
import { beverageLabelMapOptions } from "@cellarnode/beverage-utils/react"; // or /vue

async function loader() {
  await queryClient.prefetchQuery(
    beverageLabelMapOptions("https://api.cellarnode.com")
  );
}

Sources: README.md:65-69, README.md:82-84

Usage in Angular

In Angular, the injectBeverageLabelMap service can be used alongside injectQuery to manage the prefetching state within the component tree or route resolvers.

import { beverageLabelMapOptions } from "@cellarnode/beverage-utils/angular";
import { injectQuery } from "@tanstack/angular-query-experimental";

const query = injectQuery(() => 
  beverageLabelMapOptions("https://api.cellarnode.com")
);

Sources: README.md:104-107, src/angular/beverage-label-map.service.ts:19-21

Data Transformation and Serialization

During the prefetching process, the raw API response is transformed into a LabelMap before being stored in the cache. This ensures that the server and client both work with the same optimized data structure.

Classification Data Structure

The source data consists of categories containing subtypes:

This diagram represents the schema of the data fetched from the API during the prefetch step.
Sources: src/types.ts:1-15

The LabelMap Object

The buildLabelMap function iterates through the classification data to produce a flat Record<string, string>. This transformation is critical for SSR as it minimizes the logic required on the client after hydration.

• Category Keys: id -> name (e.g., "wine" -> "Still Wine")
• Subtype Keys: id -> name (e.g., "red" -> "Red Wine")
• Composite Keys: category:subtype -> name (e.g., "wine:red" -> "Red Wine")

Sources: src/label-map.ts:5-14, README.md:33-40

Conclusion

SSR and Prefetching in this library are designed to provide a seamless developer experience by leveraging TanStack Query. By exposing beverageLabelMapOptions, the library allows for efficient server-side data fetching and cache priming, ensuring that beverage labels are rendered instantly without additional network requests on the client.