Wappler CSV Streamer Extension

Stream CSV files directly to the browser for download or display in your Wappler applications.

Features

• ✅ Stream CSV files for download
• ✅ Optional inline display mode
• ✅ Automatic content-type and caching headers
• ✅ Browser caching support with ETag
• ✅ 304 Not Modified responses for optimal performance
• ✅ Custom display filenames
• ✅ UTF-8 encoding support
• ✅ 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 "CSV Operations" group
4. You should see "Stream CSV" action

Quick Start

Basic Usage - Download CSV

In your Server Connect action:

{
  "name": "streamCSV",
  "module": "csvstreamer",
  "action": "stream",
  "options": {
    "filepath": "exports/data.csv",
    "disposition": "attachment"
  }
}

Custom Filename

{
  "name": "downloadCSV",
  "module": "csvstreamer",
  "action": "stream",
  "options": {
    "filepath": "exports/data.csv",
    "filename": "Customer Report 2025.csv",
    "disposition": "attachment"
  }
}

Display in Browser (Inline)

{
  "name": "viewCSV",
  "module": "csvstreamer",
  "action": "stream",
  "options": {
    "filepath": "exports/data.csv",
    "disposition": "inline"
  }
}

Parameters

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

Frontend Usage

Download Link

<!-- Direct download link -->
<a href="/api/[server-action]/export.csv" class="btn btn-primary">
  Download CSV
</a>

<!-- With dynamic filename -->
<a href="/api/export-data" download="report.csv" class="btn btn-success">
  Export Report
</a>

Programmatic Download

<button dmx-on:click="downloadCSV.load()">Export Data</button>

<!-- Server Connect component -->
<dmx-serverconnect 
  id="downloadCSV" 
  url="/api/export-data">
</dmx-serverconnect>

Response Headers

The extension automatically sets optimized headers:

Content-Type: text/csv; charset=utf-8
Content-Length: [file size]
Content-Disposition: attachment; filename="export.csv"
Cache-Control: public, max-age=3600
ETag: "[timestamp]-[size]"

Caching Behavior

When caching is enabled (default):

1. First request: Returns full CSV 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 CSV with updated ETag

Cache duration: 1 hour (3600 seconds)

Common Use Cases

Export Database Query Results

{
  "exec": {
    "steps": [
      {
        "name": "query_data",
        "module": "dbconnector",
        "action": "select",
        "options": {
          "connection": "db",
          "sql": {
            "query": "SELECT * FROM customers"
          }
        }
      },
      {
        "name": "create_csv",
        "module": "csvwriter",
        "action": "write",
        "options": {
          "data": "{{query_data}}",
          "filepath": "exports/customers.csv"
        }
      },
      {
        "name": "stream_csv",
        "module": "csvstreamer",
        "action": "stream",
        "options": {
          "filepath": "exports/customers.csv",
          "filename": "Customers Export.csv"
        }
      }
    ]
  }
}

Secure Download with Authentication

{
  "exec": {
    "steps": [
      {
        "name": "restrict",
        "module": "auth",
        "action": "restrict",
        "options": {
          "provider": "security"
        }
      },
      {
        "name": "verify_access",
        "module": "dbconnector",
        "action": "single",
        "options": {
          "connection": "db",
          "sql": {
            "query": "SELECT filepath FROM exports WHERE id = ? AND user_id = ?",
            "params": ["{{$_PARAM.id}}", "{{identity.id}}"]
          }
        }
      },
      {
        "name": "stream_csv",
        "module": "csvstreamer",
        "action": "stream",
        "options": {
          "filepath": "{{verify_access.filepath}}",
          "filename": "My Export.csv"
        }
      }
    ]
  }
}

Dynamic Filename with Date

{
  "name": "stream_csv",
  "module": "csvstreamer",
  "action": "stream",
  "options": {
    "filepath": "exports/daily-report.csv",
    "filename": "{{NOW.formatDate('yyyy-MM-dd')}}-report.csv"
  }
}

Path Resolution

The extension supports multiple path types:

1. Relative to project root:

   "filepath": "exports/data.csv"
   // Resolves to: /your-project/exports/data.csv

2. Absolute paths:

   "filepath": "/var/data/exports/data.csv"
   // Uses the path as-is

Error Handling

Clear error messages for common issues:

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

Troubleshooting

Extension Not Showing in Wappler

Solution:

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

"Module not found" Error

Solution:

• Verify installation: npm list @benpley/wappler-csvstreamer
• Reinstall if needed: npm install @benpley/wappler-csvstreamer
• Restart Wappler completely

CSV Not Downloading

Solution:

1. Check the disposition parameter is set to "attachment"
2. Verify file exists at specified path
3. Check response headers in browser DevTools

Character Encoding Issues

Solution:

• The extension uses UTF-8 encoding by default
• Ensure your CSV files are saved with UTF-8 encoding
• Special characters should display correctly in most modern applications

Performance Tips

1. ✅ Enable caching for static CSV files
2. ✅ Use relative paths when possible
3. ✅ Add authentication early in the workflow
4. ✅ Consider generating CSVs on-demand rather than pre-generating
5. ✅ Use compression for large CSV files

Advantages Over fs.download

| Feature | fs.download | csvstreamer | |---------|-------------|-------------| | Download support | ✅ | ✅ | | Automatic headers | ❌ | ✅ | | UTF-8 encoding | ❌ | ✅ | | 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

Related Extensions

• @benpley/wappler-pdfstreamer - Stream PDF files