@mosaicora/plugin-mosaicora-core

Framework-agnostic helpers for Mosaicora.io Open Graph image URLs and typed mosaicora:og JSON-LD v3 overrides.

Install

pnpm add @mosaicora/plugin-mosaicora-core

Use @mosaicora/plugin-nextjs for a native Next.js App Router integration.

Public API

The package exports URL helpers, JSON-LD builders, and the complete v3 semantic contract, including MosaicoraOgOverride, MosaicoraOgSemanticValues, MosaicoraOgSemanticRole, and role-specific value types.

Build an Open Graph image URL

import { buildOgImageUrl } from "@mosaicora/plugin-mosaicora-core";

const imageUrl = buildOgImageUrl({
  siteId: "321cac22d2103fb1660c50bd",
  pageHref: "https://example.com/products/view",
});

URL behavior is deterministic:

• / becomes https://cdn.mosaicora.io/s/{siteId}.jpg.
• Nested paths retain their path below /s/{siteId}.
• Non-tracking page query parameters are sorted, percent-encoded into the CDN path, and appear before .jpg.
• utm_*, click identifiers, referral parameters, and CDN control parameters are removed before the CDN URL is emitted.
• Only the reserved cache-version v parameter appears after .jpg; the CDN ignores post-.jpg query parameters when resolving the source page.
• Hash fragments are ignored and UTF-8 paths remain readable.

For example, https://example.com/products/view?page=2&sku=123 becomes https://cdn.mosaicora.io/s/{siteId}/products/view%3Fpage%3D2%26sku%3D123.jpg. For legacy compatibility, the CDN also recognizes /products/view?page=2&sku=123.jpg as the same source page.

Optionally rotate the image URL for social caches

Social platforms often store a link preview and its Open Graph image after the first crawl. Purging Mosaicora's own image cache makes the latest image available from the CDN, but it cannot remove a preview already stored by Slack, LinkedIn, X, Facebook, or another social platform.

Set cacheVersion when you have an explicit content, deployment, or release revision. It adds that value as the v query parameter, so the next crawler that re-scrapes the page metadata sees a distinct image URL and can fetch a fresh image asset:

const imageUrl = buildOgImageUrl({
  siteId: "321cac22d2103fb1660c50bd",
  pageHref: "https://example.com/products/view",
  cacheVersion: "release-2026-07",
});
// https://cdn.mosaicora.io/s/321cac22d2103fb1660c50bd/products/view.jpg?v=release-2026-07

For pages that are rendered dynamically, opt in to a UTC-based URL rotation:

const imageUrl = buildOgImageUrl({
  siteId: "321cac22d2103fb1660c50bd",
  pageHref: "https://example.com/products/view",
  cacheBuster: "monthly",
});
// https://cdn.mosaicora.io/s/321cac22d2103fb1660c50bd/products/view.jpg?v=2026-07

Supported schedules are "daily", "weekly", "monthly", and positive whole-number UTC durations such as "15m", "6h", or "7d". The option is off by default, so existing URLs remain stable. Use the least frequent schedule that fits the content; "monthly" is the recommended production default. A non-empty cacheVersion takes precedence over cacheBuster and replaces any v value already present in the canonical URL.

URL rotation does not force any social platform to crawl a page again. It only ensures that, when a platform refreshes the page metadata, it receives a new image URL rather than the prior cached asset.

Add a v3 JSON-LD override

Keep your existing Schema.org data and add only values that Mosaicora should use exactly:

import {
  buildMosaicoraOgJsonLd,
  serializeJsonLd,
} from "@mosaicora/plugin-mosaicora-core";

const jsonLd = buildMosaicoraOgJsonLd({
  schemaType: "Product",
  name: "Example product",
  offers: {
    "@type": "Offer",
    price: "49",
    priceCurrency: "USD",
  },
  mosaicoraOg: {
    schemaVersion: 3,
    templateId: "6a36446a0021410e8044",
    semanticValues: {
      "content.title": "Example product",
      "content.description": "A polished preview for every product page.",
      "product.price": "$49",
      "product.features": ["Fast setup", "Consistent previews"],
    },
  },
});

const serialized = serializeJsonLd(jsonLd);

serializeJsonLd removes undefined values and escapes less-than characters so the result can be embedded safely in an HTML JSON-LD script element.

See Mosaicora OG Overrides v3 for every supported semantic role and value type.

Development

pnpm install
pnpm build
pnpm test
pnpm typecheck
npm pack --dry-run

Releases follow semantic versioning and publish from GitHub Releases to the public npm registry with trusted publishing and provenance.

Contributing and security

Read CONTRIBUTING.md before opening a pull request and SECURITY.md before reporting a vulnerability.

Licensed under the MIT License.