@power-seo/preview

Pixel-accurate SERP, Open Graph, and Twitter/X Card preview generators for TypeScript — compute exactly how a page appears in Google search results and social shares without a headless browser or canvas.

@power-seo/preview delivers pixel-width-aware SERP snippet generation, Open Graph image validation, and Twitter/X Card preview data — comparable to what Yoast SEO, Semrush, and Moz Pro show in their browser-based UIs, but as a standalone TypeScript library that runs anywhere. Provide a title, meta description, URL, and optional OG image — get back structured preview data with truncation flags, breadcrumb paths, and image validation results. Run it server-side in a CMS pipeline, client-side in a React editor, or inside a CI content gate. All four generators are fully tree-shakeable.

Zero runtime dependencies — only @power-seo/core as a peer.

Why @power-seo/preview?

Features

• Pixel-accurate SERP truncation — generateSerpPreview() truncates title at 580px, description at 920px using character-width lookup tables
• Site title composition — optional siteTitle field appended as "title - siteTitle" before truncation, matching Google's display format
• Google breadcrumb URL — formats https://example.com/blog/my-post as example.com › blog › my-post
• Open Graph image validation — generateOgPreview() validates image dimensions against the recommended 1200×630 minimum and reports pass/fail with a message
• Twitter/X Card support — generateTwitterPreview() handles summary and summary_large_image card types with per-type image dimension requirements
• Low-level truncation primitive — truncateAtPixelWidth() truncates any string at any pixel budget, usable independently of the preview generators
• Structured typed output — returns plain data objects ready for any UI renderer; no HTML, no DOM required
• React UI components — pre-built SerpPreview, OgPreview, TwitterPreview, and PreviewPanel from the /react subpath
• Framework-agnostic — works in Next.js, Remix, Gatsby, Vite, vanilla Node.js, Edge
• Full TypeScript support — complete type definitions for all inputs, outputs, and validation results
• Tree-shakeable — import only the generators you use; "sideEffects": false
• Zero runtime dependencies — pure computation, no canvas, no browser, no external libraries

Comparison

Installation

npm install @power-seo/preview

yarn add @power-seo/preview

pnpm add @power-seo/preview

Quick Start

import { generateSerpPreview, generateOgPreview } from '@power-seo/preview';

const serp = generateSerpPreview({
  title: 'How to Add SEO to React Apps',
  description: 'Learn how to add meta tags, Open Graph, and JSON-LD to any React application.',
  url: 'https://example.com/blog/react-seo',
  siteTitle: 'My Blog', // optional — appended as "title - siteTitle"
});

console.log(serp.title); // 'How to Add SEO to React Apps - My Blog' (truncated at 580px if too long)
console.log(serp.displayUrl); // 'example.com › blog › react-seo'
console.log(serp.titleTruncated); // false

const og = generateOgPreview({
  title: 'React SEO Guide',
  description: 'Complete SEO for React',
  url: 'https://example.com/blog/react-seo',
  image: { url: 'https://example.com/og.jpg', width: 1200, height: 630 },
});

console.log(og.image?.valid); // true
console.log(og.image?.message); // undefined (dimensions are correct)

Usage

Generating a Google SERP Preview

generateSerpPreview() computes the display title, breadcrumb URL, and description that Google would show, with pixel-accurate truncation flags.

import { generateSerpPreview } from '@power-seo/preview';

const serp = generateSerpPreview({
  title: 'Next.js SEO Best Practices',
  description:
    'Learn how to optimize your Next.js app for search engines with meta tags and structured data.',
  url: 'https://example.com/nextjs-seo',
  siteTitle: 'Dev Blog', // optional
});

// serp.title            → 'Next.js SEO Best Practices - Dev Blog' (possibly truncated)
// serp.displayUrl       → 'example.com › nextjs-seo'
// serp.description      → display description (possibly truncated at 920px)
// serp.titleTruncated   → true | false
// serp.titleValidation  → ValidationResult from @power-seo/core

Generating an Open Graph Preview

generateOgPreview() validates image dimensions and returns a structured card data object for Facebook, LinkedIn, and other OG-compatible platforms.

import { generateOgPreview } from '@power-seo/preview';

const og = generateOgPreview({
  title: 'React SEO Guide',
  description: 'Complete guide to adding SEO in React apps.',
  url: 'https://example.com/react-seo',
  siteName: 'Dev Blog',
  image: { url: 'https://example.com/og.jpg', width: 800, height: 400 },
});

// og.image?.valid    → false (too small)
// og.image?.message  → 'Image is 800x400px. Minimum size is 200x200px.'

Generating a Twitter/X Card Preview

generateTwitterPreview() handles both summary and summary_large_image card types, each with different image dimension requirements.

import { generateTwitterPreview } from '@power-seo/preview';

const twitter = generateTwitterPreview({
  cardType: 'summary_large_image',
  title: 'React SEO Guide',
  description: 'Everything you need to add SEO to any React application.',
  url: 'https://example.com/react-seo',
  site: '@myblog',
  image: { url: 'https://example.com/twitter.jpg', width: 1200, height: 628 },
});

// twitter.cardType  → 'summary_large_image'
// twitter.domain    → 'myblog'
// twitter.image?.valid → true

Using the Low-Level Truncation Primitive

