JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 57
  • Score
    100M100P100Q67776F
  • License MIT

A CLI tool for AI code agents and developers for generating images and videos.

Package Exports

  • loopwind
  • loopwind/sdk

Readme

loopwind

The Shadcn for design and marketing. A template-based CLI tool for generating images and videos using React + Tailwind CSS + Satori.

Features

  • 🎨 shadcn/ui Design System: Beautiful, semantic colors out of the box (text-primary, bg-card, etc.)
  • ✨ Template-based: Install design templates like you install UI components
  • 🖼️ Serverless Image Rendering: Pure JavaScript rendering with Satori - works on Vercel, Netlify, Cloudflare Workers
  • 🎬 Serverless Video Rendering: WASM-based MP4 encoding - 12x faster than traditional approaches
  • 🎨 Tailwind CSS Support: Style templates with Tailwind utility classes + opacity modifiers (bg-primary/50)
  • 📱 Built-in Helpers: QR codes, image embedding, video backgrounds, template composition
  • ✅ Smart Validation: Automatic prop and template validation with helpful error messages
  • 🚀 Framework-agnostic: Works with Node, Bun, Deno, Laravel, Python, and more
  • 🤖 Agent-friendly: Machine-readable metadata for LLMs
  • 📦 Easy installation: npx loopwind add template-name
  • 🌐 Pure JavaScript/WASM: No native dependencies, works everywhere

Quick Start

Installation

npm install -g loopwind

Or use with npx:

npx loopwind --help

Install a Template

Templates can be installed from multiple sources:

1. Official Registry (Coming Soon)

loopwind add banner-hero
loopwind add og-image --registry https://custom-registry.com/r

2. GitHub Repositories

# From a GitHub repo (looks for template.json in repo root)
loopwind add github:username/repo

# From a specific path in the repo
loopwind add github:username/repo/templates/banner-hero

# From an organization
loopwind add github:myorg/design-templates/social-media/og-image

How it works:

  • Converts to raw GitHub URLs
  • Fetches template.json from the specified path
  • Downloads all referenced files
  • Uses main branch by default

3. Direct URLs

# Install from any publicly accessible URL
loopwind add https://example.com/templates/my-template.json
loopwind add https://cdn.example.com/templates/awesome-banner.json

Requirements:

  • URL must return JSON in the registry template format
  • Must be publicly accessible (no authentication)

4. Local Filesystem

# Relative path
loopwind add ./my-templates/banner-hero
loopwind add ../shared-templates/product-card

# Absolute path
loopwind add /Users/you/templates/social-card

Use cases:

  • Development and testing
  • Private templates
  • Shared team templates (monorepo)
  • Before publishing to registry

Templates are installed to: _loopwind/templates/<template>/ (customizable in _loopwind/loopwind.json)

Benefits:

  • Templates are local to your project (like npm packages)
  • Different projects can use different template versions
  • Version controlled with your project
  • Easy to share within your team
  • Works offline once installed

See REGISTRY_SETUP.md to create your own registry.

Render an Image

loopwind render banner-hero \
  --props '{"title":"Hello World","subtitle":"Welcome to loopwind"}'

By default, images are saved to _loopwind/outputs/ in your current project.

You can specify a custom output path:

loopwind render banner-hero \
  --props '{"title":"Hello World","subtitle":"Welcome to loopwind"}' \
  --out custom/path/banner.png

Or use a props file:

# props.json
{
  "title": "Hello World",
  "subtitle": "Welcome to loopwind"
}

loopwind render banner-hero --props props.json --out banner.png

Output formats:

# PNG (default) - best for photos and complex gradients
loopwind render banner-hero --props props.json --format png -o banner.png

# SVG - scalable vector, smaller file size, perfect for template composition
loopwind render banner-hero --props props.json --format svg -o banner.svg

# WebP - modern format, smaller than PNG with similar quality
loopwind render banner-hero --props props.json --format webp -o banner.webp

# JPEG - smallest file size, good for photos
loopwind render banner-hero --props props.json --format jpg -o banner.jpg

SVG benefits with template composition:

  • Smaller file size (typically 3-4x smaller than PNG)
  • Infinitely scalable without quality loss
  • Embedded templates remain as native SVG elements
  • Can be edited in design tools (Figma, Illustrator)

