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-ftpVerified import paths — ran on the pinned version, not inferred.
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.
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.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.
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.
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 })`.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.
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.
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`.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.
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.
No dependency data recorded yet.