Server-Side Usage

Overview

The Refine SDK works in server-side environments including Node.js, serverless functions (AWS Lambda, Vercel), and SSR frameworks (Next.js, Nuxt).

Server Configuration

import { Refine } from '@refine-ai/sdk';

const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: process.env.REFINE_ORG_ID,
  catalogId: process.env.REFINE_CATALOG_ID,
  applicationType: 'server',
  events: {
    persistence: 'memory'  // No localStorage on server
  }
});

Key differences from client-side:

Setting	Client	Server
`applicationType`	`'web'`	`'server'`
`events.persistence`	`'localStorage'`	`'memory'`
Identity	Auto-managed	Explicit

Next.js

Server Components (App Router)

// app/search/page.tsx
import { refine } from '@/lib/refine';

export default async function SearchPage({
  searchParams
}: {
  searchParams: { q?: string }
}) {
  const query = searchParams.q || '';
  
  if (!query) {
    return <SearchForm />;
  }

  const results = await refine.search.text({
    query,
    topK: 24
  });

  return (
    <div>
      <SearchForm initialQuery={query} />
      <ProductGrid products={results.results} />
    </div>
  );
}

API Routes

// app/api/search/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { refine } from '@/lib/refine';

export async function GET(request: NextRequest) {
  const query = request.nextUrl.searchParams.get('q');
  
  if (!query) {
    return NextResponse.json({ error: 'Query required' }, { status: 400 });
  }

  try {
    const results = await refine.search.text({
      query,
      topK: parseInt(request.nextUrl.searchParams.get('limit') || '24')
    });

    return NextResponse.json(results);
  } catch (error) {
    console.error('Search error:', error);
    return NextResponse.json({ error: 'Search failed' }, { status: 500 });
  }
}

getServerSideProps (Pages Router)

// pages/search.tsx
import { refine } from '@/lib/refine';
import type { GetServerSideProps } from 'next';

export const getServerSideProps: GetServerSideProps = async (context) => {
  const query = context.query.q as string;
  
  if (!query) {
    return { props: { results: null, query: '' } };
  }

  try {
    const results = await refine.search.text({ query, topK: 24 });
    return { 
      props: { 
        results: results.results,
        totalResults: results.totalResults,
        query 
      } 
    };
  } catch (error) {
    return { props: { results: [], query, error: 'Search failed' } };
  }
};

Client-Side Hydration

Server-render search results, then hydrate for interactivity:

// lib/refine.ts
import { Refine } from '@refine-ai/sdk';

// Server instance
export const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY!,
  organizationId: process.env.REFINE_ORG_ID!,
  catalogId: process.env.REFINE_CATALOG_ID!,
  applicationType: 'server',
  events: { persistence: 'memory' }
});

// Client instance (created dynamically)
export function createClientRefine() {
  return new Refine({
    apiKey: process.env.NEXT_PUBLIC_REFINE_API_KEY!,
    organizationId: process.env.NEXT_PUBLIC_REFINE_ORG_ID!,
    catalogId: process.env.NEXT_PUBLIC_REFINE_CATALOG_ID!,
    applicationType: 'web'
  });
}

// components/SearchResults.tsx
'use client';

import { useEffect, useState } from 'react';
import { createClientRefine } from '@/lib/refine';

export function SearchResults({ 
  initialResults, 
  query 
}: { 
  initialResults: any[]; 
  query: string;
}) {
  const [refine] = useState(() => createClientRefine());

  useEffect(() => {
    // Track the search on client
    if (initialResults.length > 0) {
      const context = refine.events.trackSearch(query, initialResults, {
        surface: 'search_results',
        totalResults: initialResults.length
      });

      // Set up click tracking
      // ...
    }
  }, [query, initialResults]);

  return (
    <div className="product-grid">
      {initialResults.map((product, index) => (
        <ProductCard 
          key={product.productId} 
          product={product} 
          position={index}
        />
      ))}
    </div>
  );
}

AWS Lambda

// handler.ts
import { Refine } from '@refine-ai/sdk';

// Initialize outside handler for connection reuse
const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY!,
  organizationId: process.env.REFINE_ORG_ID!,
  catalogId: process.env.REFINE_CATALOG_ID!,
  applicationType: 'server',
  events: { persistence: 'memory' }
});

export const handler = async (event: any) => {
  const query = event.queryStringParameters?.q;
  
  if (!query) {
    return {
      statusCode: 400,
      body: JSON.stringify({ error: 'Query required' })
    };
  }

  try {
    const results = await refine.search.text({ query, topK: 24 });
    
    return {
      statusCode: 200,
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(results)
    };
  } catch (error) {
    console.error('Search error:', error);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: 'Search failed' })
    };
  }
};