List Installed Templates

loopwind list

Validate Templates

loopwind validate
loopwind validate banner-hero

SDK for Programmatic Use

Use loopwind programmatically in your Next.js API routes, serverless functions, or Node.js applications!

Installation

npm install loopwind

Quick Example

import { defineTemplate, renderImage } from 'loopwind/sdk';

// Define template programmatically
const ogTemplate = defineTemplate({
  name: 'og-image',
  size: { width: 1200, height: 630 },
  render: ({ tw, title, description }) => (
    <div style={tw('flex flex-col w-full h-full bg-gradient-to-br from-blue-600 to-purple-700 p-12')}>
      <h1 style={tw('text-6xl font-bold text-white')}>{title}</h1>
      <p style={tw('text-2xl text-white/80')}>{description}</p>
    </div>
  ),
});

// Render to buffer
const png = await renderImage(ogTemplate, {
  title: 'Hello World',
  description: 'Generated with loopwind SDK',
});

// Use in Next.js API route
export default async function handler(req, res) {
  const png = await renderImage(ogTemplate, req.query);
  res.setHeader('Content-Type', 'image/png');
  res.send(png);
}

Video Rendering

import { defineTemplate, renderVideo } from 'loopwind/sdk';

const introTemplate = defineTemplate({
  name: 'intro-video',
  type: 'video',
  size: { width: 1920, height: 1080 },
  video: { fps: 30, duration: 3 },
  render: ({ tw, progress, title }) => {
    const opacity = progress; // 0 to 1 animation

    return (
      <div style={tw('flex items-center justify-center w-full h-full bg-black')}>
        <h1 style={{ ...tw('text-8xl font-bold text-white'), opacity }}>
          {title}
        </h1>
      </div>
    );
  },
});

const mp4 = await renderVideo(introTemplate, { title: 'Welcome!' });

Key Features

  • ✅ No file system dependencies - templates defined in code
  • ✅ Returns buffers - integrate with any framework or storage
  • ✅ Serverless-first - works on Vercel, Netlify, Cloudflare Workers
  • ✅ Full TypeScript support - type-safe props and templates
  • ✅ Same Tailwind + shadcn/ui styling - consistent with CLI

Use Cases

  • 🖼️ Dynamic OG images for blogs and marketing sites
  • 🎬 Programmatic videos for social media automation
  • 📧 Email images generated on-the-fly
  • 🎨 User-generated content like certificates, cards, badges
  • 🔄 Batch processing of images or videos

Example: Next.js API Route

See the full example in examples/nextjs-api/

// pages/api/og-image.ts
import { defineTemplate, renderImage } from 'loopwind/sdk';

const template = defineTemplate({
  name: 'og-image',
  size: { width: 1200, height: 630 },
  render: ({ tw, title }) => (
    <div style={tw('flex items-center justify-center w-full h-full bg-white')}>
      <h1 style={tw('text-6xl font-bold')}>{title}</h1>
    </div>
  ),
});

export default async function handler(req, res) {
  const png = await renderImage(template, req.query);
  res.setHeader('Content-Type', 'image/png');
  res.setHeader('Cache-Control', 's-maxage=86400');
  res.send(png);
}

Usage:

https://yoursite.com/api/og-image?title=Hello+World

shadcn/ui Design System

loopwind uses shadcn/ui's design system by default! All templates have access to semantic color tokens:

// Use shadcn colors in templates
<div style={tw('bg-card border rounded-xl p-16')}>
  <h1 style={tw('text-foreground font-bold')}>Title</h1>
  <p style={tw('text-muted-foreground')}>Subtitle</p>
</div>

Supported shadcn classes:

  • text-primary, bg-secondary, text-muted-foreground, bg-card, border, bg-destructive
  • Opacity modifiers: bg-primary/50, text-muted-foreground/75, border/30
  • Dark mode ready: Override colors in loopwind.json

See SHADCN_INTEGRATION.md for complete documentation.

Configuration (loopwind.json)

Templates automatically use your project's design tokens defined in _loopwind/loopwind.json. This allows generated images to match your brand colors and design system.

