How to Build an AI-Powered E-Commerce PWA with Next.js 15 RSC and LangChain 0.3 for Product Recommendation

pnpx create-next-app@15 ai-ecommerce-pwa --typescript --tailwind --eslint --app --src-dir --import-alias \"@/*\"

cd ai-ecommerce-pwa
pnpm add langchain@0.3 @langchain/openai @langchain/core next-pwa idb
pnpm add -D @types/idb

OPENAI_API_KEY=sk-your-openai-api-key-here

// types/product.ts
export interface Product {
  id: string;
  name: string;
  category: string;
  price: number;
  image: string;
}

// lib/db.ts
import type { Product } from '@/types/product';

/**
 * Mock product database (replace with real PostgreSQL/Prisma in production)
 */
const mockProducts: Product[] = [
  { id: 'p1', name: 'Wireless Headphones', category: 'Electronics', price: 89.99, image: 'https://assets.example.com/products/p1.jpg' },
  { id: 'p2', name: 'Leather Laptop Bag', category: 'Accessories', price: 129.99, image: 'https://assets.example.com/products/p2.jpg' },
  { id: 'p3', name: 'Organic Cotton T-Shirt', category: 'Clothing', price: 24.99, image: 'https://assets.example.com/products/p3.jpg' },
  { id: 'p4', name: 'Stainless Steel Water Bottle', category: 'Home', price: 34.99, image: 'https://assets.example.com/products/p4.jpg' },
  { id: 'p5', name: 'Smart Watch', category: 'Electronics', price: 199.99, image: 'https://assets.example.com/products/p5.jpg' },
  { id: 'p6', name: 'Yoga Mat', category: 'Fitness', price: 29.99, image: 'https://assets.example.com/products/p6.jpg' },
  { id: 'p7', name: 'Coffee Maker', category: 'Home', price: 79.99, image: 'https://assets.example.com/products/p7.jpg' },
  { id: 'p8', name: 'Running Shoes', category: 'Footwear', price: 119.99, image: 'https://assets.example.com/products/p8.jpg' },
  { id: 'p9', name: 'Portable Charger', category: 'Electronics', price: 49.99, image: 'https://assets.example.com/products/p9.jpg' },
  { id: 'p10', name: 'Desk Lamp', category: 'Home', price: 44.99, image: 'https://assets.example.com/products/p10.jpg' },
  { id: 'p11', name: 'Backpack', category: 'Accessories', price: 69.99, image: 'https://assets.example.com/products/p11.jpg' },
  { id: 'p12', name: 'Face Cream', category: 'Beauty', price: 39.99, image: 'https://assets.example.com/products/p12.jpg' },
];

/**
 * Fetch all products from mock DB
 */
export async function getProducts(): Promise {
  // Simulate DB latency (remove in production)
  await new Promise(resolve => setTimeout(resolve, 50));
  return mockProducts;
}

/**
 * Fetch single product by ID
 */
export async function getProductById(id: string): Promise {
  await new Promise(resolve => setTimeout(resolve, 20));
  return mockProducts.find(p => p.id === id);
}

// app/actions/recommendation.ts
import { ChatOpenAI } from '@langchain/openai';
import { PromptTemplate } from '@langchain/core/prompts';
import { StringOutputParser } from '@langchain/core/output_parsers';
import { Product } from '@/types/product';
import { getProducts } from '@/lib/db';

// Initialize OpenAI model with LangChain 0.3 defaults
const model = new ChatOpenAI({
  model: 'gpt-4o-mini', // Cost-effective for high-throughput recs
  temperature: 0.2, // Low temp for consistent, relevant recommendations
  maxRetries: 2, // Handle transient API errors
  timeout: 5000, // 5s timeout to meet p99 latency targets
});

// Prompt template for product recommendations
const recommendationPrompt = PromptTemplate.fromTemplate(`
  You are an e-commerce product recommendation engine. Given a user's browsing history and product catalog, return a JSON array of 3-5 product IDs most relevant to the user.
  User Browsing History: {browsingHistory}
  Product Catalog (id, name, category, price): {productCatalog}
  Return only a valid JSON array of product IDs, no additional text.
`);

// Compile the recommendation chain
const recommendationChain = recommendationPrompt.pipe(model).pipe(new StringOutputParser());

export interface RecommendationInput {
  browsingHistory: string[];
  userId?: string;
}

export interface RecommendationOutput {
  productIds: string[];
  error?: string;
}

/**
 * Server action to generate personalized product recommendations using LangChain 0.3
 * Complies with Next.js 15 RSC constraints (runs only on server)
 */
