Framework-Specific Examples

Learn how to use the SDK with different frameworks and platforms.

Field Format Handling

The SDK supports multiple field formats through the parseBynderField() utility:

import { BynderDamImage, parseBynderField } from '@neworange/bynder-dam-connector-sitecoreai-sdk';
 
// Automatically handles all formats:
// - SitecoreAI/XM Cloud: Pure JSON object
// - Content SDK: JSON string
// - Legacy XP/XM: XML-wrapped JSON <asset><![CDATA[{"type":"Assets",...}]]></asset>
 
const asset = parseBynderField(fields.image.value);
 
<BynderDamImage asset={asset} derivative="webImage" alt="Image" />

Supported Formats

Format	Example	Use Case
Pure JSON Object	`{ type: "Assets", assets: [...] }`	SitecoreAI, XM Cloud, JSS
JSON String	`"{\"type\":\"Assets\",\"assets\":[...]}"`	Content SDK
XML-Wrapped	`<asset><![CDATA[{"type":"Assets",...}]]></asset>`	Legacy XP/XM connectors

Key Benefits

✅ Backward compatible with legacy XP/XM connectors
✅ Works across all Sitecore platforms
✅ Automatic format detection
✅ No breaking changes when migrating platforms

Sitecore JSS

In Sitecore JSS, use parseBynderField() to handle field values consistently:

import { BynderDamImage, parseBynderField } from '@neworange/bynder-dam-connector-sitecoreai-sdk';
 
const HeroBlock = ({ fields }) => {
  const asset = parseBynderField(fields.heroImage.value);
  
  return (
    <BynderDamImage
      asset={asset}
      derivative="webImage"
      alt={fields.altText.value}
      loading="lazy"
    />
  );
};

Key Points

Use parseBynderField() for consistent field handling
Works with analyzed field values from JSS
Access via fields.fieldName.value
Compatible with all SDK components

Sitecore Content SDK

In Content SDK, the Bynder field is stored as a JSON string. Use parseBynderField() for automatic parsing:

import { BynderDamImage, parseBynderField } from '@neworange/bynder-dam-connector-sitecoreai-sdk';
import { Text, Field, withDatasourceCheck } from '@sitecore-content-sdk/nextjs';
 
type HeroBlockProps = {
  fields: {
    heading: Field<string>;
    heroImage: Field<string>; // JSON string
  };
};
 
const HeroBlock = ({ fields }: HeroBlockProps) => {
  const asset = parseBynderField(fields.heroImage?.value);
 
  return (
    <>
      <Text tag="h1" field={fields.heading} />
      <BynderDamImage
        asset={asset}
        derivative="webImage"
        alt="Hero image"
      />
    </>
  );
};
 
export default withDatasourceCheck()<HeroBlockProps>(HeroBlock);

Key Points

Field value is a JSON string - use parseBynderField()
Type the field as Field<string>
parseBynderField() handles null/undefined automatically
Full TypeScript support with BynderAssetResponse type

React / Vite / CRA

Standard React usage with state or props from API calls:

import { BynderDamImage, parseBynderField } from '@neworange/bynder-dam-connector-sitecoreai-sdk';
import { useState, useEffect } from 'react';
 
function ProductGallery() {
  const [assetData, setAssetData] = useState(null);
  
  useEffect(() => {
    fetch('/api/bynder-asset')
      .then(res => res.json())
      .then(setAssetData);
  }, []);
  
  const asset = parseBynderField(assetData);
  
  return asset ? (
    <BynderDamImage
      asset={asset}
      derivative="webImage"
      alt="Product image"
      loading="lazy"
    />
  ) : null;
}

Key Points

Use parseBynderField() to handle API responses consistently
Works in any React environment
No framework-specific dependencies
Compatible with all React rendering patterns

Next.js App Router

Use with Next.js 14+ App Router and Server Components:

import { BynderDamNextImage } from '@neworange/bynder-dam-connector-sitecoreai-sdk/next';
import { parseBynderField } from '@neworange/bynder-dam-connector-sitecoreai-sdk';
 
async function getAssetData() {
  const res = await fetch('https://api.example.com/asset');
  return res.json();
}
 
export default async function ProductPage() {
  const assetData = await getAssetData();
  const asset = parseBynderField(assetData);
 
  return (
    <main>
      <BynderDamNextImage
        asset={asset}
        derivative="webImage"
        alt="Product"
        priority
      />
    </main>
  );
}

Key Points

Use parseBynderField() to normalize API responses
Works in both Server and Client Components
Use BynderDamNextImage for image optimization
Server Components can fetch asset data directly

Legacy XP/XM Connector Migration

If you're migrating from the legacy XP/XM Bynder connector, parseBynderField() handles legacy XML-wrapped field values automatically:

import { BynderDamImage, parseBynderField } from '@neworange/bynder-dam-connector-sitecoreai-sdk';
 
// Legacy XP/XM format: <asset><![CDATA[{"type":"Assets",...}]]></asset>
// parseBynderField() extracts the JSON automatically
 
const MyComponent = ({ fields }) => {
  const asset = parseBynderField(fields.image.value);
  
  return (
    <BynderDamImage
      asset={asset}
      derivative="webImage"
      alt="Product"
    />
  );
};

Migration Benefits

✅ No code changes needed - Same API for old and new formats
✅ Gradual migration - Mix old and new connectors during transition
✅ Future-proof - Works with current and future Sitecore platforms
✅ Type-safe - Full TypeScript support across all formats

Legacy Format Details

The old XP/XM connector stored data as XML-wrapped JSON:

<asset><![CDATA[
{
  "type": "Assets",
  "assets": [
    {
      "id": "973C1499-6BA7-42C3-ACB72E4E09F05111",
      "name": "sample-product-image",
      "assetType": "Image",
      "files": [
        {
          "name": "webImage",
          "url": "http://www.your-bynder-portal.com/asset/973c1499-6ba7-42c3-acb7-2e4e09f05111/thumbnail/webimage-sample-product-image"
        },
        {
          "name": "thumbnail",
          "url": "http://www.your-bynder-portal.com/asset/973c1499-6ba7-42c3-acb7-2e4e09f05111/thumbnail/thul-sample-product-image"
        }
      ]
    }
  ]
}
]]></asset>

The SDK automatically:

Detects the XML wrapper
Extracts the JSON content from CDATA
Parses and validates the structure
Returns a typed BynderAssetResponse object

Next.js Pages Router

Use with Next.js Pages Router and getServerSideProps/getStaticProps:

import { BynderDamNextImage } from '@neworange/bynder-dam-connector-sitecoreai-sdk/next';
import { parseBynderField } from '@neworange/bynder-dam-connector-sitecoreai-sdk';
import type { GetServerSideProps } from 'next';
 
export default function ProductPage({ asset }) {
  const normalizedAsset = parseBynderField(asset);
 
  return (
    <BynderDamNextImage
      asset={normalizedAsset}
      derivative="webImage"
      alt="Product"
      width={800}
      height={600}
    />
  );
}
 
export const getServerSideProps: GetServerSideProps = async () => {
  const res = await fetch('https://api.example.com/asset');
  const asset = await res.json();
  
  return { props: { asset } };
};

Key Points

Use parseBynderField() as the default for normalized field handling
If migrating from XP/XM (<asset><![CDATA[...]]></asset>), parsing is required
If you're not upgrading and only use pure JSON object data, parsing is optional
Compatible with getServerSideProps, getStaticProps, and getInitialProps
Pass asset data as props from server-side data fetching
Use BynderDamNextImage for Next.js optimization
Works with incremental static regeneration (ISR)

Component Examples Advanced Examples