@aklinker1/viteshot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+<div align="center">
+
+# ViteShot
+
+Build and generate store screenshots and promo images with code, powered by Vite.
+
+</div>
+
+## Why?
+
+With AI, it's common for developers with less design experience to generate store screenshots and promo images. However, one shot image generation models aren't very good at this yet.
+
+However, AI is really good at building *simple* UIs with HTML! ViteShot provides a simple way for agents in your preferred dev environment to create and generate images in a structured, easy-to-iterate way.
+
+## Get Started
+
+1. Add Vite and ViteShot as dev dependencies to your project:
+
+   ```sh
+   bun add -D vite @aklinker1/viteshot
+   ```
+
+2. Initialize the `./store` directory:
+
+   ```sh
+   bun viteshot init ./store
+   ```
+
+3. Add the following scripts to your `package.json`:
+
+   ```sh
+   {
+     "scripts": {
+       "store:dev": "viteshot dev ./store",
+       "store:generate": "viteshot generate ./store",
+     }
+   }
+   ```
+
+Then generate your screenshots with `bun store:generate`! Screenshots will be output to `store/screenshots`.
+
+## Design Files
+
+Your screenshot designs go in `store/designs/{name}@{width}x{height}.{ext}`.
+
+- `{name}`: The name of your screenshot, it can be anything (ex: "small-marquee", "screenshot-1", etc).
+- `{width}x{height}`: The size your screenshot should be rendered at (ex: "1280x600", "640x400").
+- `{ext}`: ViteShot supports a variety of file extensions, so you can build your designs using your preferred frontend framework!
+
+### HTML (Recommended)
+
+You don't need a frontend framework to build a simple static layout.
+
+```html
+<div>My screenshot design</div>
+```
+
+### Vue
+
+TODO
+
+### Svelte
+
+TODO
+
+### React
+
+TODO
+
+## Styling
+
+1. Setup your framework (like installing the TailwindCSS Vite plugin)
+2. In your screenshots file, `<link>` to your CSS file, import your CSS file, or import your UI framework's components
+
+And that's it!
+
+## Assets
+
+Create an `assets` directory and reference them via `assets/<filename>`. Vite will load them.

package/assets/dashboard.ts

@@ -0,0 +1,85 @@
+/** Main JS module for displaying the different screenshots */
+import screenshots from "viteshot-virtual/screenshots";
+import locales from "viteshot-virtual/locales";
+
+declare const app: HTMLDivElement;
+
+// Language management
+
+const CURRENT_LANGUAGE_STORAGE_KEY = "viteshot:current-language";
+
+let currentLanguageId: string | undefined = locales[0]?.language;
+
+function restoreLanguage() {
+  const oldId = localStorage.getItem(CURRENT_LANGUAGE_STORAGE_KEY);
+  if (!oldId) return;
+
+  const oldLocale = locales.find((l) => l.id === oldId);
+  if (!oldLocale) return;
+
+  currentLanguageId = oldId;
+}
+
+function setLanguage(languageId: string): void {
+  currentLanguageId = languageId;
+  localStorage.setItem(CURRENT_LANGUAGE_STORAGE_KEY, languageId);
+}
+
+// UI Rendering
+
+function renderScreenshots() {
+  app.innerHTML = "";
+
+  const header = document.createElement("div");
+  {
+    header.className = "header";
+
+    const h1 = document.createElement("h1");
+    h1.textContent = "Dashboard";
+    header.append(h1);
+
+    if (locales.length > 0) {
+      const select = document.createElement("select");
+
+      for (const locale of locales) {
+        const option = document.createElement("option");
+        option.value = locale.id;
+        option.textContent = locale.language;
+        select.append(option);
+      }
+
+      if (currentLanguageId) select.value = currentLanguageId;
+
+      select.addEventListener("change", () => {
+        setLanguage(select.value);
+        renderScreenshots();
+      });
+
+      header.append(select);
+    }
+  }
+  app.append(header);
+
+  const listItems = screenshots.map((screenshot) => {
+    const li = document.createElement("li");
+    li.id = screenshot.id;
+    li.className = "list-item";
+
+    const p = document.createElement("p");
+    p.textContent = screenshot.name;
+    li.append(p);
+
+    const iframe = document.createElement("iframe");
+    iframe.src = `/screenshot/${currentLanguageId ? encodeURIComponent(currentLanguageId) : "null"}/${encodeURIComponent(screenshot.id)}`;
+    if (screenshot.width) iframe.width = String(screenshot.width);
+    if (screenshot.width) iframe.height = String(screenshot.height);
+    li.append(iframe);
+
+    return li;
+  });
+
+  app.append(...listItems);
+}
+
+restoreLanguage();
+renderScreenshots();

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,18 @@
+import { n as createServer, t as generateScreenshots } from "./generate-screenshots-bbolMzf5.mjs";
+
+//#region src/cli.ts
+const [command, ..._args] = process.argv.slice(2);
+switch (command) {
+	case "dev":
+		const server = await createServer("example");
+		await server.listen();
+		server.printUrls();
+		break;
+	case "generate":
+		await generateScreenshots("example");
+		process.exit(0);
+	default: break;
+}
+
+//#endregion
+export {  };

