@mosaicora/plugin-mosaicora-core

@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",
  canonicalHref: "https://example.com/products/view?sku=123&campaign=launch",
  fallbackHref: "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}.
• Every query parameter is preserved and sorted by key and value.
• .jpg appears before the query string.
• Hash fragments are ignored and UTF-8 paths remain readable.

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.