# fax-downloader

> ownload files from URLs with fax-downloader. This works for image downloads and any file that is hosted on a CDN.

Latest version **2.0.1** (published 2026-02-21) · ISC license · 0 weekly downloads

## Install

```sh
npm install fax-downloader
pnpm add fax-downloader
yarn add fax-downloader
bun add fax-downloader
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2026-02-21 |
| First published | 2022-03-01 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 9.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | FAXES |
| Maintainers | faxes |
| Keywords | download, file, cdn, download, get, file, get, url |

## Links

- npm: https://www.npmjs.com/package/fax-downloader
- Repository: https://github.com/FAXES/fax-downloader
- Homepage: https://github.com/FAXES/fax-downloader#readme
- Issues: https://github.com/FAXES/fax-downloader/issues
- npm.io page: https://npm.io/package/fax-downloader

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 2.0.1 (latest) — 2026-02-21
- 2.0.0 — 2026-02-21
- 1.0.8 — 2023-12-17
- 1.0.7 — 2023-09-18
- 1.0.6 — 2022-12-27
- 1.0.5 — 2022-10-13
- 1.0.4 — 2022-10-13
- 1.0.3 — 2022-10-09
- 1.0.2 — 2022-10-09
- 1.0.1 — 2022-03-01
- 1.0.0 — 2022-03-01

## README

# File Downloader

Download files from URLs and save them locally with a simple API.
Built using modern fetch(), so this package requires node version 18 and above.

✅ Stream downloads directly to disk
✅ Promise-based API
ℹ️ Optional request configuration
🐃 Buffer download support via `getSync()`
⚠️ Requires Node.js 18+ (native `fetch()` support)

## Installation

```
npm install file-downloader
```

## Functions

### `getBuffer(url, options?)`
Downloads a remote file and returns its data as a Buffer.

| Name      | Type     | Required | Description   |
| --------- | -------- | -------- | ------------- |
| `url`     | `string` | ✅        | File URL      |
| `options` | `object` | ❌        | Fetch options |

**Example Usage**
```js
const faxDl = require('fax-downloader');
(async () => {
    const result = await faxDl.getBuffer("https://example.com/file.json");
    if(result.data) {
        console.log(result.data.toString());
    }
})();
```

**Response Object**
```js
{
    status: number,
    data: Buffer,   // returned when successful
    error: any
}
```

### `getFile(url, dest, options?)` (deprecated)
Downloads a file from a URL and saves it to disk. This function always resolves (never rejects) to maintain compatibility with previous versions (1.x.x).

| Name      | Type     | Required | Description                                              |
| --------- | -------- | -------- | -------------------------------------------------------- |
| `url`     | `string` | ✅        | File URL to download                                     |
| `dest`    | `string` | ✅        | Destination path relative to the Node process entry file |
| `options` | `object` | ❌        | Fetch request options                                    |

**Example Usage**
```js
const faxDl = require('fax-downloader');

faxDl.getFile(
    "https://example.com/image.png",
    "/downloads/image.png"
    )
    .then((fileResult) => {
        /*
        fileResult = {
            dest: "/downloads/image.png",
            status: 200,
            error: undefined
        }
        */
        console.log(fileResult);
    });
```

**Response Object**
```js
{
    dest: string,     // destination path (on success)
    status: number,   // HTTP status code
    error: any        // error object or status code if failed
}
```

> ⚠️ Errors resolve instead of throwing to preserve legacy compatibility.

---

**Options**
Any standard Fetch API options may be used including but not limited to; headers, method, signal, timeouts.
https://developer.mozilla.org/en-US/docs/Web/API/fetch


**Path Behaviour (getFile)**
Files are saved relative to `path.dirname(require.main.filename)`.


**Error Handling**
This package intentionally does not reject Promises. This design is intended to allow applications to read the response and not throw errors. 

```js
{
    status: HTTP_CODE,
    error: ERROR_OBJECT
}
```

### Authors
Markdownconvert is created by [Weblutions & FAXES](https://weblutions.com).

<a href="https://discord.gg/faxes" target="_blank">
    <img alt="Discord Invite" src="https://api.weblutions.com/discord/invite/faxes/light">
</a>

---
_Source: https://npm.io/package/fax-downloader · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._