Initialize Config

loopwind init

This creates a _loopwind/loopwind.json file in your project:

{
  "colors": {
    "primary": "#667eea",
    "secondary": "#764ba2",
    "background": "#ffffff",
    "foreground": "#000000",
    "muted": "#f3f4f6",
    "accent": "#3b82f6",
    "destructive": "#ef4444",
    "border": "#e5e7eb"
  },
  "fonts": {
    "sans": ["Inter", "system-ui", "sans-serif"],
    "mono": ["JetBrains Mono", "monospace"]
  },
  "tokens": {
    "borderRadius": {
      "sm": "0.25rem",
      "md": "0.5rem",
      "lg": "1rem",
      "xl": "1.5rem"
    }
  },
  "defaults": {
    "width": 1200,
    "height": 630
  }
}

Using Config in Templates

Templates receive the config via props:

export default function MyTemplate({ title, config }) {
  const primaryColor = config?.colors?.primary || '#000';

  return (
    <div style={{ background: primaryColor }}>
      {title}
    </div>
  );
}

This ensures your generated images use the same colors as your Tailwind/Shadcn setup!

Using Tailwind Classes

Templates can use Tailwind utility classes for styling! The tw() function is automatically provided:

export default function MyTemplate({ title, tw }) {
  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-primary text-white')}>
      <h1 style={tw('text-6xl font-bold')}>
        {title}
      </h1>
    </div>
  );
}

Combine with custom styles:

<div
  style={{
    ...tw('flex flex-col p-20 text-white'),
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
  }}
>
  <h1 style={tw('text-8xl font-bold')}>{title}</h1>
</div>

Automatic Tailwind Config Support

loopwind automatically detects and uses your tailwind.config.js!

If you have a Tailwind project:

// tailwind.config.js
export default {
  theme: {
    extend: {
      colors: {
        primary: '#667eea',
        brand: {
          500: '#0ea5e9',
          900: '#0c4a6e',
        },
      },
      spacing: {
        '72': '18rem',
      },
    },
  },
};

Your templates can use these values:

<div style={tw('bg-primary text-white p-72')}>
  <div style={tw('bg-brand-500')}>Custom brand color!</div>
</div>

Config priority:

  1. tailwind.config.js (if exists)
  2. loopwind.json (fallback)
  3. Default Tailwind values

Supported classes:

  • Layout: flex, flex-col, items-center, justify-between, etc.
  • Spacing: p-4, px-8, m-6, gap-4, etc.
  • Typography: text-6xl, font-bold, text-center, etc.
  • Colors: bg-primary, text-brand-500, etc. (from your config!)
  • Effects: opacity-90, rounded-xl, etc.
  • shadcn/ui colors: bg-card, text-foreground, text-muted-foreground
  • Opacity modifiers: bg-primary/50, text-muted-foreground/75

Note: Tailwind v4 uses CSS variables instead of JS config. We're working on CSS parsing support. For now, use loopwind.json or tailwind.config.js (v3 format).

Fonts

Templates can use default fonts (from CDN) or bundle custom fonts for brand-specific typography.

Default Fonts

By default, templates use Noto Sans fetched from jsDelivr CDN. No setup required!

Custom Fonts

Templates can bundle their own fonts (WOFF, WOFF2, TTF, OTF):

my-template/
├── template.tsx
└── fonts/
    ├── CustomFont-Regular.woff
    └── CustomFont-Bold.woff

template.tsx:

export const meta = {
  name: "my-template",
  // ...
  fonts: [
    {
      name: "Custom Font",
      path: "fonts/CustomFont-Bold.woff",
      weight: 700,
      style: "normal"
    }
  ]
};

export default function Template({ title, tw }) {
  return (
    <h1 style={{ fontFamily: 'Custom Font', fontWeight: 700 }}>
      {title}
    </h1>
  );
}

Use cases:

  • Brand-specific fonts (company guidelines)
  • Offline rendering (no CDN dependency)
  • Special display typography

Template Helpers

Templates have access to built-in helper functions:

  • tw(classes) - Convert Tailwind classes to inline styles
  • qr(text, options?) - Generate QR codes from text/URLs
  • image(propKey) - Embed images as data URIs
  • video(propKey) - Embed video frames (for video templates)
  • template(name, props) - Embed other templates
  • config - Access loopwind.json configuration

