Skip to content

NODE_RENDERER_GUIDE.md

Latest commit

 

History

History
467 lines (331 loc) · 9.07 KB

NODE_RENDERER_GUIDE.md

File metadata and controls

467 lines (331 loc) · 9.07 KB

🖥️ Node.js SVG Fullpage Renderer Guide

Add Node.js environment support to existing dom-to-image project

High-quality SVG → Image conversion using Puppeteer

📚 Included Files

Newly Added (JavaScript + JSDoc)

src/
├── renderer.js                 🎯 Main Renderer (Puppeteer Integration)
└── utils.js                    Utility Functions

examples/
├── node-renderer.js            📝 Usage Examples
└── fallback-server.js          🖥️ Express Server Example

NODE_RENDERER_GUIDE.md           This File (Guide)
SPEC_INTEGRATION.md              Technical Specifications
IMPLEMENTATION_GUIDE.md          Implementation Guide

Existing Files (No Changes)

  • ✅ src/dom-to-image.js - Browser Main Logic
  • ✅ spec/ - Test Suite
  • ✅ Gruntfile.js - Build Configuration

🚀 Quick Start

1️⃣ One Command to Start

# Install Puppeteer + Start server (all in one!)
npm run start-server

# Default: http://localhost:3000/render

Or run individually:

npm install puppeteer
npm run example:server

2️⃣ Run Examples

# Rendering example
npm run example:render

# Or server example (same as start-server)
npm run example:server

💡 Basic Usage

SVG String → PNG Conversion

const { renderSvgFullPage } = require('./src/renderer');

const svgString = `
  <svg width="300" height="150" xmlns="http://www.w3.org/2000/svg">
    <rect width="300" height="150" fill="skyblue"/>
    <circle cx="150" cy="75" r="50" fill="white"/>
  </svg>
`;

(async () => {
  const result = await renderSvgFullPage(svgString, {
    outputType: 'png',
    outputPath: './output.png',
    deviceScaleFactor: 2
  });

  console.log(`✨ Saved: ${result.width}x${result.height}`);
})();

Using Convenience Functions

const { svgToPng, svgToJpeg, svgToWebp } = require('./src/renderer');

// PNG
await svgToPng(svgString, { outputPath: './image.png' });

// JPEG (high quality)
await svgToJpeg(svgString, {
  outputPath: './image.jpg',
  quality: 0.95
});

// WebP
await svgToWebp(svgString, { outputPath: './image.webp' });

📖 API Reference

renderSvgFullPage(svgString, options)

Main Function - Render SVG string as image

Parameters

{
  // Output format
  outputType: 'png' | 'jpeg' | 'webp',  // Default: 'png'
  
  // File saving
  outputPath: string,                    // Return buffer only if omitted
  
  // Quality (JPEG only)
  quality: 0-1,                          // Default: 1
  
  // Resolution multiplier
  deviceScaleFactor: 1-3,                // Default: 2
  
  // Puppeteer timeout (ms)
  timeout: number                        // Default: 30000
}

Return Value

{
  buffer: Buffer,        // Image binary
  width: number,         // Final width (px)
  height: number,        // Final height (px)
  format: string,        // Format (png/jpeg/webp)
  path?: string          // Saved file path (if applicable)
}

Example

const result = await renderSvgFullPage(svg, {
  outputType: 'png',
  outputPath: './output.png',
  deviceScaleFactor: 2
});

console.log(`${result.width}x${result.height} PNG created`);

svgToPng(svgString, options)

SVG → PNG Conversion (Convenience Function)

const buffer = await svgToPng(svgString);
// Saves file if outputPath specified

svgToJpeg(svgString, options)

SVG → JPEG Conversion

const buffer = await svgToJpeg(svgString, { quality: 0.95 });

svgToWebp(svgString, options)

SVG → WebP Conversion

const buffer = await svgToWebp(svgString);

🎯 Practical Examples

Example 1: Basic Usage

const { svgToPng } = require('./src/renderer');

const svg = `<svg width="200" height="100"><rect width="200" height="100" fill="blue"/></svg>`;

(async () => {
  await svgToPng(svg, { outputPath: './my-image.png' });
  console.log('✅ Complete!');
})();

Example 2: High Resolution (Retina)

// 2x resolution
await svgToPng(svg, {
  deviceScaleFactor: 2,
  outputPath: './image-2x.png'
});

// 3x resolution (ultra-high quality)
await svgToPng(svg, {
  deviceScaleFactor: 3,
  outputPath: './image-3x.png'
});

Example 3: Generate Multiple Formats Simultaneously

