Use the core npm package to build Mosaicora image URLs, publish crawler-readable social metadata, and optionally version refreshed image assets in any server-rendered or statically generated Node.js application.
Expected outcome
Your server or static build publishes one predictable Mosaicora image URL per page and can safely provide typed JSON-LD values when the image needs deliberate content.
The integration connects content your application already knows about to the metadata a social crawler can read.
Choose another path
Choose the Next.js guide when App Router metadata can handle the integration for you.
Use the native Next.js packageAdd the framework-agnostic ESM package to your application.
Install from the project root. The package is side-effect free and includes TypeScript declarations.
Install with pnpm
pnpm add @mosaicora/plugin-mosaicora-coreExpected result
Turn the page’s canonical identity into a deterministic Mosaicora CDN address.
Call buildOgImageUrl on the server or during static generation. Pass the site ID and pageHref: the same absolute canonical URL your page publishes.
Use one pageHref for each public page identity. Publish an alternate route’s canonical URL before creating its Mosaicora image URL.
Generate the CDN URL
import { buildOgImageUrl } from "@mosaicora/plugin-mosaicora-core";
const imageUrl = buildOgImageUrl({
siteId: "321cac22d2103fb1660c50bd",
pageHref: "https://example.com/products/view",
});Expected result
Add an opt-in v URL when an updated image should be fetched as a separate asset.
Set cacheVersion to a non-empty deployment, release, or content revision you control. It safely encodes the value, replaces a source URL’s existing v, and takes precedence over a cacheBuster schedule.
For automatic rotation, use cacheBuster: "monthly" as the least-frequent suitable schedule. When neither option is supplied, buildOgImageUrl preserves the existing URL behavior.
Manual image version
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-07Monthly image version
const imageUrl = buildOgImageUrl({
siteId: "321cac22d2103fb1660c50bd",
pageHref: "https://example.com/products/view",
cacheBuster: "monthly",
});
// For July 2026: https://cdn.mosaicora.io/s/321cac22d2103fb1660c50bd/products/view.jpg?v=2026-07Use the generated URL in standard Open Graph and X/Twitter tags.
Pass imageUrl into your framework, CMS, or template engine. Render these tags in the document head before returning the page to crawlers.
Framework-neutral HTML
<meta property="og:image" content="IMAGE_URL" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="IMAGE_URL" />Build and safely serialize JSON-LD values for the Mosaicora generator.
Keep your existing Schema.org fields and add mosaicora:og semantic values for content the generator should render exactly. These overrides guide the Open Graph image. They do not replace normal page metadata.
serializeJsonLd removes undefined values and escapes less-than characters so the result can be embedded in an HTML JSON-LD script element.
Build and serialize the override
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,
semanticValues: {
"content.title": "Example product",
"content.description": "A polished product preview.",
"product.price": "$49",
"product.features": ["Fast setup", "Consistent previews"],
},
},
});
const serialized = serializeJsonLd(jsonLd);Embed with your template engine
Insert serialized as the text content of an application/ld+json script.
<script type="application/ld+json">
SERIALIZED_JSON_LD
</script>Check the server-rendered HTML, image URL, and JSON-LD together.
Publish the page at its canonical public URL, inspect the initial HTML response, and run the URL through the Open Graph Checker.
Confirm that the image metadata uses imageUrl and that the JSON-LD contains the same page identity and intended semantic render values.
If image content changed, verify that imageUrl ends with only the intended v value before requesting any optional platform refresh.
Expected result
Reference
The same canonical input always maps to the same normalized image location.
The package exports URL helpers, JSON-LD builders, and the complete v3 semantic contract.
Help
Confirm the application uses Node.js 20+ and supports ESM imports. Import from the package root rather than a private dist path.
Move metadata generation to the server or static build. Tags injected only after browser hydration are not reliable for social crawlers.
Embed the output from serializeJsonLd once as script text. Do not run JSON.stringify on the serialized string a second time.
Verify the public page now exposes the intended metadata and image, then set cacheVersion for the new asset or choose the least-frequent suitable cacheBuster schedule. A versioned image does not make a third-party platform re-crawl an already cached page preview.
Learn how to distinguish a stale social preview from a metadata or image delivery issue.
Use the native App Router package built on these core helpers.
Inspect the metadata and social image published by a public page.
Compare the available Mosaicora integration paths.
Open the dashboard to start with the current integrations, or contact us if you need a different workflow.