Promise.inc/Dev Reel

Quick Start

Your first Dev Reel

Let's create an animated preview in 3 simple steps. This guide shows the complete workflow from scratch.

Step 1: Add a dev-reel block

Open your README.md and add a code block with the language 'dev-reel'. The block uses frontmatter syntax (YAML) for configuration:

markdown
```dev-reel
title: my-project
theme: promise-inc
animation:
  - typing
  - fade-lines
frame: terminal


$ npm install my-project
✔ Installed successfully in 0.8s


$ npm run dev
> Starting development server...
✔ Server running at http://localhost:3000
```

Step 2: Run the build

In your terminal, at the root of your project (where the README.md is), run:

bash
npx @promise-inc/dev-reel build

You'll see output similar to:

bash
✔ Found 1 dev-reel block in README.md
✔ Generated assets/my-project.svg (4.2 KB)
✔ Build completed in 0.3s

Step 3: Use the generated SVG

The SVG file was created at 'assets/my-project.svg'. Reference it in your README:

markdown
## Installation


![Installation demo](assets/my-project.svg)


Install via npm:
```bash
npm install my-project
```
The SVG is standalone and works anywhere: GitHub, npm, GitLab, Bitbucket, or your website.

Understanding the syntax

Let's dissect the block we created:

yaml
title: my-project          # File name (generates my-project.svg)
theme: promise-inc        # Color theme
animation:                # Array of animations
  - typing               # Typing effect
  - fade-lines           # Lines appear gradually
frame: terminal           # Frame type (macOS window)

After the frontmatter comes the terminal content:

bash
$ npm install my-project      # Line with $ = command
✔ Installed successfully...   # Line with ✔ = success (green)


$ npm run dev                 # Another command
> Starting dev server...      # Line with > = output
✔ Server running...           # Success

Line types

Dev Reel automatically detects the type of each line based on prefixes:

  • Commands: lines starting with $ or >
  • Success: lines with ✔ or ✓ (green)
  • Error: lines with ✖ or ✗ (red)
  • Warning: lines with ⚠ (yellow)
  • Info: lines with ℹ (blue)
  • Normal output: any other line
  • Empty lines: spacing

Watch mode for development

During development, use watch mode for automatic rebuild when editing the README:

bash
npx @promise-inc/dev-reel build --watch

Now edit your README.md and the SVGs will be recreated automatically.

Complete example

Here's a more elaborate example showing different line types:

markdown
```dev-reel
title: complete-example
theme: dracula
animation:
  - typing
  - blink-cursor
  - fade-lines
frame: terminal
width: 800


$ npm create my-app
✔ Created project structure


$ cd my-app
$ npm install
[========>   ] Installing dependencies... 75%


⚠ Warning: peer dependency missing
ℹ Installing @types/node as dev dependency
✔ All dependencies installed


$ npm run build
> Building for production...
✔ Build completed in 2.3s
✔ Output: 245 KB (gzipped: 82 KB)


✖ Error: Type check failed
  Expected 'string', got 'number' at line 42
```
Use progress bars with the syntax [====> ] to show ongoing processes.

Next steps

  • Block Syntax: learn all configuration options
  • Themes: explore the 4 available themes
  • Animations: see all 11 animations
  • Frames: discover the 5 frame types
InstallationBlock Syntax