loopwind 0.9.1 → 0.9.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -71
- package/package.json +2 -3
- package/website/astro.config.mjs +1 -1
- package/website/package.json +1 -1
- package/website/public/robots.txt +1 -1
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
#
|
|
1
|
+
# loopwind
|
|
2
2
|
|
|
3
3
|
> The Shadcn for design and marketing. A template-based CLI tool for generating images and videos using React + Tailwind CSS + Satori.
|
|
4
4
|
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
- ✅ **Smart Validation**: Automatic prop and template validation with helpful error messages
|
|
14
14
|
- 🚀 **Framework-agnostic**: Works with Node, Bun, Deno, Laravel, Python, and more
|
|
15
15
|
- 🤖 **Agent-friendly**: Machine-readable metadata for LLMs
|
|
16
|
-
- 📦 **Easy installation**: `npx
|
|
16
|
+
- 📦 **Easy installation**: `npx loopwind add template-name`
|
|
17
17
|
- 🌐 **Pure JavaScript/WASM**: No native dependencies, works everywhere
|
|
18
18
|
|
|
19
19
|
## Quick Start
|
|
@@ -21,13 +21,13 @@
|
|
|
21
21
|
### Installation
|
|
22
22
|
|
|
23
23
|
```bash
|
|
24
|
-
npm install -g
|
|
24
|
+
npm install -g loopwind
|
|
25
25
|
```
|
|
26
26
|
|
|
27
27
|
Or use with npx:
|
|
28
28
|
|
|
29
29
|
```bash
|
|
30
|
-
npx
|
|
30
|
+
npx loopwind --help
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
### Install a Template
|
|
@@ -37,21 +37,21 @@ Templates can be installed from multiple sources:
|
|
|
37
37
|
#### 1. Official Registry (Coming Soon)
|
|
38
38
|
|
|
39
39
|
```bash
|
|
40
|
-
|
|
41
|
-
|
|
40
|
+
loopwind add banner-hero
|
|
41
|
+
loopwind add og-image --registry https://custom-registry.com/r
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
#### 2. GitHub Repositories
|
|
45
45
|
|
|
46
46
|
```bash
|
|
47
47
|
# From a GitHub repo (looks for template.json in repo root)
|
|
48
|
-
|
|
48
|
+
loopwind add github:username/repo
|
|
49
49
|
|
|
50
50
|
# From a specific path in the repo
|
|
51
|
-
|
|
51
|
+
loopwind add github:username/repo/templates/banner-hero
|
|
52
52
|
|
|
53
53
|
# From an organization
|
|
54
|
-
|
|
54
|
+
loopwind add github:myorg/design-templates/social-media/og-image
|
|
55
55
|
```
|
|
56
56
|
|
|
57
57
|
**How it works:**
|
|
@@ -64,8 +64,8 @@ dsgn add github:myorg/design-templates/social-media/og-image
|
|
|
64
64
|
|
|
65
65
|
```bash
|
|
66
66
|
# Install from any publicly accessible URL
|
|
67
|
-
|
|
68
|
-
|
|
67
|
+
loopwind add https://example.com/templates/my-template.json
|
|
68
|
+
loopwind add https://cdn.example.com/templates/awesome-banner.json
|
|
69
69
|
```
|
|
70
70
|
|
|
71
71
|
**Requirements:**
|
|
@@ -76,11 +76,11 @@ dsgn add https://cdn.example.com/templates/awesome-banner.json
|
|
|
76
76
|
|
|
77
77
|
```bash
|
|
78
78
|
# Relative path
|
|
79
|
-
|
|
80
|
-
|
|
79
|
+
loopwind add ./my-templates/banner-hero
|
|
80
|
+
loopwind add ../shared-templates/product-card
|
|
81
81
|
|
|
82
82
|
# Absolute path
|
|
83
|
-
|
|
83
|
+
loopwind add /Users/you/templates/social-card
|
|
84
84
|
```
|
|
85
85
|
|
|
86
86
|
**Use cases:**
|
|
@@ -89,7 +89,7 @@ dsgn add /Users/you/templates/social-card
|
|
|
89
89
|
- Shared team templates (monorepo)
|
|
90
90
|
- Before publishing to registry
|
|
91
91
|
|
|
92
|
-
Templates are installed to: `
|
|
92
|
+
Templates are installed to: `_loopwind/templates/<template>/` (customizable in `loopwind.json`)
|
|
93
93
|
|
|
94
94
|
**Benefits:**
|
|
95
95
|
- Templates are local to your project (like npm packages)
|
|
@@ -103,17 +103,17 @@ See `REGISTRY_SETUP.md` to create your own registry.
|
|
|
103
103
|
### Render an Image
|
|
104
104
|
|
|
105
105
|
```bash
|
|
106
|
-
|
|
107
|
-
--props '{"title":"Hello World","subtitle":"Welcome to
|
|
106
|
+
loopwind render banner-hero \
|
|
107
|
+
--props '{"title":"Hello World","subtitle":"Welcome to loopwind"}'
|
|
108
108
|
```
|
|
109
109
|
|
|
110
|
-
By default, images are saved to `
|
|
110
|
+
By default, images are saved to `_loopwind/outputs/` in your current project.
|
|
111
111
|
|
|
112
112
|
You can specify a custom output path:
|
|
113
113
|
|
|
114
114
|
```bash
|
|
115
|
-
|
|
116
|
-
--props '{"title":"Hello World","subtitle":"Welcome to
|
|
115
|
+
loopwind render banner-hero \
|
|
116
|
+
--props '{"title":"Hello World","subtitle":"Welcome to loopwind"}' \
|
|
117
117
|
--out custom/path/banner.png
|
|
118
118
|
```
|
|
119
119
|
|
|
@@ -123,26 +123,26 @@ Or use a props file:
|
|
|
123
123
|
# props.json
|
|
124
124
|
{
|
|
125
125
|
"title": "Hello World",
|
|
126
|
-
"subtitle": "Welcome to
|
|
126
|
+
"subtitle": "Welcome to loopwind"
|
|
127
127
|
}
|
|
128
128
|
|
|
129
|
-
|
|
129
|
+
loopwind render banner-hero --props props.json --out banner.png
|
|
130
130
|
```
|
|
131
131
|
|
|
132
132
|
**Output formats:**
|
|
133
133
|
|
|
134
134
|
```bash
|
|
135
135
|
# PNG (default) - best for photos and complex gradients
|
|
136
|
-
|
|
136
|
+
loopwind render banner-hero --props props.json --format png -o banner.png
|
|
137
137
|
|
|
138
138
|
# SVG - scalable vector, smaller file size, perfect for template composition
|
|
139
|
-
|
|
139
|
+
loopwind render banner-hero --props props.json --format svg -o banner.svg
|
|
140
140
|
|
|
141
141
|
# WebP - modern format, smaller than PNG with similar quality
|
|
142
|
-
|
|
142
|
+
loopwind render banner-hero --props props.json --format webp -o banner.webp
|
|
143
143
|
|
|
144
144
|
# JPEG - smallest file size, good for photos
|
|
145
|
-
|
|
145
|
+
loopwind render banner-hero --props props.json --format jpg -o banner.jpg
|
|
146
146
|
```
|
|
147
147
|
|
|
148
148
|
**SVG benefits with template composition:**
|
|
@@ -154,30 +154,30 @@ dsgn render banner-hero --props props.json --format jpg -o banner.jpg
|
|
|
154
154
|
### List Installed Templates
|
|
155
155
|
|
|
156
156
|
```bash
|
|
157
|
-
|
|
157
|
+
loopwind list
|
|
158
158
|
```
|
|
159
159
|
|
|
160
160
|
### Validate Templates
|
|
161
161
|
|
|
162
162
|
```bash
|
|
163
|
-
|
|
164
|
-
|
|
163
|
+
loopwind validate
|
|
164
|
+
loopwind validate banner-hero
|
|
165
165
|
```
|
|
166
166
|
|
|
167
167
|
## SDK for Programmatic Use
|
|
168
168
|
|
|
169
|
-
Use **
|
|
169
|
+
Use **loopwind** programmatically in your Next.js API routes, serverless functions, or Node.js applications!
|
|
170
170
|
|
|
171
171
|
### Installation
|
|
172
172
|
|
|
173
173
|
```bash
|
|
174
|
-
npm install
|
|
174
|
+
npm install loopwind
|
|
175
175
|
```
|
|
176
176
|
|
|
177
177
|
### Quick Example
|
|
178
178
|
|
|
179
179
|
```typescript
|
|
180
|
-
import { defineTemplate, renderImage } from '
|
|
180
|
+
import { defineTemplate, renderImage } from 'loopwind/sdk';
|
|
181
181
|
|
|
182
182
|
// Define template programmatically
|
|
183
183
|
const ogTemplate = defineTemplate({
|
|
@@ -194,7 +194,7 @@ const ogTemplate = defineTemplate({
|
|
|
194
194
|
// Render to buffer
|
|
195
195
|
const png = await renderImage(ogTemplate, {
|
|
196
196
|
title: 'Hello World',
|
|
197
|
-
description: 'Generated with
|
|
197
|
+
description: 'Generated with loopwind SDK',
|
|
198
198
|
});
|
|
199
199
|
|
|
200
200
|
// Use in Next.js API route
|
|
@@ -208,7 +208,7 @@ export default async function handler(req, res) {
|
|
|
208
208
|
### Video Rendering
|
|
209
209
|
|
|
210
210
|
```typescript
|
|
211
|
-
import { defineTemplate, renderVideo } from '
|
|
211
|
+
import { defineTemplate, renderVideo } from 'loopwind/sdk';
|
|
212
212
|
|
|
213
213
|
const introTemplate = defineTemplate({
|
|
214
214
|
name: 'intro-video',
|
|
@@ -253,7 +253,7 @@ See the full example in [`examples/nextjs-api/`](examples/nextjs-api/)
|
|
|
253
253
|
|
|
254
254
|
```typescript
|
|
255
255
|
// pages/api/og-image.ts
|
|
256
|
-
import { defineTemplate, renderImage } from '
|
|
256
|
+
import { defineTemplate, renderImage } from 'loopwind/sdk';
|
|
257
257
|
|
|
258
258
|
const template = defineTemplate({
|
|
259
259
|
name: 'og-image',
|
|
@@ -280,7 +280,7 @@ https://yoursite.com/api/og-image?title=Hello+World
|
|
|
280
280
|
|
|
281
281
|
## shadcn/ui Design System
|
|
282
282
|
|
|
283
|
-
|
|
283
|
+
loopwind uses **shadcn/ui's design system** by default! All templates have access to semantic color tokens:
|
|
284
284
|
|
|
285
285
|
```tsx
|
|
286
286
|
// Use shadcn colors in templates
|
|
@@ -293,21 +293,21 @@ dsgn uses **shadcn/ui's design system** by default! All templates have access to
|
|
|
293
293
|
**Supported shadcn classes:**
|
|
294
294
|
- `text-primary`, `bg-secondary`, `text-muted-foreground`, `bg-card`, `border`, `bg-destructive`
|
|
295
295
|
- **Opacity modifiers**: `bg-primary/50`, `text-muted-foreground/75`, `border/30`
|
|
296
|
-
- **Dark mode ready**: Override colors in `
|
|
296
|
+
- **Dark mode ready**: Override colors in `loopwind.json`
|
|
297
297
|
|
|
298
298
|
See `SHADCN_INTEGRATION.md` for complete documentation.
|
|
299
299
|
|
|
300
|
-
## Configuration (
|
|
300
|
+
## Configuration (loopwind.json)
|
|
301
301
|
|
|
302
|
-
Templates automatically use your project's design tokens defined in `
|
|
302
|
+
Templates automatically use your project's design tokens defined in `loopwind.json`. This allows generated images to match your brand colors and design system.
|
|
303
303
|
|
|
304
304
|
### Initialize Config
|
|
305
305
|
|
|
306
306
|
```bash
|
|
307
|
-
|
|
307
|
+
loopwind init
|
|
308
308
|
```
|
|
309
309
|
|
|
310
|
-
This creates a `
|
|
310
|
+
This creates a `loopwind.json` file in your project:
|
|
311
311
|
|
|
312
312
|
```json
|
|
313
313
|
{
|
|
@@ -389,7 +389,7 @@ Combine with custom styles:
|
|
|
389
389
|
|
|
390
390
|
### Automatic Tailwind Config Support
|
|
391
391
|
|
|
392
|
-
**
|
|
392
|
+
**loopwind automatically detects and uses your `tailwind.config.js`!**
|
|
393
393
|
|
|
394
394
|
If you have a Tailwind project:
|
|
395
395
|
|
|
@@ -423,7 +423,7 @@ Your templates can use these values:
|
|
|
423
423
|
|
|
424
424
|
**Config priority:**
|
|
425
425
|
1. `tailwind.config.js` (if exists)
|
|
426
|
-
2. `
|
|
426
|
+
2. `loopwind.json` (fallback)
|
|
427
427
|
3. Default Tailwind values
|
|
428
428
|
|
|
429
429
|
**Supported classes:**
|
|
@@ -435,7 +435,7 @@ Your templates can use these values:
|
|
|
435
435
|
- shadcn/ui colors: `bg-card`, `text-foreground`, `text-muted-foreground`
|
|
436
436
|
- Opacity modifiers: `bg-primary/50`, `text-muted-foreground/75`
|
|
437
437
|
|
|
438
|
-
**Note:** Tailwind v4 uses CSS variables instead of JS config. We're working on CSS parsing support. For now, use `
|
|
438
|
+
**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).
|
|
439
439
|
|
|
440
440
|
## Fonts
|
|
441
441
|
|
|
@@ -494,7 +494,7 @@ Templates have access to built-in helper functions:
|
|
|
494
494
|
- **`image(propKey)`** - Embed images as data URIs
|
|
495
495
|
- **`video(propKey)`** - Embed video frames (for video templates)
|
|
496
496
|
- **`template(name, props)`** - Embed other templates
|
|
497
|
-
- **`config`** - Access
|
|
497
|
+
- **`config`** - Access loopwind.json configuration
|
|
498
498
|
|
|
499
499
|
### QR Code Helper
|
|
500
500
|
|
|
@@ -517,9 +517,9 @@ export default function Template({ title, url, qr, tw }) {
|
|
|
517
517
|
|
|
518
518
|
**Usage:**
|
|
519
519
|
```bash
|
|
520
|
-
|
|
520
|
+
loopwind render qr-card '{
|
|
521
521
|
"title": "Visit Our Website",
|
|
522
|
-
"url": "https://
|
|
522
|
+
"url": "https://loopwind.dev"
|
|
523
523
|
}'
|
|
524
524
|
```
|
|
525
525
|
|
|
@@ -573,7 +573,7 @@ export default function Banner({ background, tw, image }) {
|
|
|
573
573
|
|
|
574
574
|
**Usage:**
|
|
575
575
|
```bash
|
|
576
|
-
|
|
576
|
+
loopwind render banner '{
|
|
577
577
|
"background": "./my-background.jpg"
|
|
578
578
|
}'
|
|
579
579
|
```
|
|
@@ -630,7 +630,7 @@ export default function VideoOverlay({ background, title, tw, video, frame, prog
|
|
|
630
630
|
|
|
631
631
|
**Usage:**
|
|
632
632
|
```bash
|
|
633
|
-
|
|
633
|
+
loopwind render video-overlay props.json --out output.mp4
|
|
634
634
|
```
|
|
635
635
|
|
|
636
636
|
**How it works:**
|
|
@@ -669,7 +669,7 @@ export default function Template({ title, bannerTitle, bannerSubtitle, template,
|
|
|
669
669
|
|
|
670
670
|
**Usage:**
|
|
671
671
|
```bash
|
|
672
|
-
|
|
672
|
+
loopwind render composite-card '{
|
|
673
673
|
"title": "Product Launch",
|
|
674
674
|
"bannerTitle": "New Release",
|
|
675
675
|
"bannerSubtitle": "Coming Soon"
|
|
@@ -777,22 +777,22 @@ export default function Template({ title, subtitle, frame, progress, tw, qr, tem
|
|
|
777
777
|
|
|
778
778
|
## Commands
|
|
779
779
|
|
|
780
|
-
### `
|
|
780
|
+
### `loopwind init`
|
|
781
781
|
|
|
782
|
-
Initialize a `
|
|
782
|
+
Initialize a `loopwind.json` config file with default design tokens.
|
|
783
783
|
|
|
784
|
-
### `
|
|
784
|
+
### `loopwind add <template>`
|
|
785
785
|
|
|
786
786
|
Install a template from the registry.
|
|
787
787
|
|
|
788
788
|
Options:
|
|
789
789
|
- `-r, --registry <url>` - Custom registry URL
|
|
790
790
|
|
|
791
|
-
### `
|
|
791
|
+
### `loopwind list`
|
|
792
792
|
|
|
793
793
|
List all installed templates with metadata.
|
|
794
794
|
|
|
795
|
-
### `
|
|
795
|
+
### `loopwind render <template>`
|
|
796
796
|
|
|
797
797
|
Render a template to an image.
|
|
798
798
|
|
|
@@ -802,25 +802,25 @@ Options:
|
|
|
802
802
|
- `--format <format>` - Output format: png, svg, webp (default: png)
|
|
803
803
|
- `--video` - Render as video (coming soon)
|
|
804
804
|
|
|
805
|
-
### `
|
|
805
|
+
### `loopwind validate [template]`
|
|
806
806
|
|
|
807
807
|
Validate template metadata. If no template is specified, validates all installed templates.
|
|
808
808
|
|
|
809
809
|
## Validation & Error Messages
|
|
810
810
|
|
|
811
|
-
|
|
811
|
+
loopwind automatically validates templates and props before rendering, providing helpful error messages.
|
|
812
812
|
|
|
813
813
|
### Automatic Validation
|
|
814
814
|
|
|
815
815
|
```bash
|
|
816
816
|
# Missing required props
|
|
817
|
-
$
|
|
817
|
+
$ loopwind render banner-hero --props '{}'
|
|
818
818
|
✖ Template validation failed
|
|
819
819
|
✗ props: Missing required prop: "title"
|
|
820
820
|
→ Add "title" to your props: --props '{"title":"value"}'
|
|
821
821
|
|
|
822
822
|
# Wrong prop type
|
|
823
|
-
$
|
|
823
|
+
$ loopwind render banner-hero --props '{"title":123}'
|
|
824
824
|
✖ Template validation failed
|
|
825
825
|
✗ props: Prop "title" should be a string, got number
|
|
826
826
|
→ Change "title" to a string: "title": "value"
|
|
@@ -828,10 +828,10 @@ $ dsgn render banner-hero --props '{"title":123}'
|
|
|
828
828
|
|
|
829
829
|
### Enhanced Satori Error Messages
|
|
830
830
|
|
|
831
|
-
When rendering fails,
|
|
831
|
+
When rendering fails, loopwind provides clear suggestions:
|
|
832
832
|
|
|
833
833
|
```bash
|
|
834
|
-
$
|
|
834
|
+
$ loopwind render my-template --props props.json
|
|
835
835
|
✖ Failed to render template
|
|
836
836
|
|
|
837
837
|
Error: Satori requires explicit display: flex for containers with multiple children
|
|
@@ -846,12 +846,12 @@ See `VALIDATION.md` for complete validation documentation and troubleshooting.
|
|
|
846
846
|
|
|
847
847
|
## Creating Custom Templates
|
|
848
848
|
|
|
849
|
-
Templates are stored in your project's `
|
|
849
|
+
Templates are stored in your project's `_loopwind/templates/` directory. You can create custom templates:
|
|
850
850
|
|
|
851
851
|
1. Create a folder:
|
|
852
852
|
|
|
853
853
|
```bash
|
|
854
|
-
mkdir -p
|
|
854
|
+
mkdir -p _loopwind/templates/my-template
|
|
855
855
|
```
|
|
856
856
|
|
|
857
857
|
2. Create `meta.json`:
|
|
@@ -893,8 +893,8 @@ export default function MyTemplate({ title }) {
|
|
|
893
893
|
4. Validate and render:
|
|
894
894
|
|
|
895
895
|
```bash
|
|
896
|
-
|
|
897
|
-
|
|
896
|
+
loopwind validate my-template
|
|
897
|
+
loopwind render my-template --props '{"title":"Hello"}' --out test.png
|
|
898
898
|
```
|
|
899
899
|
|
|
900
900
|
## Use Cases
|
|
@@ -911,7 +911,7 @@ Video templates use `type: "video"` and support `frame` and `progress` props for
|
|
|
911
911
|
|
|
912
912
|
### ⚡ No Dependencies Required
|
|
913
913
|
|
|
914
|
-
**
|
|
914
|
+
**loopwind uses pure JavaScript/WASM for video encoding** - works everywhere!
|
|
915
915
|
|
|
916
916
|
✅ Works on **Vercel Edge Functions**
|
|
917
917
|
✅ Works on **Netlify Functions**
|
|
@@ -956,13 +956,13 @@ export default function Template({ title, frame, progress, tw, qr, template }) {
|
|
|
956
956
|
|
|
957
957
|
```bash
|
|
958
958
|
# Render to MP4
|
|
959
|
-
|
|
959
|
+
loopwind render my-video '{"title":"Animated Title"}' -o output.mp4
|
|
960
960
|
|
|
961
961
|
# With custom quality settings
|
|
962
|
-
|
|
962
|
+
loopwind render my-video props.json --crf 18 # Higher quality (lower CRF = better quality)
|
|
963
963
|
|
|
964
964
|
# Export frames only (for manual encoding)
|
|
965
|
-
|
|
965
|
+
loopwind render my-video props.json --frames-only -o frames/
|
|
966
966
|
```
|
|
967
967
|
|
|
968
968
|
**How it works:**
|
|
@@ -1006,13 +1006,13 @@ See `website/README.md` for more details.
|
|
|
1006
1006
|
Templates are fetched from a registry (similar to shadcn/ui). The default registry is:
|
|
1007
1007
|
|
|
1008
1008
|
```
|
|
1009
|
-
https://
|
|
1009
|
+
https://loopwind.dev/r
|
|
1010
1010
|
```
|
|
1011
1011
|
|
|
1012
1012
|
You can host your own registry and use it with:
|
|
1013
1013
|
|
|
1014
1014
|
```bash
|
|
1015
|
-
|
|
1015
|
+
loopwind add my-template --registry https://my-registry.com
|
|
1016
1016
|
```
|
|
1017
1017
|
|
|
1018
1018
|
## License
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "loopwind",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.2",
|
|
4
4
|
"description": "A CLI tool for AI code agents and developers for generating images and videos.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -21,8 +21,7 @@
|
|
|
21
21
|
"build": "tsc && npm run copy-templates",
|
|
22
22
|
"copy-templates": "cp -r src/default-templates dist/",
|
|
23
23
|
"dev": "tsc --watch",
|
|
24
|
-
"prepublishOnly": "npm run build"
|
|
25
|
-
"postinstall": "patch-package"
|
|
24
|
+
"prepublishOnly": "npm run build"
|
|
26
25
|
},
|
|
27
26
|
"keywords": [
|
|
28
27
|
"design",
|
package/website/astro.config.mjs
CHANGED
package/website/package.json
CHANGED