Javascript Browser File Download

Common errors

• TypeError: fileDownload is not a function

  cause Attempting to import `fileDownload` as a named export when it is a default export.
  fix Change your import statement from `import { fileDownload } from 'js-file-download';` to `import fileDownload from 'js-file-download';`.

• ReferenceError: fileDownload is not defined

  cause This usually happens when mixing CommonJS (`require`) and ES Module (`import`) syntax without proper transpilation, or if the module isn't correctly resolved in the environment.
  fix Ensure your environment (Node.js, bundler like Webpack/Rollup) is configured to handle both module types, or stick to the appropriate syntax for your module system (e.g., `const fileDownload = require('js-file-download');` in CJS files).

• Downloaded file content appears garbled or with incorrect characters (e.g., mojibake for non-ASCII text)

  cause Encoding issues, often due to the browser defaulting to an incorrect character set or missing an explicit UTF-8 byte order mark (BOM).
  fix Ensure your content is UTF-8 encoded. For text files, you might need to prepend a UTF-8 BOM if issues persist, or explicitly set the charset in the MIME type, e.g., `'text/csv;charset=utf-8;'`.

Warnings

• gotcha The package exports a default function. Attempting to use named imports (`import { fileDownload } from 'js-file-download';`) will result in a runtime `TypeError`.
  Fix: Always use a default import: `import fileDownload from 'js-file-download';` for ESM, or `const fileDownload = require('js-file-download');` for CommonJS.
• gotcha While the package aims for broad browser compatibility, historical issues, such as those fixed in v0.4.12 for Apple devices, highlight potential cross-browser quirks. Always test thoroughly in target browsers.
  Fix: Ensure you are on the latest stable version of `js-file-download` to benefit from recent browser compatibility fixes.
• gotcha Downloading very large files generated client-side can lead to browser memory exhaustion or performance issues, especially on less powerful devices. The content is held in memory before download.
  Fix: For extremely large datasets, consider server-side file generation or streaming approaches if feasible, rather than purely client-side generation and download.
• gotcha Incorrectly specifying the MIME type (the third argument) or omitting it for non-textual content can lead to browsers handling the downloaded file incorrectly (e.g., displaying binary data as text).
  Fix: Always provide the correct MIME type as the third argument (e.g., 'application/json', 'text/csv', 'image/png') to ensure proper browser handling.

Install

• npm install js-file-download npm
• yarn add js-file-download yarn
• pnpm add js-file-download pnpm

Imports

• fileDownload
  wrong:

  import { fileDownload } from 'js-file-download';

  correct:

  import fileDownload from 'js-file-download';

  The package exports a default function. Named import will result in 'TypeError: fileDownload is not a function'.
• fileDownload (CJS)
  wrong:

  const { fileDownload } = require('js-file-download');

  correct:

  const fileDownload = require('js-file-download');

  The README shows CommonJS `require` syntax, which correctly accesses the default export. Destructuring will fail.
• Type import
  wrong:

  import type { fileDownload } from 'js-file-download';

  correct:

  import fileDownload from 'js-file-download'; // Includes types

  The package ships TypeScript types. The default import statement handles both the function and its type. Attempting to import types with a named import for a default export is incorrect.

Quickstart

Demonstrates how to download various types of client-side generated content (text, JSON, CSV) using the `fileDownload` function, including specifying MIME types.

import fileDownload from 'js-file-download';

// Example 1: Download a simple text string
const textData = 'Hello, world!\nThis is some client-generated text.';
fileDownload(textData, 'hello.txt');

// Example 2: Download JSON data
const jsonData = {
  id: 1,
  name: 'Product A',
  description: 'A fantastic product generated on the client-side.',
  timestamp: new Date().toISOString(),
};
const jsonString = JSON.stringify(jsonData, null, 2);
fileDownload(jsonString, 'data.json', 'application/json');

// Example 3: Simulate downloading a CSV file with custom content type
const csvData = `Name,Age,City\nAlice,30,New York\nBob,24,London\nCharlie,35,Paris`;
fileDownload(csvData, 'report.csv', 'text/csv');

// In a browser environment, these calls would trigger actual downloads.
// For security and browser sandbox reasons, actual file saving does not happen in a Node.js console.
console.log('File download attempts initiated. Check your browser downloads.');

// Illustrative environment variable usage, not directly related to file-download functionality.
const API_KEY = process.env.MY_API_KEY ?? 'sk-example-key';
if (API_KEY === 'sk-example-key') {
  console.warn('Warning: MY_API_KEY environment variable is not set. Using a dummy key.');
}