QR Code Helper

Generate QR codes from any text or URL using the qr() helper:

export default function Template({ title, url, qr, tw }) {
  return (
    <div style={tw('flex flex-col items-center p-16')}>
      <h1 style={tw('text-5xl font-bold mb-8')}>{title}</h1>

      {/* QR code auto-generated from url prop */}
      <img src={qr(url)} width={200} height={200} alt="QR Code" />

      <p style={tw('text-xl mt-4')}>{url}</p>
    </div>
  );
}

Usage:

loopwind render qr-card '{
  "title": "Visit Our Website",
  "url": "https://loopwind.dev"
}'

Customization:

// Custom size and error correction
<img src={qr(url, {
  width: 300,
  margin: 2,
  errorCorrectionLevel: 'H', // L, M, Q, H (higher = more error correction)
  color: {
    dark: '#000000',
    light: '#FFFFFF'
  }
})} />

How it works:

  • All string props are automatically pre-generated as QR codes
  • Call qr() with any prop value (url, text, etc.)
  • Returns a data URI that can be used directly in <img src={...} />
  • Cached per render for performance

Use cases:

  • Event tickets with QR codes
  • Business cards with contact info
  • Marketing materials with campaign URLs
  • Product labels with tracking codes

Image Helper

Embed images (jpg, png, gif, webp, svg) as data URIs using the image() helper:

export default function Banner({ background, tw, image }) {
  return (
    <div style={tw('relative w-full h-full')}>
      <img src={image('background')} style={tw('absolute inset-0 w-full h-full object-cover')} />
      <h1 style={tw('relative text-6xl font-bold text-white')}>Hello World</h1>
    </div>
  );
}

Props format:

{
  "background": "./path/to/image.jpg"
}

Usage:

loopwind render banner '{
  "background": "./my-background.jpg"
}'

How it works:

  • The renderer auto-detects props ending in image extensions (.jpg, .png, .gif, .webp, .svg)
  • Images are pre-loaded and converted to data URIs
  • Call image('propKey') to get the data URI for that prop
  • Works with any image format

Use cases:

  • Background images in banners
  • Logos and brand elements
  • Product photos in cards
  • Avatar images

Video Helper

For video templates, embed video frames synchronized to the current animation frame using the video() helper:

export default function VideoOverlay({ background, title, tw, video, frame, progress }) {
  const opacity = progress < 0.2 ? progress / 0.2 : 1;

  return (
    <div style={tw('relative w-full h-full')}>
      {/* Background video - auto-syncs to current frame */}
      <img
        src={video('background')}
        style={tw('absolute inset-0 w-full h-full object-cover')}
      />

      {/* Animated overlay */}
      <h1
        style={{
          ...tw('relative text-8xl font-bold text-white'),
          opacity
        }}
      >
        {title}
      </h1>
    </div>
  );
}

Props format:

{
  "title": "My Video",
  "background": "./my-video.mp4"
}

Usage:

loopwind render video-overlay props.json --out output.mp4

How it works:

  1. First render detects video props (auto-detects .mp4, .mov, etc.)
  2. Extracts all frames at template's FPS
  3. Returns frame matching current template frame number
  4. Frames cached in memory for fast access

Use cases:

  • Video backgrounds with text overlays
  • Adding titles/captions to existing videos
  • Combining multiple video sources
  • Dynamic watermarking

Template Composition Helper

Embed one template inside another using the template() helper. This is perfect for creating composite designs where smaller templates are reused as building blocks.

Just call template() - no declaration needed:

export default function Template({ title, bannerTitle, bannerSubtitle, template, tw }) {
  return (
    <div style={tw('w-full h-full flex flex-col bg-slate-900 p-12')}>
      <div style={tw('bg-white rounded-3xl p-10 flex flex-col')}>
        <h1 style={tw('text-5xl font-bold mb-8')}>{title}</h1>

        {/* Embed any template - auto-loaded on first render */}
        <div style={tw('rounded-xl overflow-hidden flex')}>
          {template('image', { title: bannerTitle, subtitle: bannerSubtitle })}
        </div>
      </div>
    </div>
  );
}

