Vendure Deep Pagination Plugin

Infinite product pagination using Elasticsearch search_after cursors. Bypass the 10k limit.

The Problem

Elasticsearch limits offset-based pagination to 10,000 documents. For e-commerce stores with large catalogs:

• Users cannot browse beyond page 834 (12 products/page)
• Performance degrades linearly with page depth
• SEO suffers from incomplete product indexing

The Solution

This plugin uses Elasticsearch's search_after API for cursor-based pagination:

• No limits - Navigate through millions of products
• O(1) performance - Constant speed at any page depth
• Drop-in replacement - Extends Vendure's GraphQL API

Installation

npm install @dylanmurzello/vendure-plugin-deep-pagination

Quick Start

1. Register Plugin

// vendure-config.ts
import { DeepPaginationPlugin } from '@gbros/vendure-plugin-deep-pagination';

export const config: VendureConfig = {
  plugins: [
    // ... other plugins
    DeepPaginationPlugin,
  ],
};

2. Query Products

query GetProducts($cursor: String) {
  cursorSearch(input: { take: 12, cursor: $cursor }) {
    items {
      productId
      productName
      slug
      priceWithTax {
        ... on SinglePrice { value }
        ... on PriceRange { min max }
      }
    }
    totalItems
    hasMore
    nextCursor
  }
}

3. Navigate Pages

// First page
const page1 = await client.request(GET_PRODUCTS, {});

// Next page
const page2 = await client.request(GET_PRODUCTS, {
  cursor: page1.cursorSearch.nextCursor
});

API Reference

Input

| Field | Type | Description | |-------|------|-------------| | term | string? | Full-text search query | | facetValueIds | string[]? | Filter by facet values | | facetValueOperator | 'AND' \| 'OR'? | Facet filter logic (default: OR) | | collectionId | string? | Filter by collection ID | | collectionSlug | string? | Filter by collection slug | | groupByProduct | boolean? | Group variants by product | | take | number? | Results per page (default: 100, max: 1000) | | cursor | string? | Opaque pagination cursor | | sort | object? | Sort options (see below) |

Sort Options

{
  name?: 'ASC' | 'DESC';
  price?: 'ASC' | 'DESC';
}

Output

| Field | Type | Description | |-------|------|-------------| | items | SearchResult[] | Products matching query | | totalItems | number | Total result count | | hasMore | boolean | More pages available | | nextCursor | string? | Cursor for next page |

How It Works

Cursor Pagination

Traditional offset pagination (skip + take) becomes slow at high offsets because Elasticsearch must scan and discard all previous results.

Cursor pagination uses search_after to resume from the last result's sort values:

Page 1: [A, B, C] -> cursor: "C's sort values"
Page 2: search_after "C's values" -> [D, E, F]

Deterministic Sorting

search_after requires stable sort order. We use:

1. User-specified field (name, price, etc.)
2. productId (keyword field)
3. productVariantId (keyword field)

This ensures consistent ordering even when products share the same name/price.

Why Keyword Fields?

Elasticsearch 9.x disables fielddata by default. We use keyword fields for sorting because:

• Keyword fields use doc_values (disk-based, efficient)
• Text fields require fielddata (memory-intensive, disabled)

Limitations

Forward-Only Navigation

Cursor pagination is forward-only. You can:

• Go to next page (use nextCursor)
• Go to first page (omit cursor)
• Jump to arbitrary pages (not supported)

Solution: Maintain a cursor stack in your frontend:

const [cursors, setCursors] = useState<string[]>([]);

// Forward
const goNext = () => {
  setCursors([...cursors, nextCursor]);
  fetchPage(nextCursor);
};

// Back
const goPrev = () => {
  const newCursors = cursors.slice(0, -1);
  setCursors(newCursors);
  fetchPage(newCursors[newCursors.length - 1]);
};

No Total Page Count

You receive totalItems but not total pages. Display pagination as:

const estimatedPages = Math.ceil(totalItems / take);
// Show: "Page 5 of ~1,320"

Performance

| Method | Page 1 | Page 100 | Page 1000 | |--------|--------|----------|-----------| | Offset | 50ms | 200ms | 1000ms | | Cursor | 50ms | 50ms | 50ms |

Cursor pagination maintains constant performance regardless of page depth.

Requirements

• Vendure >= 3.0.0
• Elasticsearch >= 8.0.0
• Node.js >= 18

Contributing

Contributions welcome! Please open an issue or PR.

Development

git clone https://github.com/dylanmurzello/vendure-plugin-deep-pagination.git
cd vendure-plugin-deep-pagination
npm install
npm run build

License

MIT - Dylan Murzello

Acknowledgments

Built for production e-commerce at scale. Open-sourced for the Vendure community.

Inspired by Elasticsearch's search_after documentation.