Recently Viewed Plugin

A Vendure plugin that tracks and manages recently viewed products for customers. This plugin provides GraphQL queries and mutations for both shop and admin APIs to manage customer product browsing history.

Features

• Track Product Views: Automatically or manually record when customers view products
• Shop API: Customers can view, create, and delete their recently viewed products
• Admin API: Administrators can query recently viewed products for any customer
• Automatic Updates: If a product variant is viewed again, its lastViewedAt timestamp is updated
• Pagination Support: Full pagination and filtering support via RecentlyViewedListOptions

Installation

npm install vendure-plugin-recently-viewed

Configuration

Add the plugin to your Vendure config:

import { VendureConfig } from '@vendure/core';
import { RecentlyViewedPlugin } from 'vendure-plugin-recently-viewed';

export const config: VendureConfig = {
    // ... other config
    plugins: [
        RecentlyViewedPlugin.init({}),
        // ... other plugins
    ],
};

Database Migration

This plugin adds a new RecentlyViewed entity to your database. After adding the plugin to your config, you need to generate and run a database migration:

# Generate the migration
npm run migration:generate recently-viewed-plugin

# Run the migration
npm run migration:run

Make sure your Vendure config has migrations enabled:

export const config: VendureConfig = {
    // ... other config
    dbConnectionOptions: {
        // ... other options
        migrations: [
            /* your migrations */
        ],
        migrationsRun: false, // Set to true to run migrations automatically on startup
    },
};

Usage

Shop API

The plugin extends the Shop API with the following operations:

Query Recently Viewed Products

Retrieve the current customer's recently viewed products:

query {
    recentlyViewedProducts(options: { take: 10 }) {
        items {
            id
            productVariant {
                id
                name
                product {
                    id
                    name
                    slug
                }
            }
            lastViewedAt
            createdAt
        }
        totalItems
    }
}

Create Recently Viewed Record

Record that the current customer has viewed a product variant:

mutation {
    createRecentlyViewedProduct(productVariantId: "123") {
        id
        productVariant {
            id
            name
        }
        lastViewedAt
    }
}

If a record already exists for the customer and product variant, the lastViewedAt timestamp will be updated instead of creating a duplicate.

Delete Recently Viewed Product

Remove a specific product from the customer's recently viewed list:

# Delete by record ID
mutation {
    deleteRecentlyViewedProduct(id: "456") {
        result
        message
    }
}

# Or delete by product variant ID
mutation {
    deleteRecentlyViewedProduct(productVariantId: "123") {
        result
        message
    }
}

Delete All Recently Viewed Products

Clear the entire recently viewed history for the current customer:

mutation {
    deleteAllRecentlyViewedProducts {
        result
        message
    }
}

Admin API

The Admin API provides a query to view recently viewed products for any customer:

query {
    recentlyViewedProducts(customerId: "789", options: { take: 20, sort: { lastViewedAt: DESC } }) {
        items {
            id
            productVariant {
                id
                name
            }
            lastViewedAt
        }
        totalItems
    }
}

Frontend Integration Example

Here's how you might integrate this plugin in your storefront:

// Track product view when customer visits a product page
async function trackProductView(productVariantId: string) {
    const mutation = gql`
        mutation CreateRecentlyViewed($productVariantId: ID!) {
            createRecentlyViewedProduct(productVariantId: $productVariantId) {
                id
            }
        }
    `;

    await apolloClient.mutate({
        mutation,
        variables: { productVariantId },
    });
}

// Display recently viewed products
async function getRecentlyViewed() {
    const query = gql`
        query GetRecentlyViewed {
            recentlyViewedProducts(options: { take: 8 }) {
                items {
                    productVariant {
                        id
                        name
                        featuredAsset {
                            preview
                        }
                        product {
                            slug
                        }
                    }
                }
            }
        }
    `;

    const { data } = await apolloClient.query({ query });
    return data.recentlyViewedProducts.items;
}

Permissions

All Shop API operations require the customer to be authenticated and use the Permission.Owner decorator to ensure customers can only access their own data.

Database Schema

The plugin creates a RecentlyViewed entity with the following structure:

• id: Unique identifier
• customerId: Reference to the customer
• productVariantId: Reference to the product variant
• lastViewedAt: Timestamp of the most recent view
• createdAt: Timestamp of initial creation
• updatedAt: Timestamp of last update

API Reference

Shop API

• Query: recentlyViewedProducts(options: RecentlyViewedListOptions): RecentlyViewedList!
• Mutation: createRecentlyViewedProduct(productVariantId: ID!): RecentlyViewed!
• Mutation: deleteRecentlyViewedProduct(id: ID, productVariantId: ID): DeletionResponse!
• Mutation: deleteAllRecentlyViewedProducts: DeletionResponse!

Admin API

• Query: recentlyViewedProducts(customerId: ID!, options: RecentlyViewedListOptions): RecentlyViewedList!

License

MIT