@neworange/bynder-dam-connector-sitecoreai-sdk

A TypeScript-first React component library for integrating Bynder DAM assets into your React applications. Works with Next.js (App Router or Pages Router), Sitecore JSS, Sitecore Content SDK, Create React App, Vite, and any React environment.

Documentation

• Bynder DAM Connector for Sitecore docs: https://docs.bynder.integrationlayer.io/
• SitecoreAI developer integration guide: https://docs.bynder.integrationlayer.io/sitecore-ai/developer-integration

Features

• Four React Components: BynderDamImage, BynderDamNextImage, BynderDamLink, BynderDamVideo
• Framework Agnostic: Use with Next.js, Sitecore JSS, Sitecore Content SDK, or any React app
• Backward Compatible: Supports both new (SitecoreAI/XM Cloud) and legacy (XP/XM) field formats
• Smart Field Parsing: parseBynderField() utility handles JSON, XML-wrapped JSON, and object formats
• Full TypeScript Support: Comprehensive type definitions for Bynder asset data
• Next.js Image Optimization: BynderDamNextImage built on Next.js <Image> component via the dedicated ./next subpath export
• Standard HTML Images: BynderDamImage uses standard <img> tag (no Next.js required)
• Derivative Selection: Smart fallback logic for image/video derivatives
• Graceful Error Handling: Components never throw, render error text or null
• Customizable Styling: Pass className and other props for external styling
• Lightweight: Minimal bundle size with proper tree-shaking
• Type-Only Imports: Export types separately for non-component usage

Installation

npm install @neworange/bynder-dam-connector-sitecoreai-sdk

Peer Dependencies

This package requires the following peer dependencies:

{
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0"
}

Optional: If using BynderDamNextImage from @neworange/bynder-dam-connector-sitecoreai-sdk/next:

{
  "next": ">=12.2.0"
}

Note: Root imports from @neworange/bynder-dam-connector-sitecoreai-sdk do not require Next.js. Next.js is only required when importing BynderDamNextImage from @neworange/bynder-dam-connector-sitecoreai-sdk/next.

Usage

Root exports (framework-agnostic, no Next.js required)

import {
  BynderDamImage,
  BynderDamLink,
  BynderDamVideo,
  parseBynderField,
} from '@neworange/bynder-dam-connector-sitecoreai-sdk';

Next.js export (requires Next.js)

import { BynderDamNextImage } from '@neworange/bynder-dam-connector-sitecoreai-sdk/next';

Migration Notes

• BynderDamNextImage import path changed from the package root to the ./next subpath.
• Replace:

import { BynderDamNextImage } from '@neworange/bynder-dam-connector-sitecoreai-sdk';

• With:

import { BynderDamNextImage } from '@neworange/bynder-dam-connector-sitecoreai-sdk/next';

• Root imports for BynderDamImage, BynderDamLink, BynderDamVideo, and parseBynderField are unchanged.

Parsing Field Values

The SDK includes a parseBynderField() utility that automatically handles multiple field formats:

• SitecoreAI / XM Cloud - Pure JSON object (passed through as-is)
• Sitecore Content SDK - JSON string (parsed automatically)
• Legacy XP/XM Connector - XML-wrapped JSON <asset><![CDATA[...]]></asset> (extracted automatically)

import { BynderDamImage, parseBynderField } from '@neworange/bynder-dam-connector-sitecoreai-sdk';

// Works with all formats automatically
const asset = parseBynderField(fields.image.value);

<BynderDamImage 
  asset={asset} 
  derivative="webImage"
  alt="Product image" 
/>

When to use parseBynderField():

• ✅ Recommended for all Sitecore integrations (provides consistent API)
• ✅ Required for Content SDK (JSON string fields)
• ✅ Required when migrating from legacy XP/XM connectors (XML-wrapped format)
• ✅ Safe to use with Sitecore JSS (works with already-parsed objects)
• ✅ Handles unknown or varying field formats automatically

Browser Support

• Modern browsers with ES2020 support
• Next.js 12.2+ (when using BynderDamNextImage)
• React 18+ or 19+
• HTML5 video support required for BynderDamVideo

Release Notes

1.2.0 - Current

• Root package is framework-agnostic and no longer exports BynderDamNextImage
• BynderDamNextImage now ships from @neworange/bynder-dam-connector-sitecoreai-sdk/next
• Package exports and type entry points were aligned for out-of-the-box TypeScript resolution
• Next.js moved to optional peer dependency (next >=12.2.0)
• Build output was adjusted to avoid Turbopack dynamic require runtime errors

1.1.x

• Type declaration and module interop fixes for broader consumer compatibility

1.0.4

• Initial public release with BynderDamImage, BynderDamNextImage, BynderDamLink, and BynderDamVideo

License

MIT

About

Developed with care by New Orange & uxbee

Powered by Bynder DAM | Built for SitecoreAI

• New Orange: https://neworange.agency/en
• uxbee: https://uxbee.eu/
• Bynder Integration Portal: https://bynder.integrationlayer.io/
• NPM: https://www.npmjs.com/package/@neworange/bynder-dam-connector-sitecoreai-sdk

Trademarks

All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.