feat: enhance API to support direct HTML content rendering alongside URL rendering

carbogninalberto · carbogninalberto · commit ce6513425691 · 2025-11-11T20:24:35.000+01:00
### Changes
- Updated README.md to reflect new feature allowing HTML content to be passed directly for rendering.
- Modified PuppeteerWrapper to handle both URL and HTML content, ensuring either can be provided for rendering.
- Adjusted Swagger API documentation to indicate that either 'url' or 'html' must be supplied in requests.
- Enhanced validation logic to enforce the requirement of at least one of 'url' or 'html' in the request configuration.

### Problem Solved
This update allows users to generate PDFs and images directly from HTML content, improving flexibility for various use cases.
diff --git a/README.md b/README.md
@@ -17,9 +17,10 @@ It provides a basic yet performant wrapper along with additional features to enh
 
 ## Features
 
-✅ Generate PNG images from any URL<br>
-✅ Generate PDFs from any URL<br>
+✅ Generate PNG images from any URL or HTML content<br>
+✅ Generate PDFs from any URL or HTML content<br>
 ✅ Generate Videos from any URL with smooth animation<br>
+✅ **Direct HTML rendering** - Pass HTML content directly without needing a URL<br>
 ✅ Support for custom headers (like Authorization)<br>
 ✅ Support to render Lazy animations<br>
 ✅ Additional support for blocking: Cookies, Ads, Trackers, Banner<br>
@@ -33,16 +34,116 @@ For usage in commercial services, please refer to the `license.txt` file in this
 
 Note: License is not enforced, but we are a small team, and any support to further develop this product would be greatly appreciated! 🙏
 