export async function getRecommendations(input: RecommendationInput): Promise {
  try {
    // Validate input
    if (!input.browsingHistory || input.browsingHistory.length === 0) {
      throw new Error('Browsing history is required for recommendations');
    }

    // Fetch full product catalog from mock DB (replace with real DB in prod)
    const productCatalog = await getProducts();

    // Format catalog for prompt (limit to 20 products to avoid token limits)
    const formattedCatalog = productCatalog
      .slice(0, 20)
      .map(p => ({ id: p.id, name: p.name, category: p.category, price: p.price }))
      .join('\n');

    // Run LangChain recommendation chain
    const rawOutput = await recommendationChain.invoke({
      browsingHistory: input.browsingHistory.join(', '),
      productCatalog: formattedCatalog,
    });

    // Parse and validate output
    let productIds: string[];
    try {
      productIds = JSON.parse(rawOutput);
    } catch (parseError) {
      console.error('Failed to parse LangChain output:', parseError, 'Raw output:', rawOutput);
      // Fallback to popular products if parsing fails
      productIds = productCatalog.slice(0, 3).map(p => p.id);
    }

    // Validate product IDs exist in catalog
    const validProductIds = productIds.filter(id => productCatalog.some(p => p.id === id));
    if (validProductIds.length === 0) {
      // Fallback to top 3 products if no valid IDs
      validProductIds.push(...productCatalog.slice(0, 3).map(p => p.id));
    }

    return { productIds: validProductIds.slice(0, 5) }; // Return max 5 recs
  } catch (error) {
    console.error('Recommendation generation failed:', error);
    return {
      productIds: [],
      error: error instanceof Error ? error.message : 'Failed to generate recommendations',
    };
  }
}

// app/components/ProductRecommendations.tsx
import { getRecommendations } from '@/app/actions/recommendation';
import { ProductCard } from './ProductCard';
import { getProducts } from '@/lib/db';
import { Suspense } from 'react';
import type { Product } from '@/types/product';

/**
 * RSC Server Component: Renders personalized product recommendations
 * Runs on server, no client-side JS required for initial render
 */
export async function ProductRecommendations({ 
  browsingHistory, 
  userId 
}: { 
  browsingHistory: string[]; 
  userId?: string 
}) {
  // Fetch recommendations and product catalog in parallel
  const [recResponse, allProducts] = await Promise.all([
    getRecommendations({ browsingHistory, userId }),
    getProducts(),
  ]);

  // Handle errors from recommendation service
  if (recResponse.error || recResponse.productIds.length === 0) {
    return (

        Recommended For You
        Unable to load personalized recommendations. Here are our top products:

          {allProducts.slice(0, 4).map((product) => (

          ))}


    );
  }

  // Filter products to only recommended ones
  const recommendedProducts = allProducts.filter((product) =>
    recResponse.productIds.includes(product.id)
  );

  return (

      Recommended For You
      }>

          {recommendedProducts.map((product) => (

          ))}



  );
}

/**
 * Client-side wrapper for ProductRecommendations with offline support
 * Uses next-pwa for caching, revalidates on reconnect
 */
'use client';
import { useEffect, useState } from 'react';
import { ProductRecommendations as ServerRecommendations } from './ProductRecommendations';
import { getCachedBrowsingHistory } from '@/lib/offline';

