@stackla/widget-utils

🎨 A comprehensive TypeScript utility library for building powerful User-Generated Content (UGC) widgets

🚀 Overview

@stackla/widget-utils is a feature-rich library that provides everything you need to build, customize, and deploy UGC widgets. Whether you're creating a simple content gallery or a complex interactive widget with carousels, infinite scrolling, and dynamic templates, this library has you covered.

✨ Features

• 🎯 TypeScript First - Fully typed API for excellent IDE support and type safety
• 🎨 Flexible Templating - Support for Handlebars templates with custom helpers
• ⚛️ JSX Support - Build widgets using JSX syntax without React
• 🎪 Widget Loading - Automated widget initialization and lifecycle management
• 🔄 Infinite Scrolling - Built-in hooks for seamless content loading
• 📦 Modular Architecture - Import only what you need with tree-shakeable exports
• 🎠 Extension Support - Includes Swiper carousel integration out of the box
• 🎨 CSS Variables - Dynamic theming and styling support
• 📡 Event System - Comprehensive event handling for widget interactions
• 🔌 Embed Utilities - Easy widget embedding for both v2 and v3 widgets

📦 Installation

npm install @stackla/widget-utils

yarn add @stackla/widget-utils

pnpm add @stackla/widget-utils

🎯 Quick Start

Basic Widget Setup

import { loadWidget } from "@stackla/widget-utils"

// Initialize a widget with default settings
const sdk = await loadWidget({
  features: {
    showTitle: true,
    preloadImages: true,
    addNewTilesAutomatically: true
  }
})

Using JSX for Widget Components

import { jsx } from '@stackla/widget-utils/jsx';

const TileComponent = ({ title, image }) => (
  <div className="tile">
    <img src={image} alt={title} />
    <h3>{title}</h3>
  </div>
);

📚 Module Reference

Core Modules

@stackla/widget-utils (Main Export)

The primary entry point providing widget loading, core types, events, and library utilities.

Key Exports:

• loadWidget() - Initialize and configure widgets
• ISdk - TypeScript interface for widget SDK
• Widget lifecycle hooks and event handlers

@stackla/widget-utils/types

Comprehensive TypeScript type definitions for widgets, tiles, components, and services.

Includes:

• Widget, Tile, Placement - Core data types
• WidgetOptions, WidgetSettings - Configuration types
• Service interfaces for tiles, events, and widgets
• Component types for static content, products, and UGC

@stackla/widget-utils/jsx

JSX-to-HTML runtime that lets you write components using JSX syntax without React.

Features:

• Lightweight JSX transformation
• Event handler support
• Ref support for DOM access
• Type-safe JSX elements

@stackla/widget-utils/handlebars

Handlebars template engine with custom helpers designed for widget rendering.

Custom Helpers:

• {{tile}} - Render tile components
• {{ifEquals}} - Conditional rendering
• {{lazy}} - Lazy loading support
• {{join}} - Array joining
• {{ifAutoPlayVideo}} - Video autoplay detection
• {{ifHasProductTags}} - Product tag checking
• {{ifHasPublicTags}} - Public tag checking
• {{tagFallbackUsername}} - Username fallback logic

@stackla/widget-utils/libs

Core library utilities for widget features and functionality.

Includes:

• CSS variable management
• Widget feature toggles
• Layout utilities
• Tile manipulation helpers

@stackla/widget-utils/components

Pre-built component utilities for common widget patterns.

Available Components:

• Static content components
• Product display components
• Share menu components
• Add-to-cart components
• UGC tile components

@stackla/widget-utils/extensions

Widget extensions for enhanced functionality.

Current Extensions:

• Swiper - Carousel/slider integration

@stackla/widget-utils/extensions/swiper

Full Swiper carousel integration for creating image/content sliders.

Features:

• Automatic initialization
• Responsive configuration
• Touch/swipe support
• Navigation and pagination

@stackla/widget-utils/events

Event system for widget lifecycle and user interactions.

