nest-sftp is a NestJS framework module that provides a wrapper around the `ssh2-sftp-client` library, enabling SFTP client capabilities within a NestJS application. It integrates SFTP connection management directly into the NestJS dependency injection system, allowing for easy configuration and use of SFTP operations. The current stable version is 3.1.0, which includes support for NestJS 11. While minor releases and bug fixes occur periodically, major version updates are less frequent, often coinciding with significant changes or new NestJS version support. Key differentiators include its seamless integration with Nest's module system, supporting both synchronous (`forRoot`) and asynchronous (`forRootAsync`) configuration patterns, and the ability to inject a configured `SftpClientService` directly into other services for file transfer operations.
npm install nest-sftpVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates registering the SftpModule asynchronously, injecting SftpClientService, and performing basic SFTP operations like listing, uploading, downloading, and deleting files.
Review the official README for the latest configuration patterns, especially `forRootAsync` usage. Re-evaluate `SftpModule` imports and `SftpClientService` injection.
Migrate `SftpModule` configuration to `forRootAsync` pattern, especially if you need to inject other services (like `ConfigService`) to retrieve SFTP connection details.
When providing passwords, ensure that `\` is escaped to `\\`. Test passwords containing `!` or `(` thoroughly, as they might interact poorly with shell environments or configuration parsing, even if the library itself handles them.
For production environments, ensure the `debug` property is either omitted or points to a custom logging function that sanitizes or redacts sensitive information before outputting to logs.
Always test new `nest-sftp` versions against your specific NestJS version. Consult the `nest-sftp` changelog for explicit NestJS version support updates, such as the v3.1.0 update for NestJS 11.
Ensure `SftpModule.forRoot()` or `SftpModule.forRootAsync()` is properly imported in your `AppModule` or a shared module that is imported by the consuming module. Remember that `SftpModule` is often made global as per the documentation.
Verify `host` and `port` in your `ConnectConfig`. Check network connectivity and firewall rules between your application and the SFTP server. Increase the `timeout` option in `ConnectConfig` if the server is known to be slow.
Double-check the `username` and `password` for accuracy, including any special character escaping requirements. Ensure the user has the necessary permissions on the SFTP server.
Update `nest-sftp` to the latest version (v2.x or later added `forRootAsync`). If on a recent version, check your `tsconfig.json` for module resolution settings and ensure proper project setup.