/loopwind

name: loopwind
description: Generate images and videos from React + Tailwind CSS templates using the loopwind CLI.
metadata:
  version: "0.25.11"

loopwind

A CLI tool for generating images and videos from JSX templates using Tailwind CSS and Satori. Templates live in a `.loopwind/` directory alongside your codebase.

Quick Start

Loopwind is a CLI tool for generating images and videos with React and Tailwind CSS. It's designed to be used with AI Agents and Cursor.

Installation

curl -fsSL https://loopwind.dev/install.sh | bash

This installs loopwind to `~/.loopwind/` and adds the `loopwind` command to your PATH. Requires Node.js 18+.

Initialize in Your Project

Navigate to any project folder and run:

loopwind init

This creates `.loopwind/loopwind.json` — a configuration file with your project's theme colors.

Install AI Skill

Give your AI agent expertise in loopwind:

npx skills add https://loopwind.dev/skill.md

This installs a skill that teaches Claude Code (or other AI agents) how to create templates, use animation classes, and render images/videos.

Use with Claude Code

With the loopwind skill installed, Claude has deep knowledge of template structure, animation classes, and Tailwind CSS patterns for Satori. Just ask:

Create an OG image for my blog post about TypeScript tips

Create an animated intro video for my YouTube channel

Claude will create optimized templates and render the final output automatically.

Install a Template

1. Official Templates

loopwind add image-template
loopwind add video-template

Templates are installed to: `.loopwind/<template>/`

**Benefits:**

• Templates are local to your project
• Version controlled with your project
• Easy to share within your team

Render a Template

loopwind render template-name '{"title":"Hello World","subtitle":"Built with loopwind"}'

or use a local props file:

loopwind render template-name props.json

Commands

`loopwind add <source>`

Install a template from various sources:

# Official templates
loopwind add image-template
loopwind add video-template

These will be downloaded to `.loopwind/<template>/`

`loopwind list`

List all installed templates:

loopwind list

`loopwind render <template> <props> [options]`

Render an image or video:

# Image with inline props
loopwind render banner-hero '{"title":"Hello World"}'

# Video with inline props
loopwind render video-intro '{"title":"Welcome"}'

# Using a props file
loopwind render banner-hero props.json

# Custom output
loopwind render banner-hero '{"title":"Hello"}' --out custom-name.png

# Different format
loopwind render banner-hero '{"title":"Hello"}' --format jpeg

Options:

• `--out, -o` - Output filename (default: `<template>.<ext>` in current directory)
• `--format` - Output format: `png`, `jpeg`, `svg` (images only)
• `--quality` - JPEG quality 1-100 (default: 92)

`loopwind validate <template>`

Validate a template:

loopwind validate banner-hero

Checks:

• Template file exists and is valid React
• `export const meta` exists and is valid
• Required props are defined
• Fonts exist (if specified)

`loopwind init`

Initialize loopwind in a project:

loopwind init

Creates `.loopwind/loopwind.json` configuration file with your project's design tokens.

Animation Classes (Video Only)

Use Tailwind-style animation classes - no manual calculations needed:

// Fade in: starts at 0ms, lasts 500ms
<h1 style={tw('enter-fade-in/0/500')}>Hello</h1>

// Loop: ping effect every 500ms
<div style={tw('loop-ping/500')} />

// Combined with easing
<h1 style={tw('ease-out enter-bounce-in-up/0/600')}>Title</h1>

See [Animation](/animation) for the complete reference.

Next Steps

• [Templates](/templates)
• [Embedding Images](/images)
• [Animation](/animation)
• [Helpers (QR, Template Composition)](/helpers)
• [Styling with Tailwind & shadcn/ui](/styling)
• [Custom Fonts](/fonts)
• [AI Agent Integration](/agents)

Templates

Templates are React components that define your images and videos. They use Tailwind CSS for styling and export metadata that loopwind uses for rendering.

Installing Templates

Official Templates

loopwind add image-template
loopwind add video-template

Templates are installed to `.loopwind/<template-name>/`.

Direct URLs

loopwind add https://example.com/templates/my-template.json

Local Filesystem

loopwind add ./my-templates/banner-hero
loopwind add /Users/you/templates/social-card

---

Image Templates

Basic Structure

// .loopwind/banner-hero/template.tsx
export const meta = {
  name: "banner-hero",
  type: "image",
  description: "Hero banner with gradient background",
  size: { width: 1600, height: 900 },
  props: { title: "string", subtitle: "string" }
};

export default function BannerHero({ title, subtitle, tw }) {
  return (
    <div style={tw('flex flex-col justify-center items-center w-full h-full bg-gradient-to-br from-purple-600 to-blue-500 p-12')}>
      <h1 style={tw('text-7xl font-bold text-white mb-4')}>
        {title}
      </h1>
      <p style={tw('text-2xl text-white/80')}>
        {subtitle}
      </p>
    </div>
  );
}

Rendering Images

# Render with inline props
loopwind render banner-hero '{"title":"Hello World","subtitle":"Welcome"}'

# Custom output name
loopwind render banner-hero '{"title":"Hello"}' --out custom-name.png

# Different format
loopwind render banner-hero '{"title":"Hello"}' --format jpeg --quality 95

# Use a props file
loopwind render banner-hero props.json

Output Formats

| Format | Best For | |--------|----------| | **PNG** (default) | Transparency, sharp text, logos | | **JPEG** | Photographs, gradients, smaller files | | **SVG** | Vector graphics, scalable designs |

---

Video Templates