Use each route’s canonical URL to publish a predictable Mosaicora image in Open Graph and Twitter metadata. Optionally version the image URL when refreshed content needs a new asset after a social platform re-scrapes the page.
Expected outcome
Each public route exposes one stable Mosaicora image URL in crawler-readable metadata, with optional render values when the image should use content different from the page defaults.
The integration connects content your application already knows about to the metadata a social crawler can read.
Choose another path
Choose this path when your Node.js application does not use Next.js App Router.
Use the framework-agnostic npm packageAdd the native App Router helpers to the application that publishes your metadata.
Run the installation command from the root of your Next.js project. The package includes the framework-agnostic Mosaicora core as a dependency.
Install with pnpm
pnpm add @mosaicora/plugin-nextjsExpected result
Use the same absolute canonical URL for the page, metadata, and Mosaicora image path.
Resolve pageHref from trusted application data. It is the absolute public page URL and the canonical URL the page publishes. Dynamic route query parameters are preserved in deterministic order, while hash fragments are ignored.
Use one pageHref for each public page identity. Alternate routes should publish their own canonical URL before creating Mosaicora metadata.
Route values
const siteId = "321cac22d2103fb1660c50bd";
const canonicalUrl = "https://example.com/products/view";Generate matching Open Graph and X/Twitter image metadata with createMosaicoraMetadata.
Spread the helper output into the metadata returned by your route. You can add the page title, description, canonical alternate, and other standard Next.js metadata alongside it.
For dynamic routes, resolve the route data inside generateMetadata and pass the final canonical URL to the helper.
Static App Router metadata
import type { Metadata } from "next";
import { createMosaicoraMetadata } from "@mosaicora/plugin-nextjs";
const canonicalUrl = "https://example.com/products/view";
export const metadata: Metadata = {
title: "Example product",
alternates: { canonical: canonicalUrl },
...createMosaicoraMetadata({
siteId: "321cac22d2103fb1660c50bd",
pageHref: canonicalUrl,
alt: "Example product social preview",
}),
};Dynamic route metadata
export async function generateMetadata({ params }): Promise<Metadata> {
const { slug } = await params;
const product = await getProduct(slug);
return {
title: product.title,
description: product.description,
...createMosaicoraMetadata({
siteId: "321cac22d2103fb1660c50bd",
pageHref: product.canonicalUrl,
alt: product.title,
}),
};
}Expected result
Opt in to a new v URL when updated image content needs a separately cacheable asset.
Use cacheVersion for a deliberate deployment or content revision. It accepts any non-empty developer-controlled string and is the recommended choice when you decide exactly when the image changes.
Use cacheBuster: "monthly" only when a regular rotation is suitable. If both options are present, cacheVersion takes precedence. Without either option, the existing image URL behavior is unchanged.
Manual image version
...createMosaicoraMetadata({
siteId,
pageHref: canonicalUrl,
cacheVersion: "release-2026-07",
})
// Both og:image and twitter:image use:
// https://cdn.mosaicora.io/s/321cac22d2103fb1660c50bd/products/view.jpg?v=release-2026-07Monthly image version
...createMosaicoraMetadata({
siteId,
pageHref: canonicalUrl,
cacheBuster: "monthly",
})
// For July 2026, both image tags use:
// https://cdn.mosaicora.io/s/321cac22d2103fb1660c50bd/products/view.jpg?v=2026-07Tell the Mosaicora generator which exact page values to render in the image.
MosaicoraOgJsonLd preserves normal Schema.org fields and adds the typed mosaicora:og v3 block. The override is not a replacement for SEO metadata: it gives the image generator precise content such as the title, description, price, and feature list.
Place the component in the page or a route-specific server component so its values describe the same canonical page as the metadata.
Product JSON-LD override
import { MosaicoraOgJsonLd } from "@mosaicora/plugin-nextjs";
export default function ProductJsonLd() {
return (
<MosaicoraOgJsonLd
schemaType="Product"
name="Example product"
description="A polished preview for every product page."
url="https://example.com/products/view"
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"],
},
}}
/>
);
}Confirm the final HTML exposes the image URL and render instructions to crawlers.
Deploy or expose the route at its public canonical URL. Inspect the rendered HTML, then run that URL through the Mosaicora Open Graph Checker.
Check that the canonical URL, og:image, twitter:image, image dimensions, alt text, and mosaicora:og semantic values all describe the same page.
When using a version, confirm the published image URL ends with only the expected v value. A social platform may still retain its existing page preview until it chooses to re-scrape.
Expected result
Reference
The helper creates stable image addresses from the page identity.
Use the high-level Next.js helpers or the re-exported core primitives.
Help
Keep metadata exports in a Server Component route. Do not move metadata generation into a client component or a browser-only effect.
Normalize one absolute canonical URL and reuse it for alternates, pageHref, and the JSON-LD url field.
Inspect the mosaicora:og semanticValues. Add explicit title, description, price, or feature overrides for the values the generator should render exactly.
First confirm the public page publishes the updated metadata and image. Add cacheVersion for the changed asset or use the least-frequent suitable cacheBuster schedule, then use the platform’s refresh tool if available. The platform controls whether and when it re-scrapes the page.
Diagnose stale social previews and choose an appropriate image versioning workflow.
Use the same URL and JSON-LD primitives outside Next.js.
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.