Vercel Edge Functions

// api/search.ts
import { Refine } from '@refine-ai/sdk';

export const config = {
  runtime: 'edge'
};

const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY!,
  organizationId: process.env.REFINE_ORG_ID!,
  catalogId: process.env.REFINE_CATALOG_ID!,
  applicationType: 'server',
  events: { persistence: 'memory' }
});

export default async function handler(request: Request) {
  const url = new URL(request.url);
  const query = url.searchParams.get('q');
  
  if (!query) {
    return new Response(JSON.stringify({ error: 'Query required' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' }
    });
  }

  const results = await refine.search.text({ query, topK: 24 });
  
  return new Response(JSON.stringify(results), {
    headers: { 'Content-Type': 'application/json' }
  });
}

Identity on Server

On the server, you need to manage identity explicitly:

// For user-based recommendations
export async function getUserRecommendations(userId: string) {
  refine.identify(userId);
  
  const recs = await refine.recs.forUser({
    configId: 'personalized',
    topK: 12
  });
  
  return recs;
}

// For server-side purchase tracking
export async function trackPurchase(userId: string, order: Order) {
  refine.identify(userId);
  
  refine.events.trackPurchase({
    orderId: order.id,
    value: order.total,
    currency: order.currency,
    items: order.items.map(item => ({
      itemId: item.productId,
      quantity: item.quantity,
      unitPrice: item.unitPrice
    }))
  });

  await refine.events.flush();
}

Caching Recommendations

Cache recommendations for performance:

import { LRUCache } from 'lru-cache';

const recsCache = new LRUCache<string, any>({
  max: 500,
  ttl: 1000 * 60 * 5  // 5 minutes
});

export async function getCachedSimilarItems(productId: string) {
  const cacheKey = `similar:${productId}`;
  
  let results = recsCache.get(cacheKey);
  if (results) {
    return results;
  }

  results = await refine.recs.similarItems({
    anchorId: productId,
    topK: 8
  });

  recsCache.set(cacheKey, results);
  return results;
}

Error Handling on Server

import { 
  RefineRateLimitError, 
  RefineServerError 
} from '@refine-ai/sdk';

export async function handleSearchRequest(query: string) {
  try {
    return await refine.search.text({ query, topK: 24 });
  } catch (error) {
    if (error instanceof RefineRateLimitError) {
      // Return 429 to let client handle retry
      throw { status: 429, retryAfter: error.retryAfter };
    }
    
    if (error instanceof RefineServerError) {
      // Log and return graceful error
      console.error('Refine server error:', error);
      throw { status: 503, message: 'Search temporarily unavailable' };
    }
    
    throw error;
  }
}

Testing

Mock the SDK for tests:

// __mocks__/@refine-ai/sdk.ts
export class Refine {
  search = {
    text: jest.fn().mockResolvedValue({
      results: [
        { productId: 'sku_001', title: 'Test Product', price: 99.99 }
      ],
      totalResults: 1
    })
  };
  
  recs = {
    similarItems: jest.fn().mockResolvedValue({ results: [] }),
    forVisitor: jest.fn().mockResolvedValue({ results: [] }),
    forUser: jest.fn().mockResolvedValue({ results: [] })
  };
  
  events = {
    trackSearch: jest.fn(),
    trackPurchase: jest.fn(),
    flush: jest.fn()
  };
  
  identify = jest.fn();
}

Getting Started

SDK

Search

Recommendations

Product Listing Pages

Event Tracking

Identity

Plugins

Advanced

Overview

Server Configuration

Next.js

Server Components (App Router)

API Routes

getServerSideProps (Pages Router)

Client-Side Hydration

AWS Lambda

Vercel Edge Functions

Identity on Server

Caching Recommendations

Error Handling on Server

Testing

Next Steps

React Integration

Error Handling

Getting Started

SDK

Search

Recommendations

Product Listing Pages

Event Tracking

Identity

Plugins

Advanced

​Overview

​Server Configuration

​Next.js

​Server Components (App Router)

​API Routes

​getServerSideProps (Pages Router)

​Client-Side Hydration

​AWS Lambda

​Vercel Edge Functions

​Identity on Server

​Caching Recommendations

​Error Handling on Server

​Testing

​Next Steps

React Integration

Error Handling

Overview

Server Configuration

Next.js

Server Components (App Router)

API Routes

getServerSideProps (Pages Router)

Client-Side Hydration

AWS Lambda

Vercel Edge Functions

Identity on Server

Caching Recommendations

Error Handling on Server

Testing

Next Steps