export function ProductRecommendationsClient() {
  const [browsingHistory, setBrowsingHistory] = useState([]);
  const [isOffline, setIsOffline] = useState(!navigator.onLine);

  useEffect(() => {
    // Load browsing history from IndexedDB for offline support
    const loadHistory = async () => {
      const cachedHistory = await getCachedBrowsingHistory();
      setBrowsingHistory(cachedHistory || []);
    };
    loadHistory();

    // Listen for online/offline events
    const handleOnline = () => setIsOffline(false);
    const handleOffline = () => setIsOffline(true);
    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []);

  if (isOffline) {
    return (

        You are offline. Showing cached recommendations.


    );
  }

  return ;
}

// next.config.mjs
import type { NextConfig } from 'next';
import withPWA from 'next-pwa';

const nextConfig: NextConfig = {
  // Enable RSC (default in Next.js 15, but explicit for clarity)
  reactStrictMode: true,
  // Disable x-powered-by header for security
  poweredByHeader: false,
  // Configure image optimization for product images
  images: {
    domains: ['assets.example.com'], // Replace with your product image domain
    formats: ['image/webp'],
  },
};

// PWA configuration with next-pwa
const pwaConfig = withPWA({
  dest: 'public',
  register: true,
  skipWaiting: true,
  // Cache strategies for e-commerce assets
  runtimeCaching: [
    {
      // Cache product API responses for 1 hour
      urlPattern: /^https:\/\/api\.example\.com\/products.*/,
      handler: 'NetworkFirst',
      options: {
        cacheName: 'product-api-cache',
        expiration: {
          maxEntries: 100,
          maxAgeSeconds: 60 * 60, // 1 hour
        },
        cacheableResponse: {
          statuses: [0, 200],
        },
      },
    },
    {
      // Cache product images for 7 days
      urlPattern: /^https:\/\/assets\.example\.com\/products.*/,
      handler: 'CacheFirst',
      options: {
        cacheName: 'product-image-cache',
        expiration: {
          maxEntries: 500,
          maxAgeSeconds: 60 * 60 * 24 * 7, // 7 days
        },
      },
    },
    {
      // Cache recommendation API for 5 minutes
      urlPattern: /^https:\/\/api\.example\.com\/recommendations.*/,
      handler: 'NetworkFirst',
      options: {
        cacheName: 'recommendation-cache',
        expiration: {
          maxEntries: 50,
          maxAgeSeconds: 60 * 5, // 5 minutes
        },
      },
    },
  ],
});

export default pwaConfig(nextConfig);

// lib/offline.ts
import { openDB, type IDBPDatabase } from 'idb';

interface BrowsingHistoryDB extends IDBPDatabase {
  get(key: string): Promise;
  put(key: string, value: string[]): Promise;
}

const DB_NAME = 'ecommerce-pwa-db';
const DB_VERSION = 1;
const BROWSING_HISTORY_KEY = 'browsing-history';

/**
 * Initialize IndexedDB for offline storage
 */
async function initDB(): Promise {
  return openDB(DB_NAME, DB_VERSION, {
    upgrade(db) {
      // Create object store for browsing history if it doesn't exist
      if (!db.objectStoreNames.contains('browsing-history')) {
        db.createObjectStore('browsing-history', { keyPath: 'id' });
      }
    },
  });
}

/**
 * Cache browsing history for offline recommendation generation
 */
export async function cacheBrowsingHistory(history: string[]): Promise {
  try {
    const db = await initDB();
    await db.put('browsing-history', { id: BROWSING_HISTORY_KEY, history });
  } catch (error) {
    console.error('Failed to cache browsing history:', error);
    // Fallback to localStorage if IndexedDB fails
    localStorage.setItem(BROWSING_HISTORY_KEY, JSON.stringify(history));
  }
}

/**
 * Retrieve cached browsing history from IndexedDB or localStorage
 */
export async function getCachedBrowsingHistory(): Promise {
  try {
    const db = await initDB();
    const record = await db.get('browsing-history', BROWSING_HISTORY_KEY);
    return record?.history || [];
  } catch (error) {
    console.error('Failed to retrieve cached browsing history:', error);
    // Fallback to localStorage
    const cached = localStorage.getItem(BROWSING_HISTORY_KEY);
    return cached ? JSON.parse(cached) : [];
  }
}

/**
 * Clear cached data on logout or user request
 */
export async function clearOfflineCache(): Promise {
  try {
    const db = await initDB();
    await db.clear('browsing-history');
    localStorage.removeItem(BROWSING_HISTORY_KEY);
  } catch (error) {
    console.error('Failed to clear offline cache:', error);
  }
}

// Listen for page visits to cache browsing history
if (typeof window !== 'undefined') {
  const cachePageVisit = (productId: string) => {
    getCachedBrowsingHistory().then((history) => {
      const updatedHistory = [productId, ...history.filter(id => id !== productId)].slice(0, 20);
      cacheBrowsingHistory(updatedHistory);
    });
  };

  // Expose to window for product page to call
  (window as any).cachePageVisit = cachePageVisit;
}

// Stream LangChain response instead of blocking invoke
const stream = await recommendationChain.stream({
  browsingHistory: input.browsingHistory.join(', '),
  productCatalog: formattedCatalog,
});
for await (const chunk of stream) {
  // Stream chunk to client via RSC
}

// Cache product images for 7 days
{
  urlPattern: /^https:\/\/assets\.example\.com\/products.*/,
  handler: 'CacheFirst',
  options: { maxAgeSeconds: 60 * 60 * 24 * 7 }
}

// Validate LangChain output product IDs
const validProductIds = productIds.filter(id => 
  productCatalog.some(p => p.id === id)
);
if (validProductIds.length === 0) {
  validProductIds.push(...productCatalog.slice(0, 3).map(p => p.id));
}

ai-ecommerce-pwa/
├── app/
│   ├── actions/
│   │   └── recommendation.ts
│   ├── components/
│   │   ├── ProductCard.tsx
│   │   ├── ProductRecommendations.tsx
│   │   └── Cart.tsx
│   ├── api/
│   │   └── products/
│   │       └── route.ts
│   ├── page.tsx
│   ├── layout.tsx
│   └── globals.css
├── lib/
│   ├── db.ts
│   ├── offline.ts
│   └── types.ts
├── public/
│   ├── manifest.json
│   └── icons/
├── next.config.mjs
├── package.json
├── pnpm-lock.yaml
└── tsconfig.json