Storefront Production Optimization Tips

In this guide, you’ll find tips useful when optimizing a storefront for production.

Summary

When building a storefront, you want to ensure that it loads quickly and efficiently for your users. You can achieve this by implementing many optimizations, including:

1. Implement appropriate rendering strategies.
2. Use fetching libraries optimized for performance and caching like TanStack Query.
3. Optimize queries to fetch only the necessary data.
4. Implement optimistic UI updates for cart operations.

This guide explains how to implement these optimizations. You can follow it regardless of the frontend framework you use.

Choose the Right Rendering Strategy

A rendering strategy defines how your frontend framework renders pages. The most common strategies are:

1. Server-Side Rendering (SSR): Pages are rendered on the server for each request. Ideal for dynamic content that changes frequently.
2. Static Site Generation (SSG): Pages are pre-rendered at build time. Best suited for content that doesn't change often.
3. Incremental Static Regeneration (ISR): A hybrid approach where pages are pre-rendered at build time but can be updated at runtime. Perfect for content that changes occasionally.
4. Client-Side Rendering (CSR): Pages are rendered in the browser using JavaScript. Optimal for highly interactive applications.

For your storefront, we recommend using different strategies for different pages:

On Next.js App Router, follow Build a Next.js Storefront: SDK calls in src/lib/data/*.ts, cache tags from _aiminaabee_cache_id, revalidate carts, customers, and fulfillment after mutations. TanStack Query below is optional for client islands, not a replacement for the server data layer.

Use TanStack Query

When fetching data from your Aiminaabee backend, consider using a fetching library optimized for performance and caching. There are many options available, but one of the most popular is TanStack Query.

TanStack Query is a powerful data-fetching library that provides features like caching, background updates, and optimistic updates.

By using TanStack Query, you can significantly improve your storefront's performance by reducing the number of network requests and ensuring that your UI is always up-to-date.

Learn how to get started with TanStack Query in their official documentation. Their documentation also has guidance on advanced usage and best practices.

Stale Time Configuration

When configuring TanStack Query, you can set the staleTime option to control how long data is considered fresh. However, avoid setting staleTime for highly dynamic data like product prices and stock levels.

Set the staleTime globally, then override it to 0 for specific queries that fetch dynamic data.

For example:

1// queryClient.ts
2import { QueryClient } from "@tanstack/react-query"
3
4const queryClient = new QueryClient({
5  defaultOptions: {
6    queries: {
7      staleTime: 1000 * 60 * 5, // 5 minutes
8    },
9  },
10})
11
12export default queryClient
13
14// product.ts
15// Used in components that are children of QueryClientProvider
16import { useQuery } from "@tanstack/react-query"
17import { sdk } from "../lib/sdk"
18
19export const useProduct = (id: string) => {
20  return useQuery(["product", id], async () => {
21    const response = await sdk.store.products.retrieve("us", id)
22    return response.data
23  })
24}
25
26export const useProductPrice = (id: string) => {
27  return useQuery(
28    ["product-price", id],
29    async () => {
30      const response = await sdk.store.products.retrieve("us", id, {
31        fields: "*variants.calculated_price",
32      })
33      return response.data.variants[0].price
34    },
35    {
36      staleTime: 0, // Always fetch fresh data
37    }
38  )
39}

Invalidate Queries

When performing mutations that change cached data, invalidate the relevant queries to ensure that the UI reflects the latest data.

For example, when adding an item to the cart, you should invalidate the cart query:

1import { useMutation, useQueryClient } from "@tanstack/react-query"
2import { sdk } from "../lib/sdk"
3
4export const useAddToCart = () => {
5  const queryClient = useQueryClient()
6
7  return useMutation(
8    async (item) => {
9      await sdk.store.cart.createLineItem("us", "cart_id", item)
10    },
11    {
12      onSuccess: () => {
13        queryClient.invalidateQueries(["cart"])
14      },
15    }
16  )
17}

Optimize Fetched Data

When fetching data from your Aiminaabee backend, optimize your queries to fetch only the necessary data in the context of a component or page. This reduces the response size and time, improving your storefront's performance.

Aiminaabee's API routes accept a fields parameter that allows you to specify which fields and relations to include in the response.

For example, if you only need the product's id, title, and variants.calculated_price, you can specify this in the fields parameter:

1const response = await sdk.store.products.retrieve("us", "product_id", {
2  fields: "*variants.calculated_price, id, title",
3})

This query will return only the specified fields, reducing the response size and improving performance.

If you're using TanStack Query, make sure to include the fields parameter in the query key to ensure that different field selections are cached separately:

1const useProduct = (id: string, fields?: string) => {
2  return useQuery({
3    queryKey: ["product", id, fields],
4    queryFn: async () => {
5      const response = await sdk.store.products.retrieve("us", id, { fields })
6      return response.data
7    },
8  })
9}

Learn more about the fields parameter in the Store API reference.

Each Store API route restricts the fields that you can request through an allowed-fields list. If you request a field that the route doesn't allow, Aiminaabee omits it from the response without returning an error.

To allow extra fields, such as a custom relation, override the route's allowed fields as explained in the Allowed Fields documentation.

Implement Optimistic UI Updates

When performing mutations that may take some time, you can implement optimistic UI updates to provide a better user experience. This means updating the UI immediately, assuming the mutation will succeed, then rolling back if it fails.

For example, if you're using TanStack Query, you can implement the following optimistic cart-update utilities and then use them in cart mutations:

optimistic-cart.ts

1import { HttpTypes } from "@aiminaabeejs/types"
2import { QueryClient } from "@tanstack/react-query"
3import { queryKeys } from "@/lib/utils/common/query-keys"
4
5/**
6 * Utility functions for optimistic cart updates
7 */
8
9export interface OptimisticCartItem {
10  id: string;
11  variant_id: string;
12  quantity: number;
13  title: string;
14  thumbnail?: string | null;
15  product_title?: string;
16  variant_title?: string;
17  product?: {
18    id: string;
19    title: string;
20  };
21  variant?: {
22    id: string;
23    title: string;
24  };
25  unit_price: number;
26  total: number;
27  isOptimistic?: boolean;
28}
29
30export interface OptimisticCart extends HttpTypes.StoreCart {
31  isOptimistic?: boolean;
32}
33
34/**
35 * Creates an optimistic cart item for immediate UI updates during add to cart operations.
36 * Generates a temporary item with calculated pricing before the server response.
37 *
38 * @param variant - The product variant being added to cart
39 * @param product - The product object containing title and thumbnail
40 * @param quantity - The quantity to add (defaults to 1)
41 * @returns Optimistic cart item with temporary ID and calculated totals
42 *
43 * @example
44 *

use-cart.ts

1import {
2  addToCart,
3  applyPromoCode,
4  createCart,
5  deleteLineItem,
6  removePromoCode,
7  retrieveCart,
8  updateCart,
9  updateLineItem,
10} from "@/lib/data/cart"
11import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
12import { queryKeys } from "@/lib/utils/common/query-keys"
13import {
14  addItemOptimistically,
15  createOptimisticCartItem,
16  getCurrentCart,
17  rollbackOptimisticCart,
18  updateLineItemOptimistically,
19  removeLineItemOptimistically,
20  createOptimisticCart,
21} from "@/lib/utils/cart/optimistic-cart"
22import { HttpTypes } from "@aiminaabeejs/types"
23
24/**
25 * React hook to fetch the current cart with optimistic updates and caching.
26 * Uses Tanstack Query with no stale time to ensure fresh data.
27 *
28 * @param fields - Optional fields to include in the cart response
29 * @returns Tanstack Query result object with cart data, loading, and error states
30 *
31 * @example
32 *

With this setup, your cart mutations will provide immediate UI feedback with optimistic updates, while ensuring that the cart data is always fresh and consistent with the backend.