@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.