loopwind 0.18.1 → 0.19.0

package/examples/template-compiler-workflow.ts

@@ -0,0 +1,251 @@
+/**
+ * Example: Template Compiler Workflow
+ *
+ * This example demonstrates the recommended production workflow for JSX templates:
+ *
+ * 1. ADMIN PANEL: Use compileTemplate() to transform JSX → JavaScript
+ * 2. DATABASE: Store the compiled JavaScript
+ * 3. PRODUCTION API: Use defineTemplateFromSource() to render
+ *
+ * Benefits:
+ * - JSX developer experience in admin panel
+ * - No @babel/standalone in production (36 MB smaller!)
+ * - Faster cold starts in serverless functions
+ * - Syntax errors caught at save time, not render time
+ */
+
+import { compileTemplate, containsJSX } from 'loopwind/sdk/compiler';
+import { defineTemplateFromSource, renderImage } from 'loopwind/sdk';
+import fs from 'fs/promises';
+
+// ============================================================================
+// PART 1: Admin Panel - Compile and Save
+// ============================================================================
+
+/**
+ * Simulates an admin panel API where users edit templates in a code editor
+ */
+async function adminPanelSaveTemplate(templateId: string, userCode: string) {
+  console.log('📝 Admin Panel: User saved template\n');
+  console.log('User-provided JSX:');
+  console.log(userCode.substring(0, 200) + '...\n');
+
+  try {
+    // Check if the code contains JSX
+    if (containsJSX(userCode)) {
+      console.log('✓ Detected JSX syntax, compiling...');
+
+      // Compile JSX to JavaScript
+      const compiled = compileTemplate(userCode);
+
+      console.log('✓ Compilation successful!');
+      console.log('  Original size:', userCode.length, 'bytes');
+      console.log('  Compiled size:', compiled.length, 'bytes\n');
+
+      // In a real app, you would save to a database:
+      // await db.templates.update(templateId, {
+      //   sourceCode: compiled,
+      //   updatedAt: new Date()
+      // });
+
+      // For this example, save to a file
+      await fs.writeFile(`template-${templateId}-compiled.js`, compiled);
+      console.log('✓ Saved compiled template to database\n');
+
+      return { success: true, compiled };
+    } else {
+      console.log('ℹ No JSX detected, saving as-is\n');
+      return { success: true, compiled: userCode };
+    }
+  } catch (error) {
+    console.error('✗ Compilation failed:', (error as Error).message);
+    return {
+      success: false,
+      error: (error as Error).message,
+    };
+  }
+}
+
+// ============================================================================
+// PART 2: Production API - Load and Render
+// ============================================================================
+
+/**
+ * Simulates a production API endpoint that renders templates
+ * This runs in Vercel, AWS Lambda, or any serverless function
+ */
+async function productionApiRenderTemplate(
+  templateId: string,
+  props: Record<string, any>
+) {
+  console.log('🚀 Production API: Rendering template\n');
+
+  try {
+    // Load pre-compiled template from database
+    // In a real app:
+    // const template = await db.templates.findById(templateId);
+    // const compiledCode = template.sourceCode;
+
+    // For this example, load from file
+    const compiledCode = await fs.readFile(
+      `template-${templateId}-compiled.js`,
+      'utf-8'
+    );
+
+    console.log('✓ Loaded pre-compiled template from database');
+    console.log('  Size:', compiledCode.length, 'bytes');
+    console.log('  No Babel needed! 🎉\n');
+
+    // Define template from pre-compiled JavaScript
+    // This is FAST - no JSX transformation at runtime
+    const templateDef = defineTemplateFromSource(compiledCode, {
+      config: {
+        colors: {
+          primary: '#3b82f6',
+          secondary: '#8b5cf6',
+        },
+      },
+    });
+
+    console.log('✓ Template loaded');
+    console.log('  Name:', templateDef.name);
+    console.log('  Type:', templateDef.type);
+    console.log('  Size:', templateDef.size.width, 'x', templateDef.size.height, '\n');
+
+    // Render the image
+    const png = await renderImage(templateDef, props);
+
+    console.log('✓ Image rendered');
+    console.log('  PNG size:', png.length, 'bytes\n');
+
+    return png;
+  } catch (error) {
+    console.error('✗ Rendering failed:', (error as Error).message);
+    throw error;
+  }
+}
+
+// ============================================================================
+// DEMO: Full Workflow
+// ============================================================================
+
+async function demo() {
+  console.log('='.repeat(70));
+  console.log('🎨 Template Compiler Workflow Demo');
+  console.log('='.repeat(70) + '\n');
+
+  // Example JSX template that a user might write in a code editor
+  const userJSX = `
+export const meta = {
+  name: 'social-card',
+  type: 'image',
+  size: { width: 1200, height: 630 }
+};
+
+export default ({ tw, title, description, author }) => (
+  <div style={tw('flex flex-col justify-between w-full h-full bg-gradient-to-br from-primary to-secondary p-12')}>
+    <div style={tw('flex flex-col')}>
+      <h1 style={tw('text-6xl font-bold text-white mb-4')}>
+        {title}
+      </h1>
+      <p style={tw('text-2xl text-white/90')}>
+        {description}
+      </p>
+    </div>
+    <div style={tw('flex items-center gap-4')}>
+      <div style={tw('w-16 h-16 rounded-full bg-white/20')} />
+      <span style={tw('text-xl text-white/80')}>{author}</span>
+    </div>
+  </div>
+);
+`;
+
+  const templateId = 'card-123';
+
+  // STEP 1: Admin panel compiles and saves
+  console.log('STEP 1: Admin Panel Workflow');
+  console.log('-'.repeat(70) + '\n');
+  await adminPanelSaveTemplate(templateId, userJSX);
+
+  // STEP 2: Production API loads and renders
+  console.log('STEP 2: Production API Workflow');
+  console.log('-'.repeat(70) + '\n');
+  const png = await productionApiRenderTemplate(templateId, {
+    title: 'Building with loopwind',
+    description: 'Generate images and videos programmatically',
+    author: 'Tommy Vedvik',
+  });
+
+  // Save the final result
+  await fs.writeFile('social-card-demo.png', png);
+  console.log('✅ Saved final image to social-card-demo.png\n');
+
+  // Cleanup
+  await fs.unlink(`template-${templateId}-compiled.js`);
+
+  console.log('='.repeat(70));
+  console.log('📊 Workflow Summary');
+  console.log('='.repeat(70));
+  console.log('\n✅ Benefits of this approach:\n');
+  console.log('1. Users write natural JSX syntax in admin panel');
+  console.log('2. JSX compiled once at save time (not every render)');
+  console.log('3. Compiled templates stored in database');
+  console.log('4. Production bundle 36 MB smaller (no @babel/standalone)');
+  console.log('5. Faster cold starts in serverless functions');
+  console.log('6. Syntax errors caught early (at save, not production)\n');
+
+  console.log('🔧 For Vercel/Lambda deployments:\n');
+  console.log('- Admin panel imports: loopwind/sdk/compiler');
+  console.log('- Production API imports: loopwind/sdk');
+  console.log('- Result: Only admin panel includes Babel\n');
+}
+
+// ============================================================================
+// Example Integration Code
+// ============================================================================
+
+/**
+ * Example: Next.js Admin Panel API Route
+ */
+async function exampleNextJSAdminRoute(req: any, res: any) {
+  const { templateId, code } = req.body;
+
+  try {
+    // Compile JSX
+    const compiled = compileTemplate(code);
+
+    // Save to database
+    // await db.templates.update(templateId, { sourceCode: compiled });
+
+    res.json({ success: true });
+  } catch (error) {
+    res.status(400).json({
+      error: 'Compilation failed',
+      message: (error as Error).message,
+    });
+  }
+}
+
+/**
+ * Example: Next.js Production API Route
+ */
+async function exampleNextJSProductionRoute(req: any, res: any) {
+  const { templateId, props } = req.body;
+
+  try {
+    // Load pre-compiled template
+    // const template = await db.templates.findById(templateId);
+    // const templateDef = defineTemplateFromSource(template.sourceCode);
+
+    // Render
+    // const png = await renderImage(templateDef, props);
+
+    // res.setHeader('Content-Type', 'image/png');
+    // res.send(png);
+  } catch (error) {
+    res.status(500).json({ error: 'Rendering failed' });
+  }
+}
+
+// Run the demo
+demo().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopwind",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "A CLI tool for AI code agents and developers for generating images and videos.",
   "type": "module",
   "bin": {
@@ -15,6 +15,10 @@
     "./sdk": {
       "types": "./dist/sdk/index.d.ts",
       "default": "./dist/sdk/index.js"
+    },
+    "./sdk/compiler": {
+      "types": "./dist/sdk/compiler.d.ts",
+      "default": "./dist/sdk/compiler.js"
     }
   },
   "scripts": {
@@ -46,7 +50,6 @@
     "url": "https://github.com/tomtev/loopwind/issues"
   },
   "dependencies": {
-    "@babel/standalone": "^7.28.5",
     "@resvg/resvg-js": "^2.6.0",
     "@vitejs/plugin-react": "^5.1.1",
     "boxen": "^7.1.1",
@@ -75,6 +78,7 @@
     "vite": "^7.2.2"
   },
   "devDependencies": {
+    "@babel/standalone": "^7.28.5",
     "@types/babel__standalone": "^7.1.9",
     "@types/chalk-animation": "^1.6.3",
     "@types/express": "^5.0.5",

package/test-jsx-support.mjs

@@ -1,10 +1,15 @@
 /**
- * Test JSX support in defineTemplateFromSource
+ * Test JSX support with compileTemplate + defineTemplateFromSource
+ *
+ * This test demonstrates the recommended workflow:
+ * 1. compileTemplate() - transforms JSX to JavaScript (admin/build time)
+ * 2. defineTemplateFromSource() - loads pre-compiled JavaScript (production)
  */
 
 import { defineTemplateFromSource, renderImage } from './dist/sdk/index.js';
+import { compileTemplate } from './dist/sdk/compiler.js';
 
-console.log('Testing JSX Support in defineTemplateFromSource\n');
+console.log('Testing JSX Support with Pre-compilation\n');
 
 // Test 1: Simple JSX template
 const simpleJSX = `
@@ -22,7 +27,11 @@ export default ({ tw, title }) => (
 `;
 
 try {
-  const template1 = defineTemplateFromSource(simpleJSX);
+  // Step 1: Compile JSX to JavaScript (admin/build time)
+  const compiledJS = compileTemplate(simpleJSX);
+
+  // Step 2: Load compiled template (production runtime)
+  const template1 = defineTemplateFromSource(compiledJS);
   const png1 = await renderImage(template1, { title: 'JSX Works!' });
   console.log('✓ Simple JSX template works');
   console.log('  PNG size:', png1.length, 'bytes\n');
@@ -53,7 +62,11 @@ export default ({ tw, title, subtitle, items }) => (
 `;
 
 try {
-  const template2 = defineTemplateFromSource(nestedJSX);
+  // Step 1: Compile JSX to JavaScript
+  const compiledJS2 = compileTemplate(nestedJSX);
+
+  // Step 2: Load compiled template
+  const template2 = defineTemplateFromSource(compiledJS2);
   const png2 = await renderImage(template2, {
     title: 'Nested JSX',
     subtitle: 'With multiple levels',
@@ -82,7 +95,11 @@ export default ({ tw }) => (
 `;
 
 try {
-  const template3 = defineTemplateFromSource(selfClosing);
+  // Step 1: Compile JSX to JavaScript
+  const compiledJS3 = compileTemplate(selfClosing);
+
+  // Step 2: Load compiled template
+  const template3 = defineTemplateFromSource(compiledJS3);
   const png3 = await renderImage(template3, {});
   console.log('✓ Self-closing tags work');
   console.log('  PNG size:', png3.length, 'bytes\n');
@@ -109,7 +126,11 @@ export default ({ tw, title, count }) => (
 `;
 
 try {
-  const template4 = defineTemplateFromSource(complexAttrs);
+  // Step 1: Compile JSX to JavaScript
+  const compiledJS4 = compileTemplate(complexAttrs);
+
+  // Step 2: Load compiled template
+  const template4 = defineTemplateFromSource(compiledJS4);
   const png4 = await renderImage(template4, { title: 'Complex JSX', count: 42 });
   console.log('✓ Complex attributes work');
   console.log('  PNG size:', png4.length, 'bytes\n');
@@ -118,3 +139,8 @@ try {
 }
 
 console.log('✅ All JSX tests completed!');
+console.log('\nWorkflow Summary:');
+console.log('1. compileTemplate() - Transform JSX → JS (admin panel)');
+console.log('2. defineTemplateFromSource() - Load compiled JS (production)');
+console.log('3. renderImage() - Render with props');
+console.log('\nBenefit: No @babel/standalone in production! 🎉');