@proofedge/medusa-storefront

v1.0.2

Published

3 months ago

React component library for ProofEdge social proof widgets in Medusa Next.js storefronts

0High
0Medium
0Low

suryanarayan

medusa react social-proof proofedge nextjs storefront

@proofedge/medusa-storefront

React components for adding ProofEdge social proof widgets to your Medusa.js storefront.

Works with Next.js, Gatsby, or any React-based Medusa storefront.

What Is This?

This package gives you two things:

ProofEdgeWidget — A React component that shows social proof popups like "Sarah from London just bought this" on your storefront.
useProofEdgeTracking — A React hook that tracks product page views and sends them to your Medusa backend.

Together with the medusa-plugin-proofedge backend plugin, this creates a complete social proof system for your Medusa store.

Quick Start

1. Install

npm install @proofedge/medusa-storefront

2. Add your environment variable

In your storefront .env.local (Next.js) or .env:

NEXT_PUBLIC_PROOFEDGE_SITE_ID=your_site_id_here

Get your Site ID from the ProofEdge dashboard.

3. Add the widget to your layout

This shows purchase notifications across your entire store:

import { ProofEdgeWidget } from "@proofedge/medusa-storefront"

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <ProofEdgeWidget
          siteId={process.env.NEXT_PUBLIC_PROOFEDGE_SITE_ID}
          position="bottom-left"
        />
      </body>
    </html>
  )
}

That's it! You should see social proof popups on your storefront.

Product-Specific Notifications

Want to show "Someone just bought THIS product" on a product page? Pass the productId and use the tracking hook:

import { ProofEdgeWidget, useProofEdgeTracking } from "@proofedge/medusa-storefront"

export default function ProductPage({ product }) {
  // Tracks when someone views this product page
  useProofEdgeTracking(product.id, product.title)

  return (
    <div>
      <h1>{product.title}</h1>
      {/* ... your product details ... */}

      <ProofEdgeWidget
        siteId={process.env.NEXT_PUBLIC_PROOFEDGE_SITE_ID}
        productId={product.id}
        position="bottom-left"
        theme="light"
      />
    </div>
  )
}

For product view tracking, also add this to your .env.local:

NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000

ProofEdgeWidget Props

| Prop | Type | Required | Default | What It Does | |------|------|----------|---------|--------------| | siteId | string | Yes | — | Your ProofEdge Site ID | | productId | string | No | — | Filter notifications to a specific product | | position | string | No | "bottom-left" | Where the popup appears on screen | | theme | string | No | "light" | Color theme of the popup | | onLoad | function | No | — | Callback when the widget script loads |

Position Options

"bottom-left" — Bottom left corner (default, recommended)
"bottom-right" — Bottom right corner
"top-left" — Top left corner
"top-right" — Top right corner

Theme Options

"light" — White background, dark text (default)
"dark" — Dark background, light text
"auto" — Matches the user's system preference

useProofEdgeTracking Hook

Tracks product page views. Call it on your product detail page:

useProofEdgeTracking(productId, productTitle, siteId?, options?)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | productId | string | Yes | The Medusa product ID | | productTitle | string | Yes | The product name | | siteId | string | No | Your Site ID (reads from NEXT_PUBLIC_PROOFEDGE_SITE_ID if not passed) | | options | object | No | { medusaBackendUrl?: string } to override the backend URL |

The hook automatically:

Fires once per product page mount (no duplicate tracking)
Sends the event to your Medusa backend's /proofedge/track endpoint
Fails silently — never blocks or breaks your page

How It Works

1. ProofEdgeWidget loads the ProofEdge script on your page
2. The script connects to ProofEdge and fetches recent purchase events
3. It shows popups like "Sarah from London just bought Premium Widget"
4. useProofEdgeTracking sends product view events through your Medusa backend
5. Your Medusa backend (with medusa-plugin-proofedge) forwards them to ProofEdge

Requirements

The backend plugin (medusa-plugin-proofedge) must be installed on your Medusa server for purchase data to flow into ProofEdge.
This storefront package handles the display side — showing popups and tracking views.

Full Setup Guide

For a complete setup guide (backend + storefront), see the medusa-plugin-proofedge README.

Troubleshooting

Widget not showing?

Check that NEXT_PUBLIC_PROOFEDGE_SITE_ID is set in .env.local
Make sure the Site ID matches your ProofEdge dashboard
Open browser console and look for [ProofEdge] messages

Product view tracking not working?

Add NEXT_PUBLIC_MEDUSA_BACKEND_URL to your .env.local
Make sure your Medusa backend is running
Make sure "product.viewed" is in your plugin's events config

Need help?

Visit proofedge.io/help
Email [email protected]

Compatibility

| Requirement | Version | |-------------|---------| | React | 17 or higher | | Next.js | 13 or higher (App Router or Pages Router) | | Node.js | 16 or higher |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@proofedge/medusa-storefront

What Is This?

Quick Start

1. Install

2. Add your environment variable

3. Add the widget to your layout

Product-Specific Notifications

ProofEdgeWidget Props

Position Options

Theme Options

useProofEdgeTracking Hook

How It Works

Requirements

Full Setup Guide

Troubleshooting

Widget not showing?

Product view tracking not working?

Need help?

Compatibility

License