Getting started

Install

Globally, as a command you can run from anywhere:

Or as a project devDependency, invoked through npx — this is what CI uses:

Requires Node.js ≥ 20 · Windows, macOS and Linux · MIT license.

Rendering browser

StoreShot renders through Chromium via playwright-core (installed automatically with the package). Download the rendering browser once:

Already have Chrome or Edge on the machine? Skip the download and reuse the system browser:

STORESHOT_BROWSER_CHANNEL=msedge storeshot generate

# Windows (cmd): set STORESHOT_BROWSER_CHANNEL=msedge first

Quick start

storeshot init my-app     # wizard: name, story, locales, template, theme
cd my-app
storeshot generate

The first render uses the bundled example app — Qamar, a bilingual task manager. Replace screens/*.png with your real screenshots and edit the copy in storeshot.config.json. Output lands in:

storeshots/<store-profile>/<locale>/01-….png   # exact verified dimensions

The config

One JSON file drives everything: screenshots × locales × device sizes. This is the starter project's real config (abridged):

{
  "$schema": "./node_modules/storeshot-cli/schema.json",
  "configVersion": 1,
  "app": {
    "name": "Qamar",
    "story": "A calm task manager for people who plan tomorrow the night before."
  },
  "locales": ["en-US", "ar"],
  "template": "editorial",
  "theme": { "background": "#0E1524", "accent": "#62E6B5", "text": "#FFFFFF" },
  "direction": { "ar": "rtl" },
  "screenshots": [
    {
      "id": "home",
      "role": "hero",
      "image": "./screens/home.png",
      "title": { "en-US": "Your day, beautifully under control",
                 "ar": "يومك تحت سيطرتك، بأناقة" }
    }
    /* …one entry per screenshot… */
  ],
  "exports": [
    { "store": "app-store",  "profile": "iphone-6-3" },
    { "store": "google-play", "profile": "phone" }
  ],
  "output": { "dir": "./storeshots" }
}

• role is an optional semantic tag (hero, feature, workflow, trust…) used by captions and sequence-aware layouts.
• theme.mode can be auto (derived from the background), light or dark; theme.surface overrides the elevated-panel token.
• Templates accept small curated settings — headlineScale, deviceScale, deviceMode and one or two per-template options.

Full field reference: docs/configuration.md

CLI reference

storeshot init [dir] [--force] [--yes]

Interactive project wizard: app name, story, locales, template, theme. Creates the starter project with a bilingual example app.

storeshot generate [-l locale…] [-e export…] [-o dir] [--allow-overflow]

Render all screenshots × locales × exports. Filter by locale or export, redirect output, or (not recommended) allow text overflow.

storeshot validate [--json] [--fast]

Validate config → assets → rendered text fit. --json for CI pipelines; --fast skips the browser-measured checks.

storeshot templates

List the template library and the settings each template accepts.

storeshot install

One-time download of the rendering browser (Chromium, ~170 MB).

Exit codes: 0 success · 1 layout/validation failure · 2 usage error. Network requests are blocked inside the renderer.

CI & automation

Because rendering is offline and deterministic, screenshots fit a pipeline like any other build artifact. Install as a devDependency, generate, then gate:

npm install --save-dev storeshot-cli
npx storeshot install        # one-time Chromium on the runner (~170 MB)
npx storeshot generate
npx storeshot validate --json

Exit codes are stable contracts: 0 success, 1 layout/validation failure, 2 usage error. Already have Chrome or Edge on the runner? Skip the Chromium download with STORESHOT_BROWSER_CHANNEL. Prefer designing by hand first? Prototype in the web editor, then reproduce the exact design deterministically from the config.

React Native, Expo, Flutter — any framework

StoreShot frames whatever PNG screenshots you hand it, so captures from React Native, Expo, Flutter or fully native apps all work. It does not integrate with any framework's toolchain, drive devices or capture screenshots for you — pair it with the capture tool you already use (for example the platform simulators, or your test runner's screenshot capability), then point screens/*.png at the output.

Localization is where the pairing pays off: one config entry per screenshot with per-locale titles, and the engine renders every locale at every export size — including Arabic RTL with connected letterforms and correct bidi order.

Store profiles

Every profile records when it was verified and against which official page. Verified 2026-10-10 against Apple's screenshot specifications, Apple creative assets specifications and Google Play store listing guidance.

Also shipped: iphone-6-1 1179×2556 and preview-frame-6-3 886×1920. Custom sizes are validated against store rules. Correct dimensions ≠ full compliance — StoreShot cannot check store policy; the profiles reference lists what remains yours.

Validation

storeshot validate fails the build before you ship bad assets. It catches:

• Schema violations
• Missing, corrupt, unsupported or low-resolution source screenshots
• Font fallbacks
• Missing translations — per screenshot, locale and field
• Unknown templates, profiles and settings
• Custom-size rule violations
• Low title/background contrast
• Rendered text overflow — per locale × screenshot × export size

It cannot judge taste or store policy — those stay yours.

Keep reading

• Configuration reference — every field, every rule.
• Templates & authoring guide — the library and how to build your own.
• Arabic & RTL guide — behavior, mixed-direction text, troubleshooting.
• Store profiles — verified dimensions with sources and dates.
• Template gallery — all fourteen templates with real renders.
• FAQ — the CLI vs the web editor, Arabic RTL, framework compatibility, privacy.