@promise-inc/dev-reel

Turn your README into a cinematic dev showcase. Animated SVG previews for open-source projects — zero JS, zero canvas, GitHub-native.

Why?

README screenshots are static, GIFs are heavy, and videos don't render on GitHub:

• Screenshots go stale the moment you ship
• GIFs are huge files with bad quality
• Videos require external hosting
• None of them are version-control friendly

dev-reel generates animated SVG previews directly from your README — pure CSS, zero JavaScript, rendered natively by GitHub.

Frames

5 built-in frame styles to match any context.

Terminal (default)

macOS-style terminal with traffic light dots and title bar.

Card

Clean rounded card with subtle shadow. Great for changelogs and feature lists.

Browser

Address bar with navigation dots. Perfect for API docs and web content.

Mobile

iPhone-style mockup with dynamic island, status bar and home indicator.

None

No chrome, just content. Metrics dashboard with animated bar charts.

Bento Grid Layout

Two-panel layout with synchronized scroll animation — panels scroll in opposite directions.

Features Showcase

Before / After

How it works

1. Write a dev-reel block in your README

```dev-reel
title: my project
theme: promise-inc
animation:
  - typing
  - blink-cursor
frame: terminal

$ npm install my-project
✔ added 1 package in 0.8s
$ npx my-project
✔ Done!
```

2. Run one command

npx dev-reel

3. dev-reel does the magic

• Reads your README
• Finds dev-reel blocks
• Generates animated SVGs
• Saves to /assets
• Replaces blocks with image references

Animations

All animations are pure CSS — zero JavaScript, GitHub-compatible.

Animation	Description
typing	Lines appear one by one with delay
blink-cursor	Classic terminal cursor blink
fade-lines	Progressive opacity reveal
scanline	CRT-style horizontal scan line
wave	Subtle vertical oscillation per line
pulse-error	Error lines pulse in and out
glow-success	Success lines glow softly
noise-overlay	CRT noise texture overlay
progress-bar	Animated loading bar for [===] lines
grow-bars	Bar charts grow from left to right
slide-cards	Notification cards slide in from right

Themes

4 built-in themes inspired by modern dev tooling.

Theme	Style
promise-inc (default)	Dark with purple/green accents
dracula	Classic Dracula palette
nord	Cool blue Nordic tones
catppuccin-mocha	Warm pastel Catppuccin

Frontmatter Reference

Field	Type	Default	Description
title	string	"terminal"	Title shown in frame chrome
theme	string	"promise-inc"	Color theme
animation	string[]	[]	List of animations to apply
frame	string	"terminal"	Frame style: terminal, card, browser, mobile, none
layout	string	"single"	Layout: single or bento (two panels split by ---)
width	number | "auto"	"auto"	SVG width in pixels
cursor	boolean	true	Show blinking cursor
prefix	string | false	"$"	Command line prefix for line detection
show-title	boolean	true	Show/hide title bar
raw	boolean	false	Disable auto line-type detection
font-family	string	JetBrains Mono	Monospace font stack
font-size	number	13	Font size in pixels
watermark	boolean	true	Show @promise-inc/dev-reel watermark

CLI Usage

npx dev-reel               # build all dev-reel blocks
npx dev-reel build         # explicit build command
npx dev-reel build --watch # regenerate on README change

GitHub Actions

- name: Update Dev Reel
  run: npx dev-reel

Why SVG?

• Native GitHub rendering
• Ultra-lightweight
• Animations without JavaScript
• Version-control friendly
• Works on GitHub, GitLab, npm

Web Version

Don't want to use the CLI? Try the web version at promise.codes/code-to-reel — generate previews directly in your browser with:

• Static PNG export
• Animated SVG export
• WebM video download
• Full configuration UI (themes, frames, animations, fonts)

How to report bugs

To report a bug, please first read our guide on opening issues.

How to contribute code

To open a pull request, please first read our guide on opening pull requests, which outlines our process for RFCs and pull requests.

Also by Promise Inc.

Package	Description
@promise-inc/ai-guard	Detect AI-generated code patterns
@promise-inc/ps-guard	Lighthouse-based performance guard
@promise-inc/fs-guard	Validate project folder and file structure
@promise-inc/devlog	Logger with automatic context (file + line)
@promise-inc/ui-states	Auto-generated skeleton loading states

---

Developed by Promise Inc.

License

MIT © Promise Inc.