@entrext/widget-nextjs

v1.0.4

Published

3 months ago

Entrext testimonial widget for Next.js applications

0High
0Medium
0Low

tarasha_entrext

entrext testimonials widget next.js react

ProofStack Widget for Next.js

A client-side testimonial widget component for Next.js applications (both App Router and Pages Router).

Features

✅ Full Next.js App Router and Pages Router support
✅ Client component with proper SSR handling ('use client')
✅ Automatic testimonial carousel with auto-scroll
✅ Modal submission form for customer feedback
✅ Light and dark theme support
✅ TypeScript support with full type definitions
✅ Responsive design
✅ Zero additional dependencies (uses React, sonner for toasts)

Installation

Option 1: Local Import (Development)

# The widget is built and ready to use

Then in your component:

import { ProofStackWidget } from '@proofstack/widget-nextjs';
import '@proofstack/widget-nextjs/dist/styles.css';

Option 2: Direct Import from Package

import { ProofStackWidget } from '../../../packages/widget-nextjs/dist';
import '../../../packages/widget-nextjs/dist/styles.css';

Usage

Basic Example

'use client'; // Required in Next.js App Router

import { ProofStackWidget } from '@proofstack/widget-nextjs';
import '@proofstack/widget-nextjs/dist/styles.css'; // Import styles from dist

export default function TestimonialSection() {
  return (
    <div className="my-12">
      <h2>What Our Users Say</h2>
      <ProofStackWidget
        projectId="your-project-id"
        backendUrl="https://your-backend.com"
        theme="light"
      />
    </div>
  );
}

Or import styles globally in your layout:

// app/layout.tsx
import '@proofstack/widget-nextjs/dist/styles.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

With All Options

'use client';

import { ProofStackWidget } from '@proofstack/widget-nextjs';

export default function Testimonials() {
  return (
    <ProofStackWidget
      projectId="your-project-id"
      backendUrl="https://api.yoursite.com"
      theme="dark"
      displayLimit={5}
      autoScroll={true}
      className="my-custom-class"
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | projectId | string | Required | Your ProofStack project ID | | theme | 'light' \| 'dark' | 'light' | Theme for the widget | | backendUrl | string | 'http://localhost:8000' | Backend API URL | | displayLimit | number | 10 | Maximum testimonials to display | | autoScroll | boolean | true | Auto-scroll carousel | | className | string | '' | Additional CSS classes |

Theme Customization

The widget uses CSS custom properties (CSS variables) for theming:

/* Light Theme (default) */
:root {
  --proofstack-primary: #3b82f6;
  --proofstack-primary-dark: #1e40af;
  --proofstack-text-primary: #1f2937;
  --proofstack-text-secondary: #6b7280;
  --proofstack-border: #e5e7eb;
  --proofstack-bg: #ffffff;
  --proofstack-bg-secondary: #f9fafb;
  --proofstack-star: #fbbf24;
}

/* Dark Theme */
.proofstack-dark {
  --proofstack-text-primary: #f9fafb;
  --proofstack-text-secondary: #d1d5db;
  --proofstack-border: #374151;
  --proofstack-bg: #1f2937;
  --proofstack-bg-secondary: #111827;
}

Override these variables in your CSS to customize colors:

.proofstack-widget {
  --proofstack-primary: #your-color;
  --proofstack-star: #your-star-color;
}

Features in Detail

Testimonial Carousel

Auto-scrolls every 5 seconds (can be disabled)
Manual navigation with arrow buttons
Dot indicators to jump to specific testimonials
Shows testimonial: name, title, company, rating, content
Optional profile image support

Submission Modal

Form for visitors to submit testimonials
Fields: Name, Email, Title, Company, Rating (1-5 stars), Content
Form validation
Toast notifications for success/error
Auto-refreshes carousel after submission

States

Loading: Skeleton cards while fetching testimonials
Empty: Shows "Be the first to share" with submit button
Error: Shows error message with retry button
Success: Displays carousel of testimonials

Next.js Specific

App Router

// app/components/Testimonials.tsx
'use client';

import { ProofStackWidget } from '@proofstack/widget-nextjs';

export default function Testimonials() {
  return <ProofStackWidget projectId="your-id" />;
}

// app/page.tsx
import Testimonials from './components/Testimonials';

export default function Home() {
  return (
    <main>
      <Testimonials />
    </main>
  );
}

Pages Router

// pages/testimonials.tsx
import { ProofStackWidget } from '@proofstack/widget-nextjs';

export default function TestimonialPage() {
  return (
    <div className="py-12">
      <ProofStackWidget projectId="your-id" />
    </div>
  );
}

Styling Integration

The widget works with any CSS framework:

Tailwind CSS

<ProofStackWidget
  projectId="your-id"
  className="max-w-4xl mx-auto rounded-lg shadow-lg"
/>

CSS Modules

import styles from './testimonials.module.css';

<ProofStackWidget
  projectId="your-id"
  className={styles.widget}
/>

/* testimonials.module.css */
.widget {
  max-width: 800px;
  margin: 0 auto;
  border-radius: 12px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

Environment Variables

# .env.local
NEXT_PUBLIC_PROOFSTACK_BACKEND_URL=https://api.yourdomain.com
NEXT_PUBLIC_PROOFSTACK_PROJECT_ID=your-project-id

Then in your component:

<ProofStackWidget
  projectId={process.env.NEXT_PUBLIC_PROOFSTACK_PROJECT_ID!}
  backendUrl={process.env.NEXT_PUBLIC_PROOFSTACK_BACKEND_URL}
/>

Troubleshooting

"Cannot find module '@proofstack/widget-nextjs'"

Make sure you're importing from the correct path:

// ✅ Correct
import { ProofStackWidget } from '@proofstack/widget-nextjs';

// or from local packages
import { ProofStackWidget } from '../../../packages/widget-nextjs/dist';

Styles not loading

Ensure CSS file is imported from the dist folder:

import '@proofstack/widget-nextjs/dist/styles.css';

For Next.js with Tailwind, add to app/layout.tsx:

import '@proofstack/widget-nextjs/dist/styles.css';

Or import in your global CSS file:

@import '@proofstack/widget-nextjs/dist/styles.css';

Dark mode not working

The widget respects the theme prop. For automatic dark mode detection:

import { useEffect, useState } from 'react';

export default function Testimonials() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  useEffect(() => {
    const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    setTheme(isDark ? 'dark' : 'light');
  }, []);

  return <ProofStackWidget projectId="your-id" theme={theme} />;
}

CORS Errors

If you see CORS errors, ensure your backend allows your Next.js domain:

Backend main.py:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yoursite.com", "https://www.yoursite.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Build Output

The widget is compiled to:

dist/index.js - Main component
dist/Carousel.js - Carousel component
dist/SubmissionModal.js - Modal component
dist/*.d.ts - TypeScript type definitions
src/styles.css - CSS stylesheet

Performance

Component lazy loads testimonials via API
Supports pagination with displayLimit
Minimal bundle size (~4KB gzipped)
No external dependencies except React and sonner

Browser Support

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

License

MIT