-## How to create your API call
+## API Usage
+
+### Render from URL
 
 Use the Playground at [html2pdfapi](https://html2pdfapi.com/playground) (a free account is required), to create the API request in your favorite language.
 You can omit the `apiKey` parameter.
 
+**Example - Generate PDF from URL:**
+```bash
+curl -X POST http://localhost:3000/render \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://example.com",
+    "type": "pdf"
+  }' \
+  --output output.pdf
+```
+
+### Render from HTML Content
+
+You can now pass HTML content directly to the API without needing a URL! This is perfect for:
+- Generating PDFs from dynamically created HTML
+- Creating images from HTML templates
+- Converting HTML email templates to images
+- Any scenario where you have HTML as a string
+
+**Example - Generate PDF from HTML:**
+```bash
+curl -X POST http://localhost:3000/render \
+  -H "Content-Type: application/json" \
+  -d '{
+    "html": "<!DOCTYPE html><html><head><title>My Document</title><style>body { font-family: Arial; padding: 40px; } h1 { color: #333; }</style></head><body><h1>Hello World!</h1><p>This PDF was generated from HTML content.</p></body></html>",
+    "type": "pdf"
+  }' \
+  --output output.pdf
+```
+
+**Example - Generate PNG from HTML:**
+```bash
+curl -X POST http://localhost:3000/render \
+  -H "Content-Type: application/json" \
+  -d '{
+    "html": "<!DOCTYPE html><html><head><style>body { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; display: flex; justify-content: center; align-items: center; height: 100vh; font-family: sans-serif; } .card { background: rgba(255,255,255,0.1); padding: 40px; border-radius: 20px; }</style></head><body><div class=\"card\"><h1>Beautiful Card</h1><p>Rendered from HTML!</p></div></body></html>",
+    "type": "image",
+    "image": { "type": "png" }
+  }' \
+  --output output.png
+```
+
+**Example - With Custom Options:**
+```bash
+curl -X POST http://localhost:3000/render \
+  -H "Content-Type: application/json" \
+  -d '{
+    "html": "<html><body><h1>Custom Settings</h1></body></html>",
+    "type": "pdf",
+    "device": {
+      "width": 800,
+      "height": 600
+    },
+    "pdf": {
+      "format": "Letter",
+      "printBackground": true,
+      "margin": {
+        "top": "20px",
+        "right": "20px",
+        "bottom": "20px",
+        "left": "20px"
+      }
+    }
+  }' \
+  --output custom.pdf
+```
+
+**Important Notes:**
+- Either `url` OR `html` must be provided (not both)
+- All standard options (device settings, PDF options, image options, etc.) work with both URL and HTML modes
+- When using HTML content, network idle wait conditions (`networkidle0`, `networkidle2`) are automatically adjusted to prevent timeouts
+
 The Saas solution of our service provides out-of-the-box async support so that you don't have to implement your own.
 
 There are many libraries you can use to achieve it, it depends on the language you are using, this is a very lightweight and versatile solution if you are looking
 for a simple, yet performant solution.
 
+## API Reference
+
+### Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/render` | POST | Render URL or HTML to PDF/Image/Video |
+| `/render?config=...` | GET | Render URL using GET with JSON config parameter |
+| `/health` | GET | Health check with browser pool stats |
+| `/docs` | GET | Swagger API documentation |
+
+### Request Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Either url or html | URL to render |
+| `html` | string | Either url or html | HTML content to render |
+| `type` | string | Yes | Output type: `image`, `pdf`, `video`, `html` |
+| `device` | object | No | Device settings (width, height, userAgent, etc.) |
+| `render` | object | No | Render options (waitTime, fullPage, scroll, etc.) |
+| `image` | object | No | Image settings (type, quality, compression, etc.) |
+| `pdf` | object | No | PDF settings (format, margins, orientation, etc.) |
+| `video` | object | No | Video settings (fps, duration, codec, etc.) |
+
+For complete API documentation, visit `/docs` endpoint after starting the server.
+
 ## Getting Started with Development
 
 To get started, run the following commands:
diff --git a/app/core/wrapper.js b/app/core/wrapper.js
@@ -51,6 +51,7 @@ export class PuppeteerWrapper {
 
     // generation config
     this.url = config?.url ?? "";
+    this.html = config?.html ?? "";
     this.type = config?.type ?? "image";
 
     // custom headers
@@ -288,7 +289,20 @@ export class PuppeteerWrapper {
       throw new Error("Page not initialized. Call initialize() first.");
     }
 
-    await this.page.goto(this.url, { waitUntil: this.render.waitUntil });
+    // Load either URL or HTML content
+    if (this.html) {
+      // When using setContent with HTML, we can't use networkidle0/networkidle2
+      // as there are no network requests, so we use 'load' or 'domcontentloaded'
+      const waitUntil = this.render.waitUntil === 'networkidle0' || this.render.waitUntil === 'networkidle2'
+        ? 'load'
+        : this.render.waitUntil;
+      await this.page.setContent(this.html, { waitUntil });
+    } else if (this.url) {
+      await this.page.goto(this.url, { waitUntil: this.render.waitUntil });
+    } else {
+      throw new Error("Either URL or HTML content must be provided");
+    }
+
     if (this.render.waitTime && this.render.waitTime >= 0) {
       await new Promise((resolve) => setTimeout(resolve, this.render.waitTime));
     }
@@ -304,7 +318,7 @@ export class PuppeteerWrapper {
     let content;
     let contentType;
     let filename;
-    let host = new URL(this.url).hostname;
+    let host = this.url ? new URL(this.url).hostname : 'html-content';
 
     // set config with all the properties of this class
     const config = {
diff --git a/app/docs/swagger.json b/app/docs/swagger.json
@@ -196,12 +196,16 @@
     "schemas": {
       "RenderRequest": {
         "type": "object",
-        "required": ["url", "type"],
+        "required": ["type"],
         "properties": {
           "url": {
             "type": "string",
             "format": "uri",
-            "description": "URL of the web page to render"
+            "description": "URL of the web page to render. Either 'url' or 'html' must be provided."
+          },
+          "html": {
+            "type": "string",
+            "description": "HTML content to render directly. Either 'url' or 'html' must be provided."
           },
           "type": {
             "type": "string",
diff --git a/app/utils/validator.js b/app/utils/validator.js
@@ -6,6 +6,7 @@ import { z } from "zod";
 export function validateConfig(config) {
   const configSchema = z.object({
     url: z.string().url().optional(),
+    html: z.string().optional(),
     type: z.enum(["image", "pdf", "video", "html"]),
     headers: z.record(z.string()).optional(),
     render: z
@@ -138,6 +139,9 @@ export function validateConfig(config) {
         timeout: z.number().positive().default(30000),
       })
       .optional(),
+  }).refine((data) => data.url || data.html, {
+    message: "Either 'url' or 'html' must be provided",
+    path: ["url", "html"],
   });
 
   try {
