appshots

Turn raw app screenshots into App Store-ready promotional images — from the CLI.

What it does

Take any screenshot from your app and turn it into a polished, store-ready image with one command:

npx appshots frame screenshot.png \
  --device iphone-6.9 \
  --background "linear-gradient(135deg, #667eea, #764ba2)" \
  --title "AI Menu Analysis" \
  --subtitle "Ranked by your goals"

appshots handles three things:

1. Frame — wrap raw screenshots in realistic device frames with backgrounds, shadows, and text
2. Capture — screenshot a running web app at exact device pixel ratios
3. Validate — check dimensions, format, and file size against store requirements

26 built-in device presets: iPhone, iPad, Android, Mac, Apple Watch, Apple TV, Vision Pro.

Install

npm install -g appshots

Or run directly without installing:

npx appshots frame ./my-screenshots --device iphone-6.9

Note: The capture command requires Playwright (npm i -D playwright). The frame and validate commands work without it.

Quick Start

1. Frame existing screenshots

You already have screenshots from your simulator, phone, or browser. Make them store-ready:

# Simple — just resize to exact App Store dimensions
appshots frame ./screenshots --device iphone-6.9

# Promotional — add background gradient and text
appshots frame ./screenshots \
  --device iphone-6.9 \
  --background "linear-gradient(135deg, #667eea, #764ba2)" \
  --title "Your App Name" \
  --subtitle "Your tagline here"

# Alternate text position (text on top, phone from bottom)
appshots frame ./screenshots --device iphone-6.9 \
  --background "linear-gradient(170deg, #134E4A, #14B8A6)" \
  --title "Scan Any Menu" --subtitle "Photo, URL, or PDF" \
  --text-position top

# Silver device frame
appshots frame ./screenshots --device iphone-6.9 \
  --background "linear-gradient(135deg, #f093fb, #f5576c)" \
  --frame-color silver --title "Premium Look"

# Pattern background
appshots frame ./screenshots --device iphone-6.9 \
  --background "#1a1a2e" --pattern dots --title "Dashboard"

# Process a single file
appshots frame home.png --device iphone-6.9 -o ./store-ready

2. Capture from a running web app

Point appshots at your running app and it captures pixel-perfect screenshots:

# Capture specific pages
appshots capture --url http://localhost:3000 --device iphone-6.9 --path / /features /pricing

# Use a config file for repeatable captures
appshots capture --config appshots.config.ts

3. Validate before uploading

Check that your screenshots meet App Store / Play Store requirements:

appshots validate ./screenshots
#   ✓ home.png         1320x2868  (iPhone 6.9")
#   ✓ results.png      1320x2868  (iPhone 6.9")
#   ✗ old-screen.png   1080x1920  → PNG has transparency. App Store requires no transparency.

4. List device presets

appshots devices
appshots devices --platform ios
appshots devices --category tablet

5. Generate a config file

appshots init
# Creates appshots.config.ts in the current directory

Config File

For repeatable workflows, create an appshots.config.ts:

import { defineConfig } from 'appshots';

export default defineConfig({
  devices: ['iphone-6.9', 'ipad-13'],

  frame: {
    background: 'linear-gradient(135deg, #667eea, #764ba2)',
    padding: 0.08,
    borderRadius: 0.04,
    titleColor: '#ffffff',
    subtitleColor: 'rgba(255,255,255,0.7)',
    shadow: true,
    frameColor: 'black',
    textPosition: 'bottom',
    pattern: 'dots',
    patternOpacity: 0.1,
  },

  capture: {
    baseUrl: 'http://localhost:3000',
    screens: [
      {
        name: 'home',
        path: '/',
        title: 'Welcome Home',
        subtitle: 'Everything you need',
        waitFor: 'Welcome',
      },
      {
        name: 'features',
        path: '/features',
        title: 'Powerful Features',
        delay: 2000,
      },
    ],
  },

  output: './screenshots',
});

Also supports .js, .mjs, and .json formats.

CLI Reference

appshots frame <input>

Option	Description	Default
-d, --device <slug>	Target device preset	iphone-6.9
-o, --output <dir>	Output directory	./screenshots/framed
-b, --background <value>	Solid color or CSS gradient	#000000
-t, --title <text>	Title text overlay	—
-s, --subtitle <text>	Subtitle text overlay	—
--padding <ratio>	Padding ratio (0–0.4)	0.08
--border-radius <ratio>	Corner radius ratio (0–0.2)	0.04
--landscape	Landscape orientation	—
--no-shadow	Disable drop shadow	—
--no-device-frame	Disable device frame bezel	—
--frame-color <color>	Frame color: black, silver, gold, blue, red, white, or hex	black
--pattern <name>	Background pattern: dots, grid, diagonal, waves, diamonds, cross-dots	—
--pattern-opacity <ratio>	Pattern opacity (0–1)	0.1
--text-position <pos>	Text position: top or bottom	bottom
-c, --config <path>	Config file path	—

appshots capture

Option	Description	Default
-u, --url <url>	Base URL of the running app	http://localhost:3000
-d, --device <slug>	Target device preset	iphone-6.9
-p, --path <paths...>	URL paths to capture	—
-o, --output <dir>	Output directory	./screenshots
--landscape	Landscape orientation	—
-c, --config <path>	Config file path	—

appshots validate <dir>

Checks: dimensions, format (PNG/JPEG), transparency, file size (< 10 MB), color space (sRGB).

appshots devices

Option	Description
--platform <name>	Filter by platform (ios, android, macos, watchos, tvos, visionos)
--category <name>	Filter by category (phone, tablet, desktop, watch, tv, headset)

Device Presets

Slug	Dimensions	Devices
iphone-6.9	1320 x 2868	iPhone Air, 17 Pro Max, 16 Pro Max
iphone-6.9-alt	1290 x 2796	iPhone 16 Plus, 15 Pro Max
iphone-6.5	1284 x 2778	iPhone 14 Plus, 13 Pro Max
iphone-6.3	1206 x 2622	iPhone 17 Pro, 17
iphone-6.3-alt	1179 x 2556	iPhone 16 Pro, 16, 15 Pro
iphone-6.1	1170 x 2532	iPhone 14, 13, 12
iphone-5.5	1242 x 2208	iPhone 8 Plus, 7 Plus
ipad-13	2064 x 2752	iPad Pro M5/M4, iPad Air M3
ipad-11	1668 x 2388	iPad Pro 11", iPad Air
android-phone	1080 x 1920	Standard Android (16:9)
android-phone-tall	1080 x 2400	Modern Android (20:9)
android-tablet-10	1600 x 2560	10" Android tablet
mac	2880 x 1800	MacBook Pro

Run appshots devices for all 26 presets including Apple Watch, Apple TV, and Vision Pro.

Programmatic API

import { frameScreenshot, captureScreenshots, validateScreenshots, getDevice } from 'appshots';

// Frame a screenshot
const buffer = await frameScreenshot({
  input: './screenshot.png',
  device: 'iphone-6.9',
  title: 'Welcome',
  options: { background: 'linear-gradient(135deg, #667eea, #764ba2)' },
});

// Get device specs
const spec = getDevice('iphone-6.9');
// { name: 'iPhone 6.9"', width: 1320, height: 2868, dpr: 3, ... }

// Validate a directory
const results = await validateScreenshots('./screenshots');

License

MIT