Registry / http-networking / basic-ftp

basic-ftp

JSON →
library5.3.0jsnpmunverified

basic-ftp is a robust and actively maintained FTP/FTPS client library designed specifically for Node.js environments. Currently stable at version 5.3.0, it demonstrates a consistent release cadence with frequent patch and minor updates addressing bugs and security enhancements, as evidenced by recent 5.x releases. A key differentiator is its modern Promise-based API, leveraging `async/await` for asynchronous operations, alongside native TypeScript support for improved developer experience and type safety. The library provides comprehensive features including FTPS over TLS for secure connections, IPv6 support, and convenient methods for performing directory-level operations like uploading and downloading entire folders. It explicitly supports Passive Mode but does not support Active Mode. Users are strongly advised to prefer FTPS (FTP over TLS) for any security-sensitive transfers, or ideally, alternative protocols like HTTPS or SFTP, as plain FTP is an inherently insecure and older protocol. The library maintains a lean dependency tree, requiring only Node.js 10.0 or later.

npm install basic-ftp
INSTALL
IMPORT
SIG · BASIC-FTP
B
basic-ftp
http-networkingjavascriptv5.3.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
import { Client } from 'basic-ftp'
const { Client } = require('basic-ftp')
Use ESM `import` for modern Node.js module systems (type: 'module' in package.json) or bundlers. CommonJS `require` is also supported but `import` is preferred for TypeScript and newer setups.
Client (CommonJS)
const { Client } = require('basic-ftp')
import { Client } from 'basic-ftp'
Use CommonJS `require` for traditional Node.js scripts without ESM enabled. Mixing CommonJS and ESM in certain environments can lead to issues.

Demonstrates connecting to an FTPS server, logging in, retrieving a directory listing, uploading a local file, and then downloading it back as a copy. Includes verbose logging and error handling.

import { Client } from 'basic-ftp'; import fs from 'node:fs'; const FTP_HOST = process.env.FTP_HOST ?? 'myftpserver.com'; const FTP_USER = process.env.FTP_USER ?? 'very'; const FTP_PASSWORD = process.env.FTP_PASSWORD ?? 'password'; // Create a dummy README.md for the example fs.writeFileSync('README.md', '# Local README\n\nThis is a test file for basic-ftp example.'); async function runFtpExample() { const client = new Client(); client.ftp.verbose = true; // Enable verbose logging try { await client.access({ host: FTP_HOST, user: FTP_USER, password: FTP_PASSWORD, secure: true // Use FTPS over TLS }); console.log('Connected and logged in. Remote directory listing:'); console.log(await client.list()); const remoteFileName = 'README_FTP.md'; const localFileName = 'README.md'; const copiedFileName = 'README_COPY.md'; console.log(`Uploading ${localFileName} to ${remoteFileName}...`); await client.uploadFrom(localFileName, remoteFileName); console.log('Upload complete.'); console.log(`Downloading ${remoteFileName} to ${copiedFileName}...`); await client.downloadTo(copiedFileName, remoteFileName); console.log('Download complete.'); // Clean up local dummy file fs.unlinkSync(localFileName); fs.unlinkSync(copiedFileName); } catch (err) { console.error('FTP Operation failed:', err); } finally { if (!client.closed) { client.close(); console.log('FTP client closed.'); } } } runFtpExample();
Debug
Known issues
breakingVersion 5.3.0 introduced an upper bound on the total bytes of directory listing data to mitigate a security vulnerability (GHSA-rp42-5vxx-qpwr). Large listings might now be truncated by default. An option to increase this limit (`Client` constructor) was added concurrently.
fix
If experiencing truncated directory listings for legitimate reasons, you can increase the `directoryListingResponseLimit` option in the `Client` constructor. For example: `new Client(timeout, { directoryListingResponseLimit: 10 * 1024 * 1024 })` for 10MB.
affects: >=5.3.0
breakingVersions 5.2.1 and 5.2.2 addressed critical security advisories (GHSA-chqc-8p9q-pq6q, GHSA-6v7q-wjvx-w8wg) by rejecting control character injection attempts in paths and improving control character rejection, respectively. This might cause previously 'working' but insecure path manipulations to now fail.
fix
Ensure all paths and filenames passed to `basic-ftp` methods are properly sanitized and do not contain malicious or unexpected control characters. Always use valid, clean paths.
affects: >=5.2.1
gotchaFTP is an old and inherently insecure protocol. Users are strongly advised to use FTPS (FTP over TLS) by setting `secure: true` in the `client.access()` options, or to prefer alternative, more secure protocols like SFTP or HTTPS for data transfer, especially for sensitive information. Plain FTP does not provide any encryption.
fix
Always set `secure: true` in `client.access()` to enable FTPS. Re-evaluate if FTP is the appropriate protocol for your use case and consider SFTP or HTTPS if security is a primary concern.
affects: >=1.0.0
gotchaThe `allowSeparateTransferHost` option in the `Client` constructor defaults to `true` for backwards compatibility. This allows the server to instruct the client to use a different IP address for data transfers, which can be a security risk (FTP bounce attacks) or cause issues in NAT environments.
fix
Set `allowSeparateTransferHost: false` in the `Client` constructor to prevent the client from connecting to different IP addresses for data transfers. Example: `new Client(30000, { allowSeparateTransferHost: false })`.
affects: >=1.0.0
gotchabasic-ftp does not support Active Mode FTP. It exclusively operates in Passive Mode (and EPSV).
fix
Ensure that your FTP server is configured to support Passive Mode. If your environment strictly requires Active Mode, basic-ftp will not be a suitable client.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Client has been closed
Attempting to perform an operation (e.g., upload, list) on a `Client` instance after `client.close()` has been called or after a connection error/timeout has occurred. A client cannot be reused after being closed.
fix
If you need to reconnect or perform new operations, create a new `Client` instance. If an error or timeout occurs, `basic-ftp` automatically closes the client, and you must instantiate a new one to reconnect.
TypeError: (0 , basic_ftp__WEBPACK_IMPORTED_MODULE_0__.Client) is not a constructor
This error typically occurs in bundled environments (like Webpack, Rollup, Vite) or when mixing CommonJS `require` with ESM `import` syntax, where the bundler incorrectly handles the module import for `basic-ftp`.
fix
Ensure your project's `package.json` correctly defines `"type": "module"` for ESM, or use CommonJS `const { Client } = require('basic-ftp')` if not using ESM. Check your bundler configuration to correctly transpile or resolve module imports for `basic-ftp`.
Error: 530 Login authentication failed
The username or password provided in the `client.access()` method is incorrect, or the user lacks the necessary permissions on the FTP server.
fix
Double-check your `host`, `user`, and `password` credentials. Verify them against the FTP server's configuration or by attempting to log in with another client. Ensure the user has appropriate directory access.
Error: connect ECONNREFUSED <IP_ADDRESS>:<PORT>
The client failed to establish a TCP connection to the specified FTP host and port. This could be due to an incorrect host/port, the server being offline, a firewall blocking the connection, or network issues.
fix
Verify the `host` and `port` (default 21 for FTP, 990 for implicit FTPS) in your `client.access()` options. Check if the FTP server is running and accessible from your network. Inspect any firewalls (local or network) that might be blocking the connection.
Upgrade
Version history
5.3.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
38 hits · last 30 days
node
36
OpenAI (training)
1
Resources
basic-ftp — npm install basic-ftp · libregistry