truncateAtPixelWidth() is a standalone utility — use it to truncate any string at any pixel budget, independent of the SERP generator.

import { truncateAtPixelWidth } from '@power-seo/preview';

const result = truncateAtPixelWidth(
  'Buy Premium Running Shoes Online — Free Shipping Worldwide',
  580,
);

// result.text      → 'Buy Premium Running Shoes Online — Free Shippi...'
// result.truncated → true

React Components

Import from the /react entry point for pre-built preview UI components:

import { SerpPreview, OgPreview, TwitterPreview, PreviewPanel } from '@power-seo/preview/react';

// All-in-one tabbed panel (Google / Facebook / Twitter)
function EditorSidebar() {
  return (
    <PreviewPanel
      title="How to Add SEO to React Apps"
      description="Learn meta tags, Open Graph, and JSON-LD for React."
      url="https://example.com/blog/react-seo"
      siteTitle="My Blog"
      siteName="My Blog"
      image={{ url: 'https://example.com/og.jpg', width: 1200, height: 630 }}
      twitterCardType="summary_large_image"
      twitterSite="@myblog"
    />
  );
}

// Or use individual components
function SerpCard() {
  return (
    <SerpPreview
      title="How to Add SEO to React Apps"
      description="Learn meta tags, Open Graph, and JSON-LD for React."
      url="https://example.com/blog/react-seo"
      siteTitle="My Blog"
    />
  );
}

Inside a CI Content Quality Gate

Block deploys when SERP titles or OG images fail validation:

import { generateSerpPreview, generateOgPreview } from '@power-seo/preview';

const serp = generateSerpPreview({ title, description, url, siteTitle });
const og = generateOgPreview({ title, description, url, image });

if (serp.titleTruncated) {
  console.error('SERP title exceeds 580px — will be cut off in Google results');
  process.exit(1);
}

if (og.image && !og.image.valid) {
  console.error('OG image invalid:', og.image.message);
  process.exit(1);
}

API Reference

Entry Points

generateSerpPreview()

function generateSerpPreview(input: SerpPreviewInput): SerpPreviewData;

SerpPreviewInput

SerpPreviewData

generateOgPreview()

function generateOgPreview(input: OgPreviewInput): OgPreviewData;

OgPreviewInput

OgPreviewData

OgImageValidation

generateTwitterPreview()

function generateTwitterPreview(input: TwitterPreviewInput): TwitterPreviewData;

TwitterPreviewInput

TwitterPreviewData

TwitterImageValidation

truncateAtPixelWidth()

function truncateAtPixelWidth(text: string, maxPixels: number): TruncateResult;

TruncateResult

React Components

Import all components from @power-seo/preview/react.

import { SerpPreview, OgPreview, TwitterPreview, PreviewPanel } from '@power-seo/preview/react';

SerpPreview

Renders a Google-style SERP result card.

OgPreview

Renders a Facebook/Open Graph card mockup.

TwitterPreview

Renders a Twitter/X card mockup for summary or summary_large_image card types.

PreviewPanel

Tabbed container with Google, Facebook, and Twitter/X preview cards in a single component.

Types

Use Cases

• CMS live preview panels — show authors how their title and description appear in Google before publishing
• SEO auditing pipelines — detect truncated titles and invalid OG images at build time
• Programmatic SEO sites — validate auto-generated titles for thousands of pages at once
• Social media schedulers — validate OG image dimensions before queuing posts
• SaaS marketing dashboards — show SERP and social card previews for every page
• Blog platforms — live preview as editors type the meta description
• eCommerce product pages — ensure product image dimensions meet OG card requirements
• Landing page builders — embed SERP and social card previews in the editor UI
• CI content quality gates — fail builds when SERP titles are truncated or OG images are too small

Architecture Overview

• Pure TypeScript — no compiled binary, no native modules
• Zero runtime dependencies — only @power-seo/core as a peer dependency
• Character-width lookup — pixel truncation uses per-character width tables matching Google's SERP font metrics, not character counts
• Framework-agnostic — works in any JavaScript environment
• SSR compatible — safe to run in Next.js Server Components, Remix loaders, or Express handlers
• Edge runtime safe — no Node.js-specific APIs; no fs, no canvas; runs in Cloudflare Workers, Vercel Edge, Deno
• Tree-shakeable — "sideEffects": false with named exports per generator function
• Dual ESM + CJS — ships both formats via tsup for any bundler or require() usage
• React optional — React is a peer dependency; the /react subpath is only included when React is present

Supply Chain Security

• No install scripts (postinstall, preinstall)
• No runtime network access
• No eval or dynamic code execution
• CI-signed builds — all releases published via verified github.com/CyberCraftBD/power-seo workflow
• Safe for SSR, Edge, and server environments

The @power-seo Ecosystem

All 17 packages are independently installable — use only what you need.

About CyberCraft Bangladesh

CyberCraft Bangladesh is a Bangladesh-based enterprise-grade software development and Full Stack SEO service provider company specializing in ERP system development, AI-powered SaaS and business applications, full-stack SEO services, custom website development, and scalable eCommerce platforms. We design and develop intelligent, automation-driven SaaS and enterprise solutions that help startups, SMEs, NGOs, educational institutes, and large organizations streamline operations, enhance digital visibility, and accelerate growth through modern cloud-native technologies.

© 2026 CyberCraft Bangladesh · Released under the MIT License