- mit
- tvos + ios
- 2 images → 44 files
tvos-assets
Generate complete Images.xcassets bundles with parallax tvOS icons, iOS 18+ appearance variants, Top Shelf, and splash assets. Expo-first: the config plugin regenerates all of it on every prebuild.
What Goes In
you bring
- ├─icon.svg
- │or
- │ ├─layer-middle.svg
- │ └─layer-front.svg
- ├─background.png
- └─#F39C12
3 inputs. Give both layers and you get real parallax on Apple TV, with the flat icon assembled from them. Pass --icon and your file is used as-is instead.
tvos-assets writes
- ├─AppIcon.brandassets/30
- ├─AppIcon.appiconset/4
- ├─SplashScreenLogo.imageset/6
- ├─SplashScreenBackground.colorset/1
- └─icon.png · preview.html3
44 files: 21 Contents.json, 21 PNGs, and the contact sheet.
Three Ways To Run
Every Run Ships a Contact Sheet
Below is a real run: every file npx tvos-assets@1.5.0 wrote from those three inputs, tvOS and iOS, at true pixel dimensions. The same run also writes preview.html, one self-contained file with all of it embedded plus colorset swatches and an interactive parallax view of both imagestacks.
tvOS
App Icon - Home Screen6 files
front@1x.png
400 × 240
front@2x.png
800 × 480
middle@1x.png
400 × 240
middle@2x.png
800 × 480
back@1x.png
400 × 240
back@2x.png
800 × 480
App Icon - App Store3 files
front@1x.png
1280 × 768
middle@1x.png
1280 × 768
back.png
1280 × 768
Top Shelf4 files
Standard and wide, composited from the same two inputs at 1x and 2x.
top@1x.png
1920 × 720
top@2x.png
3840 × 1440
wide@1x.png
2320 × 720
wide@2x.png
4640 × 1440
iOS
App Icon - Light / Dark / Tinted (iOS 18+)3 files
One appiconset, three appearances. Dark sits on transparency so iOS supplies the gradient; tinted ships as grayscale for the user's accent color. Both are derived from your icon, or overridden with --icon-dark and --icon-tinted.
icon-1024.png
1024 × 1024
icon-1024-dark.png
1024 × 1024
icon-1024-tinted.png
1024 × 1024
Shared
Splash Screen Logo5 files
200-icon@1x.png
200 × 200
200-icon@2x.png
400 × 400
200-icon@3x.png
600 × 600
200-icon-tv@1x.png
200 × 200
200-icon-tv@2x.png
400 × 400
Standalone1 file
icon.png
1024 × 1024
One Config, Three Surfaces
Expo plugin
Add it to app.json. Every expo prebuild regenerates the full catalog, nothing gets committed under ios/.
CLI
One command, one zip. Made for scripts and CI, with --dry-run and --quiet included.
Config file
tvos-assets.config.json, read by both. Auto-discovered in the project root, schema included.
When the same setting arrives from two places, the more direct one wins: the config file overrides the defaults, --set overrides the config file, and --icon, --background, and --color always win.
CLI Reference
Inputs
| Flag | Description | Default |
|---|---|---|
| --icon <path> | Icon PNG or SVG (transparent background). Optional when --layer-front and --layer-middle are both given: the icon is assembled from them instead. | required |
| --background <path> | Background PNG or SVG | required |
| --color <hex> | Splash background color, light mode | required |
| --dark-color <hex> | Splash background color, dark mode | auto-darkened |
| --icon-dark <path> | iOS dark-appearance icon override | derived from --icon |
| --icon-tinted <path> | iOS tinted-appearance icon override | grayscale of --icon |
| --icon-border-radius <px> | Icon corner radius (0 = square) | 0 |
| --layer-front <path> | Custom front parallax layer art | — |
| --layer-middle <path> | Custom middle parallax layer art | — |
| --layer-back <path> | Custom back parallax layer art | — |
--icon <path>
Icon PNG or SVG (transparent background). Optional when --layer-front and --layer-middle are both given: the icon is assembled from them instead.
Required
--background <path>
Background PNG or SVG
Required
--color <hex>
Splash background color, light mode
Required
--dark-color <hex>
Splash background color, dark mode
Default: auto-darkened
--icon-dark <path>
iOS dark-appearance icon override
Default: derived from --icon
--icon-tinted <path>
iOS tinted-appearance icon override
Default: grayscale of --icon
--icon-border-radius <px>
Icon corner radius (0 = square)
Default: 0
--layer-front <path>
Custom front parallax layer art
--layer-middle <path>
Custom middle parallax layer art
--layer-back <path>
Custom back parallax layer art
Output
| Flag | Description | Default |
|---|---|---|
| --config <path> | Config JSON file | ./tvos-assets.config.json if present |
| --output <path> | Directory for the zip file | ~/Desktop |
| --out-dir <path> | Write Images.xcassets directly, no zip | — |
| --mode <zip|dir> | Output mode; --out-dir implies dir | zip |
| --platforms <list> | Icon families: tvos, ios, or both | both |
| --preview / --no-preview | Write preview.html contact sheet | on for zip, off for --out-dir |
--config <path>
Config JSON file
Default: ./tvos-assets.config.json if present
--output <path>
Directory for the zip file
Default: ~/Desktop
--out-dir <path>
Write Images.xcassets directly, no zip
--mode <zip|dir>
Output mode; --out-dir implies dir
Default: zip
--platforms <list>
Icon families: tvos, ios, or both
Default: both
--preview / --no-preview
Write preview.html contact sheet
Default: on for zip, off for --out-dir
Naming & selection
| Flag | Description | Default |
|---|---|---|
| --brand-name <name> | Name of the .brandassets bundle | AppIcon |
| --ios-icon-name <name> | Name of the iOS .appiconset | AppIcon |
| --splash-logo-name <name> | Splash logo imageset name | SplashScreenLogo |
| --splash-background-name <name> | Splash colorset name | SplashScreenBackground |
| --splash-logo-size <px> | Base splash logo size | 200 |
| --no-ios-icon | Skip the iOS appiconset | — |
| --no-top-shelf | Skip both Top Shelf imagesets | — |
| --no-splash | Skip splash logo and colorset | — |
--brand-name <name>
Name of the .brandassets bundle
Default: AppIcon
--ios-icon-name <name>
Name of the iOS .appiconset
Default: AppIcon
--splash-logo-name <name>
Splash logo imageset name
Default: SplashScreenLogo
--splash-background-name <name>
Splash colorset name
Default: SplashScreenBackground
--splash-logo-size <px>
Base splash logo size
Default: 200
--no-ios-icon
Skip the iOS appiconset
--no-top-shelf
Skip both Top Shelf imagesets
--no-splash
Skip splash logo and colorset
Advanced
| Flag | Description | Default |
|---|---|---|
| --set <path=value> | Override any config key by dotted path; repeatable | — |
| --dry-run | Report what would be written, then exit | — |
| --print-config | Print the fully merged config as JSON | — |
| --init [path] | Write a starter tvos-assets.config.json | — |
| --quiet | Only errors and the final output path | — |
--set <path=value>
Override any config key by dotted path; repeatable
--dry-run
Report what would be written, then exit
--print-config
Print the fully merged config as JSON
--init [path]
Write a starter tvos-assets.config.json
--quiet
Only errors and the final output path
Frequently Asked Questions
Do I need Xcode or design tools to generate the assets?
No. Two images and Node.js 18+ are enough. Xcode is only where the generated Images.xcassets catalog ends up.
Does it work with Expo and React Native TVOS?
Yes, that is the primary integration: the tvos-assets/plugin entry in app.json regenerates the full catalog on every expo prebuild, for both the tvOS and iOS targets. Nothing gets committed under ios/.
Can I use SVG inputs?
Yes, for the icon, the background, the iOS appearance overrides, and the parallax layers. SVGs are rasterized at the density each output needs, so one small vector stays crisp up to the 4640px Top Shelf image.
How are the iOS 18 dark and tinted icons made?
Derived automatically: dark is your icon on transparency, since iOS supplies the dark gradient behind it; tinted is a grayscale render that iOS colors with the user's accent. Both can be replaced with explicit art via --icon-dark and --icon-tinted.
How do the parallax layers work on Apple TV?
tvOS app icons are 3-layer imagestacks (Front, Middle, Back) that the home screen tilts in 3D. By default the tool renders your icon on the front and middle layers; pass separate art per layer with --layer-front and --layer-middle for true depth.
Does the generated catalog pass App Store validation?
Yes. Asset names, Contents.json structure, and dimensions follow Apple's spec, and the same layout ships in App Store-approved apps.