const { renderSvgFullPage } = require('./src/renderer');

async function convertToAllFormats(svg) {
  const formats = [
    { type: 'png', ext: 'png' },
    { type: 'jpeg', ext: 'jpg', quality: 0.95 },
    { type: 'webp', ext: 'webp' }
  ];

  for (const fmt of formats) {
    await renderSvgFullPage(svg, {
      outputType: fmt.type,
      outputPath: `./output.${fmt.ext}`,
      quality: fmt.quality,
      deviceScaleFactor: 2
    });
    console.log(`✅ ${fmt.ext} created`);
  }
}

Example 4: Return Buffer (No File Saving)

const { renderSvgFullPage } = require('./src/renderer');

async function getImageBuffer(svg) {
  const result = await renderSvgFullPage(svg, {
    outputType: 'png',
    deviceScaleFactor: 2
    // outputPath omitted → return buffer only
  });

  return result.buffer;  // Buffer object
}

// Send over network
const buffer = await getImageBuffer(svg);
response.type('image/png').send(buffer);

Example 5: Express Server

const express = require('express');
const { renderSvgFullPage } = require('./src/renderer');

const app = express();
app.use(express.json());

app.post('/api/render', async (req, res) => {
  try {
    const { svg, format = 'png' } = req.body;

    const result = await renderSvgFullPage(svg, {
      outputType: format,
      deviceScaleFactor: 2
    });

    res.type(`image/${result.format}`).send(result.buffer);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

⚡ Optimization Tips

1️⃣ Fast Rendering

// Use 1x resolution for speed
await svgToPng(svg, { deviceScaleFactor: 1 });

// Reduce timeout for simple SVGs
await svgToPng(svg, { timeout: 5000 });

2️⃣ Reduce File Size

// Low quality JPEG
await svgToJpeg(svg, { quality: 0.5 });

// Use WebP (smaller file)
await svgToWebp(svg);

3️⃣ Memory Efficiency

# Increase Node.js heap size (for large SVGs)
node --max-old-space-size=4096 your-script.js

4️⃣ Batch Processing

const { svgToPng } = require('./src/renderer');

async function batchRender(svgList) {
  const results = [];

  for (const svg of svgList) {
    const result = await svgToPng(svg, {
      deviceScaleFactor: 2
    });
    results.push(result.buffer);
    console.log(`✅ Processed: ${results.length}/${svgList.length}`);
  }

  return results;
}

🐛 Troubleshooting

❌ "Puppeteer is not installed"

npm install puppeteer --force
npx puppeteer install

❌ "SVG element not found"

Verify SVG string has <svg> tag:

// ❌ Wrong
const svg = '<div><svg></svg></div>';  // Root is div

// ✅ Correct
const svg = '<svg width="300" height="150">...</svg>';  // SVG is root

❌ "Timeout error"

Increase timeout for complex SVGs:

await svgToPng(svg, {
  timeout: 60000  // 60 seconds
});

❌ "Out of memory"

node --max-old-space-size=8192 script.js

📊 Performance Benchmarks (Reference)

Configuration Render Time File Size Resolution
1x PNG ~0.5s 30KB 1x
2x PNG (Retina) ~0.7s 80KB 2x
3x PNG ~1.0s 180KB 3x
2x JPEG (95%) ~0.6s 20KB 2x
2x JPEG (50%) ~0.6s 10KB 2x

Actual times vary depending on SVG complexity

✅ Checklist

Setup Complete

  • npm install puppeteer completed
  • examples/node-renderer.js runs successfully
  • output/ directory created

Usage Started

  • SVG string prepared (width/height required)
  • renderSvgFullPage() or convenience functions called
  • Buffer or file verified

Production Ready

  • Error handling added
  • Puppeteer memory monitoring
  • Logging and debugging configured
  • Timeout values adjusted

🎓 Key Points

✅ SVG Dimension Detection

// SVG must have width/height attributes
<svg width="300" height="150">
  <!-- width, height required -->
</svg>

✅ File Saving vs Buffer Return

// Save to file
await svgToPng(svg, { outputPath: './image.png' });

// Return buffer only (no file saving)
const buffer = await renderSvgFullPage(svg, {
  outputType: 'png'
  // outputPath omitted
});

✅ deviceScaleFactor Selection

// General purpose (recommended)
deviceScaleFactor: 2

// High-quality printing
deviceScaleFactor: 3

// Fast preview
deviceScaleFactor: 1

📞 Support

Happy rendering! 🎉

Enjoy high-quality SVG rendering via Puppeteer!