download.js: Client-Side File Download

1.4.7 · active · verified Sun Apr 19

Download.js is a client-side JavaScript library, currently at version 1.4.7, designed to programmatically trigger file downloads within the user's browser without requiring server interaction. It provides a single `download()` function that can accept various data types, including URLs, plain strings, Blobs, Typed Arrays, and dataURLs, abstracting the complexities of browser-specific download mechanisms. The library aims to set the filename and MIME type via browser capabilities, behaving similarly to a server's `Content-Disposition` header. While the release cadence is infrequent, the library remains active, offering a lightweight solution for in-browser file generation and download. Its key differentiators lie in its broad data input flexibility and wide browser compatibility, albeit with notable limitations on older browsers and devices lacking local file system access or specific web APIs like `Blob` or `window.URL`.

Common errors

```
File not downloaded on mobile (e.g., iOS)
```
cause The device lacks a local filesystem or sufficient browser support to handle client-side downloads programmatically.

fix This is often a fundamental device limitation. The library cannot circumvent the absence of a file system. Inform users of this limitation.
```
Downloaded file has a generic name (e.g., 'download.bin', 'unknown')
```
cause The user's browser is an older version or a legacy device that does not support the `download` attribute on anchor tags, which is used to suggest a filename.

fix Update browser if possible, or accept that custom filenames may not be honored on very old systems. The content type should still be correct.
```
download() called with a Blob or TypedArray argument fails
```
cause The browser in use does not have full support for the Blob API.

fix Check the browser's compatibility for the Blob API. For environments lacking Blob support, you might need to convert data to a dataURL string as a fallback, although this has size limitations.

Warnings

gotcha Devices without a local filesystem (e.g., iPhone, iPad, Wii) cannot save files using this library.
Fix: Inform users about device limitations or provide alternative file handling mechanisms for incompatible platforms.
gotcha Older browsers or legacy devices that do not support the `a[download]` attribute will only be able to download a few hundred kilobytes of data, and may not honor the custom filename provided.
Fix: Be aware of these limitations for users on very old browsers. The library provides a best-effort approach.
gotcha Browser support for Blobs and TypedArrays is required to download these data types. Devices without Blob support will fail when attempting to download them.
Fix: Check browser compatibility for Blob API if using Blob or TypedArray inputs. Consider polyfills or fallback mechanisms for older browsers.
gotcha Callback mode for AJAX operations will not work correctly with vanilla XMLHttpRequest or when dealing with binary files, as it expects specific success callback arguments.
Fix: For AJAX downloads, use an explicit `XMLHttpRequest` with `responseType='blob'` and manually call `download(e.target.response, ...)` in the `onload` handler.
gotcha Android support for the built-in browser begins at version 4.2. Chrome 36+ and Firefox 20+ on Android 2.3+ generally work well. Older Android versions may have limited or no functionality.
Fix: Test thoroughly on target Android devices and browsers, especially for older OS versions.

Install

npm install downloadjs npm
yarn add downloadjs yarn
pnpm add downloadjs pnpm

Imports

download
wrong:
```
const { download } = require('downloadjs');
```
correct:
```
const download = require('downloadjs');
```
The CommonJS module exports the download function directly, not an object with named exports.
download
```
download(data, strFileName, strMimeType);
```
Available globally when the library is included via a <script> tag.

download

require(['path/to/downloadjs'], function(download) { download(data, strFileName, strMimeType); });

For use with Asynchronous Module Definition (AMD) loaders like RequireJS.

Quickstart

Demonstrates basic usage of the global `download` function to save various types of client-side generated files like text, HTML, and SVG.

if (typeof download === 'function') {
  console.log('download.js is available!');

  // Download a plain text file
  download('Hello, Checklist Day!', 'greeting.txt', 'text/plain');

  // Download an HTML file with bold text from a Blob
  const htmlContent = '<h1>Welcome!</h1><p>This is <b>bold</b> text.</p>';
  download(new Blob([htmlContent]), 'welcome.html', 'text/html');

  // Download a file from a data URL
  const dataUrl = 'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><circle cx="50" cy="50" r="40" fill="red" /></svg>';
  download(dataUrl, 'red-circle.svg', 'image/svg+xml');

  console.log('Check your downloads folder for greeting.txt, welcome.html, and red-circle.svg');
} else {
  console.error('download.js function not found. Ensure the script is loaded.');
}

view raw JSON →