@amjadiqbal/start-seo-kit 0.0.0-stage → 0.1.1

package/dist/og.js

@@ -0,0 +1,142 @@
+// src/og.ts
+let resvgReady;
+async function loadResvg(wasm) {
+	resvgReady ??= (async () => {
+		const resvg = await import("@resvg/resvg-wasm");
+		const source = typeof wasm === "function" ? await wasm() : wasm ?? await nodeWasm();
+		await resvg.initWasm(source);
+		return resvg;
+	})().catch((error) => {
+		resvgReady = void 0;
+		throw error;
+	});
+	return resvgReady;
+}
+async function nodeWasm() {
+	try {
+		const { readFile } = await import("node:fs/promises");
+		const { createRequire } = await import("node:module");
+		return await readFile(createRequire(import.meta.url).resolve("@resvg/resvg-wasm/index_bg.wasm"));
+	} catch (error) {
+		throw new Error("start-seo-kit/og: could not load @resvg/resvg-wasm/index_bg.wasm. Install @resvg/resvg-wasm, or pass the wasm option, or use format: \"svg\".", { cause: error });
+	}
+}
+/** Render an element to PNG bytes (or an SVG string with `format: 'svg'`). */
+async function renderOgImage(element, options) {
+	const width = options.width ?? 1200;
+	const height = options.height ?? 630;
+	const { default: satori } = await import("satori");
+	const svg = await satori(element, {
+		width,
+		height,
+		fonts: options.fonts.map((f) => ({
+			...f,
+			data: toArrayBuffer(f.data)
+		}))
+	});
+	if (options.format === "svg") return svg;
+	const { Resvg } = await loadResvg(options.wasm);
+	const rendered = new Resvg(svg, { fitTo: {
+		mode: "width",
+		value: width
+	} }).render();
+	try {
+		return rendered.asPng();
+	} finally {
+		rendered.free();
+	}
+}
+/**
+* `GET` handler for an Open Graph image server route, e.g. `src/routes/og/$slug.ts`.
+* Point `seo({ image: '/og/my-post' })` at it.
+*/
+function createOgImageHandler(options) {
+	let fonts;
+	return async (ctx) => {
+		fonts ??= Promise.resolve(typeof options.fonts === "function" ? options.fonts() : options.fonts).catch((error) => {
+			fonts = void 0;
+			throw error;
+		});
+		const element = await options.render({
+			...ctx,
+			url: new URL(ctx.request.url)
+		});
+		if (element === null) return new Response("Not Found", { status: 404 });
+		const body = await renderOgImage(element, {
+			...options,
+			fonts: await fonts
+		});
+		return new Response(typeof body === "string" ? body : body, { headers: {
+			"Content-Type": typeof body === "string" ? "image/svg+xml" : "image/png",
+			"Cache-Control": options.cacheControl ?? "public, max-age=86400, immutable"
+		} });
+	};
+}
+/** A ready-made 1200x630 card (title, description, label, footer) as a plain element tree; no JSX needed. */
+function ogCard(input) {
+	const fg = input.foreground ?? "#F8FAFC";
+	const muted = input.muted ?? "#94A3B8";
+	const accent = input.accent ?? "#34D399";
+	const el = (style, children) => ({
+		type: "div",
+		props: {
+			style,
+			children
+		}
+	});
+	const titleSize = input.title.length > 60 ? 56 : input.title.length > 34 ? 68 : 80;
+	return el({
+		width: "100%",
+		height: "100%",
+		display: "flex",
+		flexDirection: "column",
+		background: input.background ?? "#0B1220",
+		color: fg,
+		fontFamily: input.fontFamily
+	}, [el({
+		display: "flex",
+		flexDirection: "column",
+		justifyContent: "space-between",
+		flexGrow: 1,
+		margin: "72px 80px"
+	}, [el({
+		display: "flex",
+		flexDirection: "column",
+		gap: 24
+	}, [
+		el({
+			display: "flex",
+			width: 96,
+			height: 8,
+			borderRadius: 4,
+			background: accent
+		}, []),
+		input.eyebrow ? el({
+			display: "flex",
+			fontSize: 30,
+			color: accent,
+			fontWeight: 600
+		}, input.eyebrow) : null,
+		el({
+			display: "flex",
+			fontSize: titleSize,
+			fontWeight: 700,
+			lineHeight: 1.1
+		}, input.title),
+		input.description ? el({
+			display: "flex",
+			fontSize: 32,
+			color: muted,
+			lineHeight: 1.35
+		}, input.description) : null
+	].filter(Boolean)), input.footer ? el({
+		display: "flex",
+		fontSize: 26,
+		color: muted
+	}, input.footer) : el({ display: "flex" }, [])])]);
+}
+function toArrayBuffer(data) {
+	if (data instanceof ArrayBuffer) return data;
+	return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+}
+export { createOgImageHandler, ogCard, renderOgImage };