Event Types:

• Widget initialization events
• Tile interaction events
• Load more events
• User action events

@stackla/widget-utils/embed

Utilities for embedding widgets into web pages.

Features:

• Support for v2 and v3 widgets
• Environment configuration (staging/production)
• Auto-detection of widget version
• Shadow DOM support

@stackla/widget-utils/templates

Template utilities and pre-built templates.

@stackla/widget-utils/bundle

Bundled distribution for direct browser usage.

🔧 Configuration

Widget Settings

interface WidgetSettings {
  features?: {
    showTitle?: boolean // Display widget title
    preloadImages?: boolean // Preload images for performance
    disableWidgetIfNotEnabled?: boolean // Auto-disable on config
    addNewTilesAutomatically?: boolean // Auto-add new tiles
    handleLoadMore?: boolean // Enable load more functionality
    hideBrokenImages?: boolean // Hide broken image tiles
    loadTileContent?: boolean // Load tile content dynamically
    loadTimephrase?: boolean // Load time phrases
  }
  callbacks?: {
    // Custom callback functions
  }
  templates?: {
    // Custom templates
  }
  config?: {
    // Additional configuration
  }
}

🎨 Examples

Creating a Gallery Widget

import { loadWidget } from "@stackla/widget-utils"
import { renderTilesWithTemplate } from "@stackla/widget-utils/handlebars"

const sdk = await loadWidget({
  features: {
    preloadImages: true,
    hideBrokenImages: true
  }
})

const tiles = await sdk.getTiles()
const html = await renderTilesWithTemplate(tileTemplate, tiles, {
  wid: "your-widget-id"
})

Using Swiper Extension

import { initSwiper } from "@stackla/widget-utils/extensions/swiper"

const swiper = initSwiper(".swiper-container", {
  slidesPerView: 3,
  spaceBetween: 30,
  navigation: true,
  pagination: {
    clickable: true
  }
})

Embedding a Widget

import { embed } from "@stackla/widget-utils/embed"

await embed({
  widgetId: "your-widget-id",
  root: document.getElementById("widget-container"),
  environment: "production",
  dataProperties: {
    // Custom data attributes
  }
})

🏗️ Project Structure

src/
├── constants.ts           # Global constants
├── embed/                 # Widget embedding utilities
├── events/                # Event system
├── fonts.ts              # Font loading utilities
├── handlebars/           # Handlebars templates and helpers
├── hooks/                # React hooks
├── index.ts              # Main entry point
├── libs/                 # Core library utilities
│   ├── components/       # Component utilities
│   ├── css-variables.ts  # CSS variable management
│   ├── extensions/       # Widget extensions
│   ├── jsx-html.ts       # JSX runtime
│   ├── tile.lib.ts       # Tile utilities
│   ├── widget.features.ts # Widget features
│   ├── widget.layout.ts   # Layout utilities
│   └── widget.utils.ts    # Widget utilities
├── styles/               # Style utilities
├── types/                # TypeScript type definitions
│   ├── components/       # Component types
│   ├── core/            # Core types
│   ├── services/        # Service types
│   └── loader.ts        # Loader types
└── widget-loader.ts      # Widget loader implementation

🧪 Development

Running Tests

npm test

Building

npm run build

Linting

npm run lint

Type Checking

npm run typecheck

📝 Contributing

Contributions are welcome! Please ensure your code:

• Passes all tests (npm test)
• Follows the linting rules (npm run lint)
• Includes proper TypeScript types
• Is documented with JSDoc comments where appropriate

🔗 Links

• NPM Package
• Repository
• Changelog

🎯 Use Cases

• Social Media Galleries - Display Instagram, Twitter, and other social feeds
• Product Showcases - Feature user-generated product reviews and photos
• Event Coverage - Aggregate and display event content from multiple sources
• Community Walls - Create interactive community content displays
• Marketing Campaigns - Build engaging campaign landing pages with UGC

Built with ❤️ by Nosto