Registry / http-networking / nest-sftp

nest-sftp

JSON →
library3.1.0jsnpmunverified

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-sftp
INSTALL
IMPORT
SIG · NEST-SFTP
N
nest-sftp
http-networkingjavascriptv3.1.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

SftpModule
✓ import { SftpModule } from 'nest-sftp';
✗ const SftpModule = require('nest-sftp');
This is the main module for registering SFTP capabilities in NestJS. Use `forRoot` or `forRootAsync`.
SftpClientService
✓ import { SftpClientService } from 'nest-sftp';
✗ import { SftpClientService } from 'nest-sftp/sftp-client.service';
This service is injected into your application's providers to perform SFTP operations. It's automatically exposed by SftpModule.
ConnectConfig
✓ import { ConnectConfig } from 'ssh2-sftp-client';
✗ import { ConnectConfig } from 'nest-sftp';
While nest-sftp uses `ssh2-sftp-client`, its `ConnectConfig` interface comes directly from the underlying library for type consistency.

This quickstart demonstrates registering the SftpModule asynchronously, injecting SftpClientService, and performing basic SFTP operations like listing, uploading, downloading, and deleting files.

import { Module, Injectable, Logger } from '@nestjs/common'; import { SftpModule, SftpClientService } from 'nest-sftp'; import { ConnectConfig } from 'ssh2-sftp-client'; @Injectable() class ConfigService { getSftpConnectionInfo(): ConnectConfig { // In a real app, fetch these from environment variables or a configuration store return { host: process.env.SFTP_HOST ?? 'sftp.example.com', port: parseInt(process.env.SFTP_PORT ?? '22', 10), username: process.env.SFTP_USERNAME ?? 'user', password: process.env.SFTP_PASSWORD ?? 'password', // Optional: debug logging debug: console.log }; } } @Injectable() export class AppService { private readonly logger = new Logger(AppService.name); constructor(private readonly sftpClient: SftpClientService) {} async runSftpExample(): Promise<void> { try { this.logger.log('Attempting to list SFTP directory...'); const list = await this.sftpClient.list('/remote/path'); this.logger.log(`Listed directory: ${JSON.stringify(list.map(f => f.name))}`); const remoteFile = `/remote/path/test-${Date.now()}.txt`; const localContent = 'Hello SFTP from NestJS!'; const buffer = Buffer.from(localContent); this.logger.log(`Uploading file to ${remoteFile}`); await this.sftpClient.upload(buffer, remoteFile); this.logger.log('File uploaded successfully.'); this.logger.log(`Downloading file from ${remoteFile}`); const downloadedBuffer = await this.sftpClient.download(remoteFile); this.logger.log(`Downloaded content: ${downloadedBuffer.toString()}`); this.logger.log(`Deleting file ${remoteFile}`); await this.sftpClient.delete(remoteFile); this.logger.log('File deleted successfully.'); } catch (error) { this.logger.error('SFTP operation failed:', error.message); } } } @Module({ imports: [ SftpModule.forRootAsync( { useFactory: (configService: ConfigService) => { return configService.getSftpConnectionInfo(); }, inject: [ConfigService], imports: [ConfigService], } ), ], controllers: [], providers: [ConfigService, AppService], exports: [ConfigService, AppService] }) export class AppModule { constructor(private readonly appService: AppService) { // Kick off the SFTP example when the app starts // This would typically be triggered by an endpoint or lifecycle hook in a real app this.appService.runSftpExample(); } }
Debug
Known issues
breakingVersion 3.0.0 introduced breaking changes due to potential updates in its underlying dependency `ssh2-sftp-client` or internal module structure, although the changelog does not explicitly detail them. Users upgrading from v2.x should review their module configuration and SFTP client usage.
fix
Review the official README for the latest configuration patterns, especially `forRootAsync` usage. Re-evaluate `SftpModule` imports and `SftpClientService` injection.
affects: >=3.0.0
breakingThe `SftpModule` configuration methods (`forRoot`, `forRootAsync`) might have changed signature or preferred usage across major versions. The documentation emphasizes `forRootAsync` which suggests that the synchronous `forRoot` might have limitations or be less recommended in newer versions.
fix
Migrate `SftpModule` configuration to `forRootAsync` pattern, especially if you need to inject other services (like `ConfigService`) to retrieve SFTP connection details.
affects: >=3.0.0
gotchaSpecial characters in SFTP passwords, specifically backslashes (`\`), exclamation marks (`!`), and opening parentheses (`(`), need careful handling. Backslashes usually require escaping (`\\`).
fix
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.
affects: >=1.0.0
gotchaThe `debug` option for `ConnectConfig` directly uses a `console.log` function. Exposing raw sensitive connection details in production logs via this can be a security risk.
fix
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.
affects: >=1.0.0
gotchaWhile `nest-sftp` supports a wide range of NestJS peer dependencies (7-11), ensure compatibility by testing thoroughly if you are on the edges of this range or using a pre-release NestJS version.
fix
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.
affects: >=1.0.0
Errors
Common errors & fixes
Nest can't resolve dependencies of the SftpClientService (?). Please make sure that the argument SftpClientService at index [0] is available in the SftpModule context.
The SftpModule was not imported or configured correctly, or `SftpClientService` is being injected outside a module that imports `SftpModule`.
fix
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.
Error: Timeout while waiting for handshake
The SFTP server did not respond within the configured timeout period, often due to incorrect host/port, network issues, or a firewall blocking the connection.
fix
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.
Error: Authentication failure. User: [username]
Incorrect username or password provided in the `ConnectConfig`.
fix
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.
TypeError: SftpModule.forRootAsync is not a function
You might be using an older version of `nest-sftp` that does not support `forRootAsync`, or there's a TypeScript compilation issue.
fix
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.
Upgrade
Version history
3.1.0latest on npm
Audit
Dependencies
@nestjs/commonrequiredPeer dependency for NestJS module integration.
@nestjs/corerequiredPeer dependency for NestJS module integration.
Agent activity
6 hits · last 30 days
node
6
Resources