Docs
Write designs by hand
Read straight from the repo's own README.md — single source, never duplicated here.
Write designs by hand (CLI)
npm install -g @snap-x/cli # or skip installing: npx -y @snap-x/cli …
snap-x version # confirm installed version
snap-x check designs/*.mjs # validate (structure, a real render, blank-box glyphs, store-alpha)
snap-x render designs/*.mjs --out snap-output
snap-x render designs/*.mjs --format svg # SVG output — skips resvg, resolution-independent
snap-x render designs/*.mjs --format png # PNG output (default)
snap-x formats # YouTube, X, LinkedIn, Play Store, App Store … sizes + placement zones
snap-x guides designs/*.mjs # draw a platform's danger zones (+ mobile crop) over your designs
Paths can be a file, a directory, or a * glob. Files starting with _ are shared helpers and are never rendered (even when your shell expands the glob). --out defaults to ./snap-output.
snap-x watch designs/*.mjs [--guides] is a dev tool: it renders once, opens a local preview page (prints the URL) listing every output image, then re-renders and auto-reloads the page whenever a design file changes. --guides also runs the placement check on every change.
--format <png|svg> (on render) sets the output format. Default is png. svg skips the resvg raster step and writes the Satori SVG string directly — useful for vector workflows, editors, or post-processing. --scale is ignored for SVG (it's resolution-independent). Note: on the guides command, --format takes a platform format id (e.g. youtube-thumbnail), not an output format.
--scale <n> (on render and check) renders sharp at n× resolution — the design's layout is unchanged; only the raster output grows, the same way a browser re-renders an SVG sharply at any zoom. Output is named <name>@<n>x.png (e.g. og@2x.png). Ignored when --format svg is set.
render renders concurrently by default — a small worker_threads pool sized to your CPU count (measured ~2× faster on a 6-file pack with large images). Console output always lists files in their original order regardless of which finishes first, and a failing file is reported without stopping the others. --jobs 1 renders one file at a time on the main thread, exactly as before this existed; --jobs <n> picks any other pool size.
A design file
.jsx and .tsx work too — same rules, transformed at load time (esbuild, no React), and usually easier to read:
export const FORMAT = { width: 1200, height: 630, name: "og.png" };
export const FONTS = [{ family: "Inter", weights: [400, 700, 900] }]; // optional, default Inter
export default function () { // zero arguments; may be async
return (
<div style={{ width: 1200, height: 630, background: "#000", display: "flex", alignItems: "center", justifyContent: "center" }}>
<div style={{ color: "#fff", fontSize: 64, fontWeight: 900, display: "flex" }}>Hello</div>
</div>
);
}
The equivalent .mjs (the plain object tree Satori actually receives — this is what .jsx/.tsx compile down to, and what the /snap-x skill writes by default):
export default function () {
return {
type: "div",
props: {
style: { width: 1200, height: 630, background: "#000", display: "flex", alignItems: "center", justifyContent: "center" },
children: [{ type: "div", props: { style: { color: "#fff", fontSize: 64, fontWeight: 900, display: "flex" }, children: ["Hello"] } }],
},
};
}
Everything the image needs lives in the file: colors, copy, fonts, size. There's no config file and no auto-detection.
Rules (Satori): every container needs display: "flex"; children is always an array; text is a string in children; no z-index, CSS grid, animations or position: "fixed". snap-x check catches these.
In JSX: a function component (<Chip label="x" />) is called immediately with its props — there's no reconciliation to defer to for a one-shot render — so check sees the same fully-resolved tree either way. Fragments (<>...</>) splice their children straight in. A _-prefixed helper works exactly like it does for .mjs, imported with a normal relative path.
Fonts: any Google Font via FONTS, per file. Fonts are cached on disk ($SNAP_X_CACHE_DIR, else ~/.cache/snap-x/fonts) so repeat renders are fast and work offline. CJK, Korean, Arabic, Hebrew, Thai, Devanagari and Bengali get an automatic Noto fallback. Emoji work (drawn as Twemoji images, cached). Other symbols the font lacks (✓, and → in some fonts) render as blank boxes — snap-x check warns about them; draw them as SVG.
Logos and images: make the export async and embed base64 <img> nodes. Resolve paths from the design file so it renders from any directory:
import fs from "fs/promises";
import { fileURLToPath } from "url";
const asset = async (rel, mime) =>
`data:${mime};base64,${(await fs.readFile(fileURLToPath(new URL(rel, import.meta.url)))).toString("base64")}`;
// { type: "img", props: { src: await asset("../assets/logo.png", "image/png"), width: 231, height: 44 } }
PNG, JPEG and SVG work. AVIF and WebP don't (convert to PNG), and an SVG containing <text> must be rasterised first. Give both width and height, at the file's real aspect ratio.
Variants — one template, many images: export VARIANTS (an array, or an async function returning one) and the default export is called once per row instead of once with no arguments:
export const FORMAT = { width: 1280, height: 720, name: "episode.png" };
export const VARIANTS = [
{ id: "ep-01", title: "Setting up", number: 1 },
{ id: "ep-02", title: "First render", number: 2 },
];
export default function (variant) { // receives one row when VARIANTS exists
return { /* tree using variant.title, variant.number */ };
}
// → episode-ep-01.png, episode-ep-02.png
Each row needs a unique string id; output is named <name-stem>-<id>.<ext> unless a row's own format: { name } overrides it. check and guides run every row (labeling failures with the id); render --only <id,id> renders a subset. Without VARIANTS, a design behaves exactly as before — this is opt-in.
MCP server
{ "mcpServers": { "snap-x": { "command": "npx", "args": ["@snap-x/mcp"] } } }
Tools: render_designs, check_designs, preview_guides, list_formats. The agent writes the .mjs files; the server renders and validates them. For agents without the skill it also serves the design rules: a snap-x://design-guide resource and a design_cards prompt.
Security: design files are JavaScript and run with this server's own permissions when rendered or checked — only point it at design files you trust. Set SNAP_X_ROOT to restrict every tool to one directory (symlinks resolved); unset by default, so existing setups are unaffected. See packages/mcp/README.md.