Framework-agnostic tutorial
Build Open Graph image URLs and safe, typed JSON-LD render overrides in any Node.js or TypeScript application.
What you will build
A framework-independent integration that publishes a Mosaicora CDN image through standard social metadata and supplies exact image-render content through safely serialized JSON-LD.
Step 1
Add 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
Step 2
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 the same absolute canonical URL your page publishes.
The fallback URL gives the generator a stable page identity when your application supports alternate entry URLs.
Generate the CDN 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",
});Expected result
Step 3
Use 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" />Step 4
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>Step 5
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.
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.
Join the waitlist and tell us what your publishing workflow needs.