download-file

Common errors

• Error: Cannot find module 'download-file'

  cause Attempting to use ES Modules `import` syntax (`import download from 'download-file'`) in a context where the package is only published as CommonJS.
  fix Use CommonJS `require` syntax: `const download = require('download-file')`.

• Error: ENOENT: no such file or directory, open './path/to/non-existent/directory/file.jpg'

  cause The target directory specified in the `options.directory` did not exist when the download attempted to write the file.
  fix Ensure the directory exists before initiating the download. Use `fs.mkdirSync(options.directory, { recursive: true });` or `fs.promises.mkdir(options.directory, { recursive: true });`.

• Error: connect ETIMEDOUT

  cause The network connection timed out, either due to a slow server, network issues, or the `timeout` option being set too low for a large file or remote server response.
  fix Increase the `timeout` option in milliseconds (e.g., `timeout: 60000` for 60 seconds) or check network connectivity and the availability of the remote server. The default timeout is 20000ms (20 seconds).

Warnings

• gotcha The package uses a callback-based API exclusively. It does not provide Promise or async/await support, which is common in modern Node.js development. This can lead to 'callback hell' for complex sequences of downloads.
  Fix: Wrap the `download` function in a Promise manually if modern async/await patterns are desired, e.g., `new Promise((resolve, reject) => download(url, options, err => err ? reject(err) : resolve()))`.
• gotcha The package does not automatically create the specified `directory` path. If the target directory does not exist, the download will fail with an `ENOENT` error. Developers must manually ensure the directory structure is in place.
  Fix: Before calling `download`, use `fs.mkdirSync(options.directory, { recursive: true })` or `fs.promises.mkdir` to create the full directory path.
• gotcha This package is at a very low version (0.1.5) and appears to be unmaintained. There haven't been updates for a significant period, which could mean it lacks bug fixes, security patches, or compatibility updates for newer Node.js versions or HTTP standards.
  Fix: For new projects or critical applications, consider more actively maintained alternatives like `node-fetch`, `axios`, or `got` which offer modern APIs, better error handling, and more features (e.g., progress tracking, retries, cancellation).
• gotcha The package provides basic timeout functionality but lacks advanced features like progress events, stream-based processing for large files, automatic retries on network failures, or integration with `AbortController` for cancellation.
  Fix: For these advanced requirements, consider using more robust HTTP clients or implementing these features manually around the basic download functionality, or again, opting for a more feature-rich library.

Install

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

Imports

• download
  wrong:

  import download from 'download-file'

  correct:

  const download = require('download-file')

  The package is CommonJS-only and does not officially support ES Modules imports. Use `require`.
• download (named)
  wrong:

  import { download } from 'download-file'

  correct:

  const { download } = require('download-file')

  Although it exports a single function, it is exported as the module.exports default, not as a named export. The `{ download }` destructuring pattern will not work correctly.

Quickstart

This quickstart demonstrates downloading two different files (an image and a video) to specific local directories. It includes necessary directory creation using `fs.mkdirSync` and basic error handling, showcasing the package's callback-based API and timeout option.

const download = require('download-file');
const fs = require('fs');
const path = require('path');

const imageUrl = "https://picsum.photos/id/237/800/600"; // A reliable public image URL
const videoUrl = "https://www.w3schools.com/html/mov_bbb.mp4"; // A reliable public video URL

// --- Example 1: Image download ---
const imageOptions = {
    directory: "./downloads/images/",
    filename: "random_image.jpg"
};

// Ensure the target directory exists before attempting to download
fs.mkdirSync(imageOptions.directory, { recursive: true });

console.log(`Attempting to download image from ${imageUrl} to ${path.join(imageOptions.directory, imageOptions.filename)}`);
download(imageUrl, imageOptions, function(err){
    if (err) {
        console.error("Image download failed:", err);
        return;
    }
    console.log("Image 'random_image.jpg' downloaded successfully!");
});

// --- Example 2: Video download with a custom timeout ---
const videoOptions = {
    directory: "./downloads/videos/",
    filename: "big_buck_bunny.mp4",
    timeout: 30000 // 30 seconds, increased for potentially larger files
};

fs.mkdirSync(videoOptions.directory, { recursive: true });

console.log(`Attempting to download video from ${videoUrl} to ${path.join(videoOptions.directory, videoOptions.filename)}`);
download(videoUrl, videoOptions, function(err){
    if (err) {
        console.error("Video download failed:", err);
        return;
    }
    console.log("Video 'big_buck_bunny.mp4' downloaded successfully!");
});