Usage:

loopwind render composite-card '{
  "title": "Product Launch",
  "bannerTitle": "New Release",
  "bannerSubtitle": "Coming Soon"
}'

How it works:

  • No declaration needed - just call template('any-template-name')
  • First render pass detects which templates are needed
  • All templates load in parallel automatically
  • Second render pass completes with loaded templates
  • Each template uses its own meta for sizing
  • Returns JSX directly (not a data URI)
  • Satori renders everything as a single SVG tree

Pass props directly:

{template('image', { title: 'Custom Title', subtitle: 'Custom Subtitle' })}
{template('qr-card', { url: 'https://example.com', title: 'Scan Me' })}

Use cases:

  • Composite social media graphics with reusable headers/footers
  • Multi-panel infographics
  • Email templates with consistent branding elements
  • Product cards with embedded badges or labels
  • Presentations with reusable slide components

Template Structure

Templates are TSX files with metadata. Each template can be either an image or a video template (not both).

Image Template

export const meta = {
  name: "banner-hero",
  description: "Hero banner with shadcn design",
  type: "image", // Optional, defaults to "image"
  size: { width: 1600, height: 900 },
  props: {
    title: "string",
    subtitle: "string?"
  }
};

export default function Template({ title, subtitle, tw, qr, template }) {
  return (
    <div style={tw('w-full h-full flex flex-col justify-center p-20 bg-background')}>
      <div style={tw('bg-card border rounded-xl p-16 flex flex-col')}>
        <h1 style={tw('text-8xl font-bold text-foreground')}>{title}</h1>
        {subtitle && (
          <p style={tw('text-4xl text-muted-foreground/75')}>{subtitle}</p>
        )}
      </div>
    </div>
  );
}

Video Template

export const meta = {
  name: "animated-banner",
  description: "Animated hero banner with shadcn design",
  type: "video",
  size: { width: 1600, height: 900 },
  props: {
    title: "string",
    subtitle: "string?"
  },
  video: {
    fps: 30,
    duration: 3
  }
};

export default function Template({ title, subtitle, frame, progress, tw, qr, template }) {
  const opacity = Math.min(1, progress * 2);
  const translateY = 20 - (progress * 20);

  return (
    <div style={tw('w-full h-full flex flex-col justify-center items-center bg-background p-20')}>
      <div style={tw('bg-card border rounded-xl p-16 flex flex-col')}>
        <h1
          style={{
            ...tw('text-9xl font-bold text-foreground'),
            opacity,
            transform: `translateY(${translateY}px)`
          }}
        >
          {title}
        </h1>
        {subtitle && (
          <p style={tw('text-5xl text-muted-foreground/75 mt-6')}>
            {subtitle}
          </p>
        )}
      </div>
    </div>
  );
}

Commands

loopwind init

Initialize a _loopwind/loopwind.json config file with default design tokens.

loopwind add <template>

Install a template from the registry.

Options:

  • -r, --registry <url> - Custom registry URL

loopwind list

List all installed templates with metadata.

loopwind render <template>

Render a template to an image.

Options:

  • -p, --props <file> - Props file (JSON)
  • -o, --out <file> - Output file path
  • --format <format> - Output format: png, svg, webp (default: png)
  • --video - Render as video (coming soon)

loopwind validate [template]

Validate template metadata. If no template is specified, validates all installed templates.

Validation & Error Messages

loopwind automatically validates templates and props before rendering, providing helpful error messages.

Automatic Validation

# Missing required props
$ loopwind render banner-hero --props '{}'
✖ Template validation failed
  ✗ props: Missing required prop: "title"
    → Add "title" to your props: --props '{"title":"value"}'

# Wrong prop type
$ loopwind render banner-hero --props '{"title":123}'
✖ Template validation failed
  ✗ props: Prop "title" should be a string, got number
    → Change "title" to a string: "title": "value"

Enhanced Satori Error Messages

When rendering fails, loopwind provides clear suggestions:

$ loopwind render my-template --props props.json
✖ Failed to render template

Error: Satori requires explicit display: flex for containers with multiple children

