{"id":11152,"library":"js-file-download","title":"Javascript Browser File Download","description":"The `js-file-download` package offers a focused JavaScript utility function to initiate browser-driven file downloads directly from client-side data. It enables applications to save JavaScript-generated content, such as dynamically created CSVs, JSON blobs, or any string data, into a local file on the user's system without requiring a server roundtrip. The current stable version, 0.4.12, includes recent fixes for specific browser compatibility issues, notably on Apple devices, indicating ongoing maintenance. Its release cadence appears to be driven by bug fixes and compatibility updates rather than feature additions. Key differentiators include its lightweight footprint, single-function API, and direct utility for client-side data persistence, making it an efficient choice for scenarios where data is already available in the browser and needs to be downloaded.","status":"active","version":"0.4.12","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/kennethjiang/js-file-download","tags":["javascript","file","react","download","typescript"],"install":[{"cmd":"npm install js-file-download","lang":"bash","label":"npm"},{"cmd":"yarn add js-file-download","lang":"bash","label":"yarn"},{"cmd":"pnpm add js-file-download","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exports a default function. Named import will result in 'TypeError: fileDownload is not a function'.","wrong":"import { fileDownload } from 'js-file-download';","symbol":"fileDownload","correct":"import fileDownload from 'js-file-download';"},{"note":"The README shows CommonJS `require` syntax, which correctly accesses the default export. Destructuring will fail.","wrong":"const { fileDownload } = require('js-file-download');","symbol":"fileDownload (CJS)","correct":"const fileDownload = require('js-file-download');"},{"note":"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.","wrong":"import type { fileDownload } from 'js-file-download';","symbol":"Type import","correct":"import fileDownload from 'js-file-download'; // Includes types"}],"quickstart":{"code":"import fileDownload from 'js-file-download';\n\n// Example 1: Download a simple text string\nconst textData = 'Hello, world!\\nThis is some client-generated text.';\nfileDownload(textData, 'hello.txt');\n\n// Example 2: Download JSON data\nconst jsonData = {\n  id: 1,\n  name: 'Product A',\n  description: 'A fantastic product generated on the client-side.',\n  timestamp: new Date().toISOString(),\n};\nconst jsonString = JSON.stringify(jsonData, null, 2);\nfileDownload(jsonString, 'data.json', 'application/json');\n\n// Example 3: Simulate downloading a CSV file with custom content type\nconst csvData = `Name,Age,City\\nAlice,30,New York\\nBob,24,London\\nCharlie,35,Paris`;\nfileDownload(csvData, 'report.csv', 'text/csv');\n\n// In a browser environment, these calls would trigger actual downloads.\n// For security and browser sandbox reasons, actual file saving does not happen in a Node.js console.\nconsole.log('File download attempts initiated. Check your browser downloads.');\n\n// Illustrative environment variable usage, not directly related to file-download functionality.\nconst API_KEY = process.env.MY_API_KEY ?? 'sk-example-key';\nif (API_KEY === 'sk-example-key') {\n  console.warn('Warning: MY_API_KEY environment variable is not set. Using a dummy key.');\n}","lang":"typescript","description":"Demonstrates how to download various types of client-side generated content (text, JSON, CSV) using the `fileDownload` function, including specifying MIME types."},"warnings":[{"fix":"Always use a default import: `import fileDownload from 'js-file-download';` for ESM, or `const fileDownload = require('js-file-download');` for CommonJS.","message":"The package exports a default function. Attempting to use named imports (`import { fileDownload } from 'js-file-download';`) will result in a runtime `TypeError`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure you are on the latest stable version of `js-file-download` to benefit from recent browser compatibility fixes.","message":"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.","severity":"gotcha","affected_versions":"<0.4.12"},{"fix":"For extremely large datasets, consider server-side file generation or streaming approaches if feasible, rather than purely client-side generation and download.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always provide the correct MIME type as the third argument (e.g., 'application/json', 'text/csv', 'image/png') to ensure proper browser handling.","message":"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).","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement from `import { fileDownload } from 'js-file-download';` to `import fileDownload from 'js-file-download';`.","cause":"Attempting to import `fileDownload` as a named export when it is a default export.","error":"TypeError: fileDownload is not a function"},{"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).","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.","error":"ReferenceError: fileDownload is not defined"},{"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;'`.","cause":"Encoding issues, often due to the browser defaulting to an incorrect character set or missing an explicit UTF-8 byte order mark (BOM).","error":"Downloaded file content appears garbled or with incorrect characters (e.g., mojibake for non-ASCII text)"}],"ecosystem":"npm"}