jsftp: A Node.js FTP Client

2.1.3 · active · verified Tue Apr 21

jsftp is a client library for the File Transfer Protocol (FTP) specifically designed for Node.js environments. It emphasizes correctness, clarity, and conciseness, providing both low-level access to raw FTP commands and higher-level convenience methods for common operations like file transfers and directory listings. The current stable version is 2.1.3, released on an as-needed basis for bug fixes and feature enhancements, with previous major versions dropping older Node.js compatibility and updating APIs. A key differentiator is its integration with Node.js streaming APIs, allowing for efficient handling of file data. It exposes the underlying FTP protocol responses with `code` and `text` properties, giving developers granular control and insight into server interactions.

Common errors

```
ECONNREFUSED on two consecutive PASV operations
```
cause Attempting to perform two passive FTP operations (e.g., file transfers or directory listings) concurrently before `jsftp` version 1.3.7.

fix Upgrade to `jsftp` v1.3.7 or higher, which will instead generate an error for this scenario. Prefer sequentializing passive operations or ensure robust error handling for concurrent requests.
```
LIST command or Ftp.ls callback not fired for non-existent path
```
cause Using the `LIST` command or the `Ftp.ls` convenience method on an invalid or non-existent remote path when using `jsftp` versions older than 1.3.4.

fix Update `jsftp` to version 1.3.4 or newer to ensure that errors for non-existent paths are correctly passed to the callback.
```
File transfer with Ftp.get proceeds despite passive socket error
```
cause A bug in `jsftp` versions prior to 1.3.1 where the `get` method would not properly halt file retrieval even if there was a preceding error in establishing the passive data connection.

fix Upgrade `jsftp` to version 1.3.1 or a later version to fix this behavior, ensuring `get` respects passive socket errors.

Warnings

breaking The `raw` API underwent significant changes in version 2.0.0. Code relying on the exact structure or behavior of `raw` command responses from prior versions may break.
Fix: Review the documentation for `jsftp` v2.0.0 to understand the new `raw` API and adapt your code accordingly. Responses now consistently return an object with `code` and `text` properties.
breaking Compatibility for Node.js versions older than 0.8 was dropped in version 1.5.0. Running `jsftp` on very old Node.js environments will lead to errors.
Fix: Ensure your Node.js environment is at least version 6.x or newer, as specified in the package's engine requirements (`engines.node: ">=6"`).
gotcha Prior to version 1.3.7, attempting two simultaneous passive (PASV) requests could result in an `ECONNREFUSED` error and potentially crash the application due to improper error handling.
Fix: Upgrade `jsftp` to version 1.3.7 or newer. This version introduces proper error generation for simultaneous PASV requests, allowing your application to handle the error gracefully instead of crashing. It is still recommended to sequentialize passive operations where possible.
gotcha In versions prior to 1.3.4, issuing a `LIST` command (directly or via `Ftp.ls`) for a non-existent file or directory would not reliably catch the error or notify the `ls` callback, leading to unhandled promises or stalled operations.
Fix: Update `jsftp` to version 1.3.4 or higher to ensure that `LIST` commands for invalid paths correctly propagate errors to the callback.
gotcha Before version 1.3.1, the `get` method could sometimes attempt to retrieve a file even if there was an error obtaining the passive socket, leading to unexpected behavior or resource leaks.
Fix: Upgrade `jsftp` to version 1.3.1 or newer. This version fixed the `get` method to correctly abort file retrieval when passive socket errors occur.

Install

npm install jsftp npm
yarn add jsftp yarn
pnpm add jsftp pnpm

Imports

jsftp (constructor)
wrong:
```
import JsFtp from 'jsftp';
```
correct:
```
const JsFtp = require('jsftp');
```
This library is primarily designed for CommonJS. While Node.js supports ESM, the primary usage pattern demonstrated is using `require()` to import the constructor function.
JsFtp instance
wrong:
```
const ftp = jsftp({ host: '...' });
```
correct:
```
const ftp = new JsFtp({ host: '...' });
```
The imported `jsftp` is a constructor function and must be called with `new` to create an FTP client instance.
raw command method
wrong:
```
ftp.quit((err, data) => { /* ... */ });
```
correct:
```
ftp.raw('quit', (err, data) => { /* ... */ });
```
All native FTP commands are accessed via the `ftp.raw(command, [...args], callback)` method. There are convenience methods for common operations, but direct protocol commands use `raw`.

Quickstart

This code demonstrates how to establish a connection to an FTP server, retrieve its system information using a raw command, and then gracefully disconnect. It uses environment variables for host, port, user, and password for secure configuration.

const JsFtp = require('jsftp');

const Ftp = new JsFtp({
  host: process.env.FTP_HOST ?? 'localhost',
  port: parseInt(process.env.FTP_PORT ?? '21', 10),
  user: process.env.FTP_USER ?? 'anonymous',
  pass: process.env.FTP_PASS ?? '@anonymous'
});

Ftp.on('error', err => {
  console.error('FTP Client Error:', err);
  Ftp.destroy(); // Ensure the connection is closed on error
});

Ftp.raw('syst', (err, data) => {
  if (err) {
    return console.error('Failed to get system info:', err);
  }
  console.log('System Info:', data.text);

  Ftp.raw('quit', (err) => {
    if (err) {
      return console.error('Failed to quit:', err);
    }
    console.log('Successfully disconnected from FTP server.');
  });
});

view raw JSON →