Wappler PDF Streamer Extension

Stream PDF files directly to the browser for inline display in your Wappler applications.

Features

• ✅ Stream PDFs for inline browser display
• ✅ Optional download mode (attachment)
• ✅ Automatic content-type and caching headers
• ✅ Browser caching support with ETag
• ✅ 304 Not Modified responses for optimal performance
• ✅ Custom display filenames
• ✅ Comprehensive error handling
• ✅ Supports both absolute and relative paths

Installation

1. Install as per Wappler Extension Guidelines

https://community.wappler.io/t/how-to-install-custom-wappler-extensions/49982

2. Restart Wappler

After installation, you must restart Wappler for it to recognize the new extension.

1. Save all your work
2. Close Wappler completely
3. Reopen Wappler
4. Open your project

3. Verify Installation

After restart, the extension should appear in Server Connect:

1. Open any Server Connect file
2. Click the "+" button to add a step
3. Look for "PDF Operations" group
4. You should see "Stream PDF" action

Quick Start

Basic Usage - Display PDF in Browser

In your Server Connect action:

{
  "name": "streamPDF",
  "module": "pdfstreamer",
  "action": "stream",
  "options": {
    "filepath": "uploads/pdfs/document.pdf",
    "disposition": "inline"
  }
}

Force Download

{
  "name": "downloadPDF",
  "module": "pdfstreamer",
  "action": "stream",
  "options": {
    "filepath": "uploads/pdfs/document.pdf",
    "filename": "My Document.pdf",
    "disposition": "attachment"
  }
}

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | filepath | String | Yes | - | Path to the PDF file (relative to project root) | | filename | String | No | Original filename | Display name for the PDF | | disposition | String | No | inline | inline (display) or attachment (download) | | cache | Boolean | No | true | Enable browser caching with ETag |

Frontend Usage

Display in Browser

<!-- Direct link -->
<a href="/api/[server-action]/document.pdf" target="_blank" class="btn btn-primary">
  View PDF
</a>

<!-- Embed in iframe -->
<iframe 
  src="/api/[server-action]/document.pdf" 
  width="100%" 
  height="600px" 
  style="border: none;">
</iframe>

Response Headers

The extension automatically sets optimized headers:

Content-Type: application/pdf
Content-Length: [file size]
Content-Disposition: inline; filename="document.pdf"
Cache-Control: public, max-age=3600
ETag: "[timestamp]-[size]"

Caching Behavior

When caching is enabled (default):

1. First request: Returns full PDF with ETag header
2. Subsequent requests: Browser sends If-None-Match header
3. If unchanged: Returns 304 Not Modified (no data transfer)
4. If changed: Returns new PDF with updated ETag

Cache duration: 1 hour (3600 seconds)

Security Example

Add authentication and authorization before streaming:

{
  "exec": {
    "steps": [
      {
        "name": "restrict",
        "module": "auth",
        "action": "restrict",
        "options": {
          "provider": "security"
        }
      },
      {
        "name": "verify_ownership",
        "module": "dbconnector",
        "action": "single",
        "options": {
          "connection": "db",
          "sql": {
            "query": "SELECT filepath FROM pdfs WHERE id = ? AND user_id = ?",
            "params": ["{{$_PARAM.id}}", "{{identity.id}}"]
          }
        }
      },
      {
        "name": "streamPDF",
        "module": "pdfstreamer",
        "action": "stream",
        "options": {
          "filepath": "{{verify_ownership.filepath}}"
        }
      }
    ]
  }
}

Path Resolution

The extension supports multiple path types:

1. Relative to project root:

   "filepath": "uploads/pdfs/document.pdf"
   // Resolves to: /your-project/uploads/pdfs/document.pdf

2. Absolute paths:

   "filepath": "/var/data/pdfs/document.pdf"
   // Uses the path as-is

Error Handling

Clear error messages for common issues:

• File not found: "PDF file not found: [path]"
• Missing filepath: "File path is required"
• Read error: "Error reading PDF file: [error]"

Troubleshooting

Extension Not Showing in Wappler

Solution:

1. Verify the package was installed: check node_modules/wappler-pdfstreamer
2. Make sure Wappler is completely closed and restarted
3. Clear Wappler cache if needed

"Module not found" Error

Solution:

• Verify installation: npm list wappler-pdfstreamer
• Reinstall if needed: npm install wappler-pdfstreamer
• Restart Wappler completely

PDF Still Downloads Instead of Displaying

Solution:

1. Check the disposition parameter is set to "inline"
2. Verify browser supports inline PDF viewing
3. Check response headers in browser DevTools

Performance Tips

1. ✅ Enable caching for static PDFs
2. ✅ Use relative paths when possible
3. ✅ Add authentication early in the workflow
4. ✅ Consider CDN for frequently accessed PDFs

Advantages Over fs.download

| Feature | fs.download | pdfstreamer | |---------|-------------|-------------| | Inline display | ✅ | ✅ | | Automatic headers | ❌ | ✅ | | Caching support | ❌ | ✅ | | ETag support | ❌ | ✅ | | 304 responses | ❌ | ✅ | | Enhanced errors | ❌ | ✅ |

Requirements

• Node.js: >= 12.0.0
• Wappler: 5.x or higher

License

MIT License - see LICENSE.md for details

Author

Ben Pleysier

Support

For issues or questions:

• Check the troubleshooting section above
• Visit the Wappler Community Forum