package/dist/generate-screenshots-bbolMzf5.mjs

@@ -0,0 +1,300 @@
+import { dirname, extname, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { mkdir, readFile, readdir, rm } from "node:fs/promises";
+import natsort from "natural-compare-lite";
+import { createServer } from "vite";
+import puppeteer from "puppeteer-core";
+import pMap from "p-map";
+import { Mutex } from "async-mutex";
+
+//#region src/templates/favicon.svg?raw
+var favicon_default = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 100 100\" width=\"200\" height=\"200\">\n  <polygon points=\"50,15 61,40 88,40 66,57 74,82 50,65 26,82 34,57 12,40 39,40\" fill=\"yellow\" stroke=\"black\" stroke-width=\"1\"/>\n</svg>\n";
+
+//#endregion
+//#region src/templates/dashboard.html?raw
+var dashboard_default = "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"UTF-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n    <title>Viteshot</title>\n    <link rel=\"icon\" type=\"image/svg+xml\" href=\"/favicon.svg\" />\n    <style>\n      * {\n        margin: 0;\n        padding: 0;\n        box-sizing: border-box;\n        min-width: 0;\n        min-height: 0;\n        list-style: none;\n      }\n\n      .app {\n        display: flex;\n        flex-direction: column;\n        gap: 1rem;\n        padding: 1rem;\n      }\n      .header {\n        display: flex;\n        align-items: center;\n        gap: 1rem;\n      }\n      .header h1 {\n        flex: 1;\n      }\n      .header select {\n        flex-shrink: 0;\n        padding-left: 0.25rem;\n      }\n      .list-item {\n        display: flex;\n        flex-direction: column;\n        gap: 0.5rem;\n      }\n    </style>\n  </head>\n  <body>\n    <div id=\"app\" class=\"app\"></div>\n    <script type=\"module\" src=\"/viteshot-assets/dashboard.ts\"><\/script>\n  </body>\n</html>\n";
+
+//#endregion
+//#region src/templates/screenshot.html?raw
+var screenshot_default = "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"UTF-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n    <title>Screenshot</title>\n    <link rel=\"icon\" type=\"image/svg+xml\" href=\"/favicon.svg\" />\n    <style>\n      body {\n        margin: 0;\n        padding: 0;\n      }\n    </style>\n  </head>\n  <body>\n    <div id=\"app\" class=\"app\"></div>\n    <script type=\"module\">\n      import { renderScreenshot } from \"/viteshot-virtual/render-screenshot/{{screenshot.id}}\";\n      import messages from \"/viteshot-virtual/messages/{{locale.id}}\";\n\n      renderScreenshot(app, messages);\n    <\/script>\n  </body>\n</html>\n";
+
+//#endregion
+//#region src/templates/render-html-screenshot.js?raw
+var render_html_screenshot_default = "import HTML from \"/@fs/{{path}}?raw\";\n\nexport function renderScreenshot(container, messages) {\n  container.innerHTML = Object.entries(messages).reduce(\n    (text, [key, value]) => text.replaceAll(`{{${key}}}`, value),\n    HTML,\n  );\n}\n";
+
+//#endregion
+//#region src/utils.ts
+async function getViteshotAssetsDir() {
+	if (process.env.DEV) return resolve("assets");
+	else return import.meta.resolve("viteshot");
+}
+
+//#endregion
+//#region src/core/get-locales.ts
+async function getLocales(localesDir) {
+	const jsonFilenames = (await readdir(localesDir, {})).filter((file) => file.endsWith(".json"));
+	return await Promise.all(jsonFilenames.map(async (file) => {
+		const ext = extname(file);
+		const text = await readFile(join(localesDir, file), "utf-8");
+		const messages = JSON.parse(text);
+		return {
+			id: file,
+			language: file.slice(0, -ext.length),
+			messages
+		};
+	}));
+}
+
+//#endregion
+//#region src/core/get-screenshots.ts
+async function getScreenshots(designsDir) {
+	return (await readdir(designsDir, {
+		recursive: true,
+		withFileTypes: true
+	})).filter((file) => file.isFile()).map((file) => {
+		const path = join(file.parentPath, file.name);
+		const ext = extname(file.name);
+		const filenameNoExt = file.name.slice(0, -ext.length);
+		const [name, size] = filenameNoExt.split("@", 2);
+		const [width, height] = size ? size.split("x").map((value) => Number(value)) : [];
+		return {
+			id: relative(designsDir, path),
+			path,
+			ext,
+			filenameNoExt,
+			name,
+			size,
+			width,
+			height
+		};
+	}).toSorted((a, b) => natsort(a.id, b.id));
+}
+
+//#endregion
+//#region src/core/resolver-plugin.ts
+function resolveTemplate(options) {
+	return (server) => () => server.middlewares.use(async (req, res, next) => {
+		if (!req.originalUrl) return;
+		const url = new URL(req.originalUrl, "http://localhost");
+		if (!options.match(url)) return next();
+		const text = options.vars == null ? options.template : applyTemplateVars(options.template, options.vars(url));
+		return res.end(options.transform ? await server.transformIndexHtml(req.originalUrl, text) : text);
+	});
+}
+const VIRTUAL_SCREENSHOTS_FILTER = { id: [/viteshot-virtual\/screenshots/] };
+const VIRTUAL_LOCALES_FILTER = { id: [/viteshot-virtual\/locales/] };
+function applyTemplateVars(template, vars) {
+	return Object.entries(vars).reduce((template, [key, value]) => template.replaceAll(`{{${key}}}`, value), template);
+}
+const RENDER_SCREENSHOT_JS_TEMPLATES = { ".html": render_html_screenshot_default };
+const resolverPlugin = (config) => [
+	{
+		name: "viteshot:resolve-favicon",
+		configureServer: resolveTemplate({
+			match: (url) => url.pathname === "/favicon.svg",
+			template: favicon_default
+		})
+	},
+	{
+		name: "viteshot:resolve-dashboard-html",
+		configureServer: resolveTemplate({
+			match: (url) => url.pathname === "/",
+			template: dashboard_default,
+			transform: true
+		})
+	},
+	{
+		name: "viteshot:resolve-screenshot-html",
+		configureServer: resolveTemplate({
+			match: (url) => /\/screenshot\/.*?\/.*?/.test(url.pathname),
+			template: screenshot_default,
+			transform: true,
+			vars: (url) => {
+				const [localeId, screenshotId] = url.pathname.slice(12).split("/");
+				return {
+					"screenshot.id": screenshotId,
+					"locale.id": localeId
+				};
+			}
+		})
+	},
+	{
+		name: "viteshot:resolve-assets",
+		resolveId: {
+			filter: { id: [/\/viteshot-assets\//] },
+			handler: async (id) => {
+				return join(await getViteshotAssetsDir(), id.slice(17));
+			}
+		}
+	},
+	{
+		name: "viteshot:resolve-virtual:screenshots",
+		resolveId: {
+			filter: VIRTUAL_SCREENSHOTS_FILTER,
+			handler: (id) => id
+		},
+		load: {
+			filter: VIRTUAL_SCREENSHOTS_FILTER,
+			handler: async () => {
+				const screenshots = await getScreenshots(config.designsDir);
+				return `export default ${JSON.stringify(screenshots)}`;
+			}
+		}
+	},
+	{
+		name: "viteshot:resolve-virtual:locales",
+		resolveId: {
+			filter: VIRTUAL_LOCALES_FILTER,
+			handler: (id) => id
+		},
+		load: {
+			filter: VIRTUAL_LOCALES_FILTER,
+			handler: async () => {
+				const locales = await getLocales(config.localesDir);
+				return `export default ${JSON.stringify(locales)}`;
+			}
+		}
+	},
+	{
+		name: "viteshot:resolve-virtual:render-screenshot",
+		resolveId: {
+			filter: { id: [/^\/viteshot-virtual\/render-screenshot/] },
+			handler: (id) => id
+		},
+		load: {
+			filter: { id: [/^\/viteshot-virtual\/render-screenshot/] },
+			handler: (id) => {
+				const screenshotId = decodeURIComponent(id.slice(36));
+				if (!screenshotId) throw Error(`Required query param "id" not provided for ${id}`);
+				const ext = extname(screenshotId);
+				const path = join(config.designsDir, screenshotId);
+				const template = RENDER_SCREENSHOT_JS_TEMPLATES[ext];
+				if (!template) throw Error(`Unsupported screenshot file type (${ext}). Must be one of ${Object.keys(RENDER_SCREENSHOT_JS_TEMPLATES).join(", ")}`);
+				return applyTemplateVars(template, { path });
+			}
+		}
+	},
+	{
+		name: "viteshot:resolve-virtual:messages",
+		resolveId: {
+			filter: { id: [/\/viteshot-virtual\/messages/] },
+			handler: (id) => {
+				const localeId = id.slice(27);
+				if (!localeId) throw Error(`Required query param "id" not provided for ${id}`);
+				return join(config.localesDir, localeId);
+			}
+		}
+	}
+];
+
+//#endregion
+//#region src/core/config.ts
+function defineConfig(config) {
+	return config;
+}
+async function importConfig(root) {
+	const configFileUrl = pathToFileURL(join(root, "viteshot.config")).href;
+	try {
+		return (await import(configFileUrl)).default ?? {};
+	} catch (err) {
+		if (err?.message?.includes?.("Cannot find module")) return {};
+		throw err;
+	}
+}
+async function resolveConfig(dir = process.cwd()) {
+	const root = resolve(dir);
+	const { localesDir: _localesDir, designsDir: _designsDir, screenshotsDir: _screenshotsDir, screenshotsConcurrency: _screenshotsConcurrency, ...vite } = await importConfig(root);
+	const designsDir = _designsDir ? resolve(root, _designsDir) : join(root, "designs");
+	const screenshotsDir = _screenshotsDir ? resolve(root, _screenshotsDir) : join(root, "screenshots");
+	const config = {
+		root,
+		localesDir: _localesDir ? resolve(root, _localesDir) : join(root, "locales"),
+		designsDir,
+		screenshotsDir,
+		screenshotsConcurrency: _screenshotsConcurrency || 1,
+		vite: {
+			...vite,
+			configFile: false
+		}
+	};
+	config.vite.plugins ??= [];
+	config.vite.plugins.push(resolverPlugin(config));
+	config.vite.resolve ??= {};
+	config.vite.resolve.external ??= [];
+	const external = config.vite.resolve.external;
+	if (Array.isArray(external)) external.push("viteshot-assets/dashboard.ts", "viteshot-assets/screenshot.ts", "viteshot-virtual/render-screenshot?id={{screenshot.id}}", "viteshot-virtual/locale?id={{locale.id}}");
+	return config;
+}
+
+//#endregion
+//#region src/core/create-server.ts
+async function createServer$1(dir) {
+	return createServer((await resolveConfig(dir)).vite);
+}
+
+//#endregion
+//#region src/core/generate-screenshots.ts
+async function generateScreenshots(dir) {
+	const config = await resolveConfig(dir);
+	const cwd = process.cwd();
+	const screenshots = await getScreenshots(config.designsDir);
+	const locales = await getLocales(config.localesDir);
+	console.log(`\n\x1b[1mGenerating ${screenshots.length * (locales.length || 1)} screenshots...\x1b[0m\n`);
+	let server;
+	let browser;
+	try {
+		await rm(config.screenshotsDir, {
+			recursive: true,
+			force: true
+		});
+		await mkdir(config.screenshotsDir, { recursive: true });
+		server = await createServer(config.vite);
+		server.listen();
+		const { port } = server.config.server;
+		browser = await puppeteer.launch({ executablePath: process.env.VITESHOT_CHROME_PATH });
+		const screenshotMutex = new Mutex();
+		await pMap(screenshots.flatMap((screenshot) => locales.map((locale) => ({
+			screenshot,
+			locale
+		}))), async ({ screenshot, locale }) => {
+			const outputId = (locale ? `${locale.language}/` : "") + screenshot.id.slice(0, -screenshot.ext.length) + ".webp";
+			const outputPath = join(config.screenshotsDir, outputId);
+			await mkdir(dirname(outputPath), { recursive: true });
+			const page = await browser.newPage({ background: true });
+			await page.goto(`http://localhost:${port}/screenshot/${locale?.id ?? "null"}/${screenshot.id}`, {
+				waitUntil: "networkidle0",
+				timeout: 5e3
+			});
+			await screenshotMutex.runExclusive(async () => {
+				await page.bringToFront();
+				await page.screenshot({
+					captureBeyondViewport: true,
+					clip: {
+						x: 0,
+						y: 0,
+						width: screenshot.width,
+						height: screenshot.height
+					},
+					type: "webp",
+					quality: 100,
+					path: outputPath
+				});
+			});
+			console.log(`  ✅ \x1b[2m./${relative(cwd, config.screenshotsDir)}/\x1b[0m\x1b[36m${outputId}\x1b[0m`);
+			await page.close();
+		}, {
+			concurrency: config.screenshotsConcurrency,
+			stopOnError: true
+		});
+	} catch (err) {
+		if (err?.message === "An `executablePath` or `channel` must be specified for `puppeteer-core`") throw Error(`Chromium not detected. Set the VITESHOT_CHROME_PATH env var to your Chromium executable.`);
+		else throw err;
+	} finally {
+		await browser?.close().catch(() => {});
+		await server?.close().catch(() => {});
+		console.log("");
+	}
+}
+
+//#endregion
+export { getScreenshots as a, resolveConfig as i, createServer$1 as n, defineConfig as r, generateScreenshots as t };

package/dist/index.d.mts

@@ -0,0 +1,43 @@
+import { InlineConfig as InlineConfig$1, UserConfig as UserConfig$1, ViteDevServer } from "vite";
+
+//#region src/core/config.d.ts
+type UserConfig = UserConfig$1 & {
+  localesDir?: string;
+  designsDir?: string;
+  screenshotsDir?: string;
+  screenshotsConcurrency?: number;
+};
+type InlineConfig = UserConfig & {
+  root: string;
+};
+type ResolvedConfig = {
+  root: string;
+  localesDir: string;
+  designsDir: string;
+  screenshotsDir: string;
+  screenshotsConcurrency: number;
+  vite: InlineConfig$1;
+};
+declare function defineConfig(config: UserConfig): UserConfig;
+declare function resolveConfig(dir?: string): Promise<ResolvedConfig>;
+//#endregion
+//#region src/core/create-server.d.ts
+declare function createServer(dir?: string): Promise<ViteDevServer>;
+//#endregion
+//#region src/core/generate-screenshots.d.ts
+declare function generateScreenshots(dir?: string): Promise<void>;
+//#endregion
+//#region src/core/get-screenshots.d.ts
+type Screenshot = {
+  id: string;
+  path: string;
+  ext: string;
+  filenameNoExt: string;
+  name: string;
+  size: string | undefined;
+  width: number | undefined;
+  height: number | undefined;
+};
+declare function getScreenshots(designsDir: string): Promise<Screenshot[]>;
+//#endregion
+export { InlineConfig, ResolvedConfig, Screenshot, UserConfig, createServer, defineConfig, generateScreenshots, getScreenshots, resolveConfig };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { a as getScreenshots, i as resolveConfig, n as createServer, r as defineConfig, t as generateScreenshots } from "./generate-screenshots-bbolMzf5.mjs";
+
+export { createServer, defineConfig, generateScreenshots, getScreenshots, resolveConfig };

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@aklinker1/viteshot",
+  "description": "Build and generate store screenshots and promo images with code, powered by Vite",
+  "version": "0.1.0",
+  "type": "module",
+  "packageManager": "bun@1.3.9",
+  "scripts": {
+    "viteshot": "bun run -d process.env.DEV:\"true\" src/cli.ts",
+    "dev": "bun viteshot dev example",
+    "generate": "bun viteshot generate example",
+    "build": "tsdown src/index.ts src/cli.ts"
+  },
+  "dependencies": {
+    "async-mutex": "^0.5.0",
+    "natural-compare-lite": "^1.4.0",
+    "p-map": "^7.0.4",
+    "p-queue": "^9.1.0",
+    "puppeteer-core": "^24.37.5"
+  },
+  "peerDependencies": {
+    "vite": "^5 || ^6 || ^7"
+  },
+  "devDependencies": {
+    "@aklinker1/check": "^2.2.0",
+    "@types/bun": "latest",
+    "@types/natural-compare-lite": "^1.4.2",
+    "@typescript/native-preview": "^7.0.0-dev.20260223.1",
+    "oxlint": "^1.50.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-jsdoc": "^1.8.0",
+    "publint": "^0.3.17",
+    "puppeteer": "^24.37.5",
+    "tsdown": "^0.20.3",
+    "typescript": "^5",
+    "vite": "^7.3.1"
+  },
+  "types": "dist/index.d.mts",
+  "module": "dist/index.mjs",
+  "bin": {
+    "viteshot": "dist/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "license": "MIT",
+  "author": {
+    "email": "aaronklinker1@gmail.com",
+    "name": "Aaron Klinker"
+  },
+  "homepage": "https://jsr.io/@aklinker1/viteshot",
+  "repository": {
+    "url": "https://github.com/aklinker1/viteshot"
+  },
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "vite",
+    "promo",
+    "images",
+    "screenshot",
+    "generate",
+    "store"
+  ]
+}