Suggestions:
  • Add "flex" or "flex-col" to your Tailwind classes: tw("flex items-center")
  • Or add display: flex directly: style={{ display: "flex", ...tw("...") }}
  • Every <div> with 2+ children MUST have display: flex or display: none

See VALIDATION.md for complete validation documentation and troubleshooting.

Creating Custom Templates

Templates are stored in your project's _loopwind/templates/ directory. You can create custom templates:

  1. Create a folder:
mkdir -p _loopwind/templates/my-template
  1. Create template.tsx with exported meta:
export const meta = {
  name: "my-template",
  description: "My custom template",
  type: "image",
  size: { width: 1200, height: 630 },
  props: { title: "string" }
};

export default function MyTemplate({ title, tw }) {
  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-black text-white text-5xl')}>
      {title}
    </div>
  );
}
  1. Validate and render:
loopwind validate my-template
loopwind render my-template --props '{"title":"Hello"}' --out test.png

Use Cases

  • 🎯 OG Images: Generate Open Graph images for websites
  • 📱 Social Media: Create social media graphics
  • 📧 Email Headers: Generate email banners
  • 🎨 Marketing: Automate marketing asset creation
  • 🤖 AI Agents: Let LLMs generate images programmatically

Video Support

Video templates use type: "video" and support frame and progress props for animations.

⚡ No Dependencies Required

loopwind uses pure JavaScript/WASM for video encoding - works everywhere!

✅ Works on Vercel Edge Functions ✅ Works on Netlify Functions ✅ Works on Cloudflare Workers ✅ Works on AWS Lambda ✅ Works everywhere (Docker, CI/CD, local)

12x faster than traditional approaches - renders a 3-second video in ~2 seconds!

Creating Video Templates

Video templates are similar to image templates but include frame and progress props for animations:

export const meta = {
  name: "my-video",
  type: "video",
  size: { width: 1200, height: 630 },
  props: { title: "string" },
  video: {
    fps: 30,
    duration: 3
  }
};

export default function Template({ title, frame, progress, tw, qr, template }) {
  return (
    <div
      style={{
        ...tw('w-full h-full flex items-center justify-center'),
        opacity: progress,
        transform: `translateY(${20 - progress * 20}px)`
      }}
    >
      <h1 style={tw('text-6xl font-bold')}>{title}</h1>
    </div>
  );
}

Rendering Videos

# Render to MP4 (default)
loopwind render my-video '{"title":"Animated Title"}' -o output.mp4

# Render to GIF (great for emails, GitHub, Slack)
loopwind render my-video '{"title":"Animated Title"}' --format gif -o output.gif

# With custom quality settings
loopwind render my-video props.json --crf 18   # Higher quality (lower CRF = better quality)

# Export frames only (for manual encoding)
loopwind render my-video props.json --frames-only -o frames/

Output formats:

  • MP4 - H.264 codec, smaller files, best quality (default)
  • GIF - Animated, works everywhere (emails, GitHub READMEs, Slack)

How it works:

  1. SVG Generation: All frames generated in parallel (~0.8s for 90 frames)
  2. WASM Encoding: Frames encoded to H.264 MP4 using pure JavaScript (~1.2s for 90 frames)
  3. Total: 3-second video renders in ~2 seconds on M1 Mac

Props available in video templates:

  • frame - Current frame number (0 to totalFrames-1)
  • progress - Animation progress from 0 to 1
  • All standard helpers: tw, qr, template, config

Performance:

  • 12x faster than traditional approaches
  • 90 frames (3s @ 30fps) renders in ~2 seconds
  • ~60 frames per second rendering speed
  • Perfect for serverless environments with execution time limits

Documentation Website

A full documentation website is available in the website/ folder, built with Astro.

Local development:

cd website
npm install
npm run dev

Open http://localhost:4321

Deployment:

The site is ready to deploy on Netlify, Vercel, or Cloudflare Pages. A netlify.toml is included for easy Netlify deployment.

See website/README.md for more details.

Registry

Templates are fetched from a registry (similar to shadcn/ui). The default registry is:

https://loopwind.dev/r

You can host your own registry and use it with:

loopwind add my-template --registry https://my-registry.com

License

MIT