package/dist/sitemap-BiQmwT37.d.ts

@@ -0,0 +1,99 @@
+type TrailingSlash = 'never' | 'always';
+/**
+ * Resolve a path or URL against the site. Absolute http(s) URLs are returned unchanged.
+ * Pass `trailingSlash` for page URLs only; asset URLs (images) keep their path as given.
+ */
+declare function absoluteUrl(siteUrl: string, pathOrUrl: string, trailingSlash?: TrailingSlash): string;
+type Awaitable<T> = T | Promise<T>;
+/** The context a TanStack Start server route handler receives (only the parts used here). */
+interface HandlerContext {
+  request: Request;
+  params?: Record<string, string | undefined> | object;
+}
+type ServerHandler = (ctx: HandlerContext) => Promise<Response>;
+type ChangeFreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+interface SitemapImage {
+  url: string;
+  title?: string;
+  caption?: string;
+}
+interface SitemapEntry {
+  /** Page path (`/posts/hello`) or absolute URL. */
+  loc: string;
+  lastmod?: string | Date;
+  changefreq?: ChangeFreq;
+  /** 0.0 to 1.0. */
+  priority?: number;
+  /** hreflang alternates, e.g. `{ en: '/en/about', de: '/de/about', 'x-default': '/about' }`. */
+  alternates?: Record<string, string>;
+  images?: Array<string | SitemapImage>;
+}
+interface UrlOptions {
+  siteUrl: string;
+  /** Match your router's `trailingSlash` option. Default `never`. */
+  trailingSlash?: TrailingSlash;
+}
+/** Render a `<urlset>` sitemap. */
+declare function sitemapXml(entries: Iterable<SitemapEntry>, options: UrlOptions): string;
+interface SitemapIndexEntry {
+  /** Path or absolute URL of a child sitemap. */
+  loc: string;
+  lastmod?: string | Date;
+}
+/** Render a `<sitemapindex>`. */
+declare function sitemapIndexXml(sitemaps: Iterable<SitemapIndexEntry>, options: UrlOptions): string;
+/**
+ * Where the URLs of one sitemap section come from:
+ * - an array of entries,
+ * - a function returning them (sync or async, e.g. a database query), called once per request
+ *   to `/sitemap.xml` and once per child-sitemap request, loading every entry each time, or
+ * - a paginated source with `count()` and `entries({ offset, limit })` for large sets:
+ *   the index calls only `count()`, and each child sitemap loads only its own range.
+ */
+type SitemapSource = SitemapEntry[] | (() => Awaitable<SitemapEntry[]>) | {
+  count: () => Awaitable<number>;
+  entries: (range: {
+    offset: number;
+    limit: number;
+  }) => Awaitable<SitemapEntry[]>;
+  lastmod?: () => Awaitable<string | Date | undefined>;
+};
+interface CreateSitemapOptions extends UrlOptions {
+  /** Named sections, e.g. `{ pages: routesFromTree(routeTree), posts: () => db.posts.list() }`. Names: letters, digits, `_`, `-`. */
+  sources: Record<string, SitemapSource>;
+  /** URLs per child sitemap. Default 50,000 (the protocol limit). */
+  maxUrlsPerSitemap?: number;
+  /**
+   * `auto` (default): `/sitemap.xml` is a plain urlset while everything fits in one file, and a sitemap index otherwise.
+   * `true`: always an index. `false`: always one urlset (throws past `maxUrlsPerSitemap`).
+   */
+  index?: 'auto' | boolean;
+  /** Path the child sitemaps are served under. Default `/sitemaps` (route file `src/routes/sitemaps/$name.ts`). */
+  basePath?: string;
+  /** `Cache-Control` header. Default `public, max-age=3600`. */
+  cacheControl?: string;
+}
+interface SitemapHandlers {
+  /** `GET` handler for `/sitemap.xml`. */
+  index: ServerHandler;
+  /** `GET` handler for `/sitemaps/$name` (child sitemaps such as `/sitemaps/posts-1.xml`). */
+  page: ServerHandler;
+  /** Every entry from every source (useful for tests and prerendering). */
+  entries(): Promise<SitemapEntry[]>;
+}
+/** Dynamic sitemap (and sitemap index for large sites) served from TanStack Start server routes. */
+declare function createSitemap(options: CreateSitemapOptions): SitemapHandlers;
+interface RoutesFromTreeOptions {
+  /** Paths to leave out: exact strings, or RegExps tested against the path. */
+  exclude?: Array<string | RegExp>;
+  /** Defaults for every entry (e.g. `{ changefreq: 'weekly' }`). */
+  defaults?: Partial<Omit<SitemapEntry, 'loc'>>;
+}
+/**
+ * Collect the static (parameter-free) page paths of your TanStack Router route tree.
+ * Dynamic routes (`$id`, `$`) are skipped: list them from your data in another source.
+ * Skipped too: server-only routes, paths with a file extension (`/sitemap.xml`), and routes with
+ * `staticData: { sitemap: false }`. Per-route `staticData.sitemap` values (priority, changefreq) are applied.
+ */
+declare function routesFromTree(routeTree: unknown, options?: RoutesFromTreeOptions): SitemapEntry[];
+export { absoluteUrl as _, ServerHandler as a, SitemapImage as c, UrlOptions as d, createSitemap as f, TrailingSlash as g, sitemapXml as h, RoutesFromTreeOptions as i, SitemapIndexEntry as l, sitemapIndexXml as m, CreateSitemapOptions as n, SitemapEntry as o, routesFromTree as p, HandlerContext as r, SitemapHandlers as s, ChangeFreq as t, SitemapSource as u };

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "@amjadiqbal/start-seo-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "SEO kit for TanStack Start: typed head() meta tags (title templates, canonical, Open Graph, Twitter cards, robots, hreflang), dynamic sitemap and robots.txt server routes, JSON-LD helpers, e-commerce Product schema and an optional Open Graph image route.",
+  "keywords": [
+    "tanstack",
+    "tanstack-start",
+    "tanstack-router",
+    "seo",
+    "meta-tags",
+    "sitemap",
+    "sitemap-index",
+    "robots-txt",
+    "json-ld",
+    "structured-data",
+    "ecommerce",
+    "product-schema",
+    "rich-results",
+    "open-graph",
+    "og-image",
+    "twitter-card",
+    "hreflang"
+  ],
+  "homepage": "https://github.com/amjadiqbal/start-seo-kit#readme",
+  "bugs": "https://github.com/amjadiqbal/start-seo-kit/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amjadiqbal/start-seo-kit.git"
+  },
+  "license": "MIT",
+  "author": "Amjad Iqbal (https://amjad.com.pk)",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./commerce": {
+      "types": "./dist/commerce.d.ts",
+      "default": "./dist/commerce.js"
+    },
+    "./og": {
+      "types": "./dist/og.d.ts",
+      "default": "./dist/og.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src tests",
+    "test": "vitest run",
+    "ci": "bash scripts/ci-local.sh"
+  },
+  "peerDependencies": {
+    "@resvg/resvg-wasm": "^2.6.0",
+    "satori": ">=0.10.0"
+  },
+  "peerDependenciesMeta": {
+    "@resvg/resvg-wasm": {
+      "optional": true
+    },
+    "satori": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@fontsource/inter": "^5.3.0",
+    "@resvg/resvg-wasm": "^2.6.2",
+    "@tanstack/react-router": "^1.170.45",
+    "@tanstack/react-start": "^1.169.3",
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "oxlint": "^1.89.0",
+    "publint": "^0.3.25",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "satori": "^0.63.2",
+    "tsdown": "^0.23.1",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.5"
+  }
+}