Next.js Integration Guide

Recommended architecture

Next.js can render images on the server, so the most predictable approach is to construct a CDN URL with a local ESM helper and render a normal image element. URL generation does not need a browser DOM.

1. Add the helper files locally

Download soft-hours-diary.js and soft-hours-diary.esm.mjs into src/lib/shd/. Keep them side by side because the ESM entry imports the sibling UMD implementation.

import {
  emojiUrl,
  flagUrl
} from "@/lib/shd/soft-hours-diary.esm.mjs";

export function AssetExamples() {
  return (
    <div>
      <img
        src={emojiUrl("1f632", { quality: "svg" })}
        alt="Surprised face"
        width={36}
        height={36}
      />

      <img
        src={flagUrl("IN", { quality: "l" })}
        alt="Flag of India"
        width={48}
        height={32}
      />
    </div>
  );
}

2. Configure next/image when required

A standard img tag does not need host configuration. If you use next/image, add the CDN host to remotePatterns.

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "softhoursdiary-emojis.pages.dev",
        pathname: "/**"
      }
    ]
  }
};

export default nextConfig;

import Image from "next/image";
import { emojiUrl } from "@/lib/shd/soft-hours-diary.esm.mjs";

export function CdnImage() {
  return (
    <Image
      src={emojiUrl("1f632", { quality: "svg" })}
      alt="Surprised face"
      width={36}
      height={36}
    />
  );
}

3. Browser custom elements with next/script

Use a Client Component when custom elements are your preferred API. Load the browser bundle using next/script.

"use client";

import Script from "next/script";

export function BrowserAssets() {
  return (
    <>
      <Script
        src="https://softhoursdiary-emojis.pages.dev/soft-hours-diary.js"
        strategy="afterInteractive"
      />

      <shd-emoji asset-id="1f632" quality="svg"
        alt="Surprised face" />

      <shd-flag asset-id="IN" quality="l"
        alt="Flag of India" />
    </>
  );
}

Avoid remote ESM imports in server code

Production checklist

• Set descriptive alt text for informative images.
• Provide width and height to reduce layout shift.
• Add remotePatterns before using next/image.
• Do not access window or customElements during server rendering.
• Keep text or native emoji fallbacks for important UI.