@baconshot/deploy-sftp

A flexible Node.js package for deploying files to FTP or SFTP servers with support for both protocols, optional directory cleaning, and comprehensive error handling.

Features

• 🚀 Support for both FTP and SFTP protocols
• 🧹 Optional remote directory cleaning before upload
• 📁 Recursive directory upload
• ⚙️ Configurable via environment variables
• 📦 TypeScript support with full type definitions
• 🔒 Secure password authentication
• 🎯 CLI tool and Node.js module

Installation

npm install @baconshot/deploy-sftp

Usage

As a CLI Tool

Add to your package.json:

{
  "scripts": {
    "deploy:sftp": "npm run build && deploy-sftp"
  }
}

Set up a .env file in your project root:

FTP_PROTOCOL=sftp
FTP_HOST=your-server.com
FTP_PORT=22
FTP_USER=your-username
FTP_PASSWORD=your-password
FTP_REMOTE_DIR=/path/to/remote/dir/
FTP_LOCAL_DIR=dist
FTP_SECURE=false
FTP_CLEAN=false
FTP_CLEAN_SAFE_DEPTH=3

Environment variables:

| Variable | Required | Default | Description | | ---------------------- | -------- | ------------------------ | ----------------------------------------------------------------- | | FTP_PROTOCOL | No | sftp | Protocol: sftp or ftp | | FTP_HOST | Yes | - | Server hostname | | FTP_USER | Yes | - | Username | | FTP_PASSWORD | Yes | - | Password | | FTP_PORT | No | 22 (SFTP) / 21 (FTP) | Server port | | FTP_REMOTE_DIR | Yes | - | Remote directory path | | FTP_LOCAL_DIR | No | dist | Local directory to upload | | FTP_SECURE | No | false | Use FTPS only when FTP_PROTOCOL=ftp (ignored for sftp) | | FTP_CLEAN | No | false | Clean remote directory before upload (requires a safe path depth) | | FTP_CLEAN_SAFE_DEPTH | No | 3 | Minimum remote path segments required before cleaning is allowed |

Then run:

npm run deploy:sftp

FTP vs FTPS vs SFTP

If you are unsure which one to use, this is the quick version:

• SFTP: Uses SSH. This is usually the modern default and the safest first choice.
• FTP: Plain FTP (no encryption). Only use if your host specifically requires it.
• FTPS: FTP + TLS encryption. In this package, FTPS is enabled by setting FTP_PROTOCOL=ftp and FTP_SECURE=true.

Important: SFTP and FTPS are different protocols.

• SFTP runs over SSH (commonly port 22)
• FTPS runs over FTP with TLS (commonly port 21)

How to configure:

• SFTP (recommended): set FTP_PROTOCOL=sftp and keep FTP_SECURE=false (ignored for SFTP)
• FTP (unencrypted): set FTP_PROTOCOL=ftp and FTP_SECURE=false
• FTPS (encrypted FTP): set FTP_PROTOCOL=ftp and FTP_SECURE=true

As a Node.js Module

import { deploy } from "@baconshot/deploy-sftp";

const result = await deploy({
  protocol: "sftp", // or 'ftp'
  host: "your-server.com",
  user: "username",
  password: "password",
  remoteDir: "/path/to/remote/dir/",
  localDir: "dist",
  secure: false,
  cleanBeforeUpload: false,
  cleanSafeDepth: 3,
  verbose: true,
});

if (result.success) {
  console.log(`Uploaded ${result.uploadedFiles} files`);
} else {
  console.error(result.message);
}

Configuration Object

interface DeployConfig {
  protocol?: "ftp" | "sftp"; // Default: 'sftp'
  host: string; // Required
  user: string; // Required
  password: string; // Required
  port?: number; // Optional, defaults based on protocol
  remoteDir: string; // Required
  localDir?: string; // Default: 'dist'
  secure?: boolean; // Default: false
  cleanBeforeUpload?: boolean; // Default: false
  cleanSafeDepth?: number; // Default: 3
  verbose?: boolean; // Default: true
}

Security Notes

⚠️ Never commit .env files to version control. Add .env to your .gitignore.

When FTP_CLEAN=true, the package refuses to clean unsafe broad targets.

By default, the minimum required depth is 3 path segments. Set FTP_CLEAN_SAFE_DEPTH to override this.

• Allowed example: /utilities/todo-2023
• Rejected examples: /, /public, . and paths containing ..

This safety check helps avoid accidental deletion of top-level remote directories.

For CI/CD environments, inject environment variables securely through your platform's secret management.

Supported Node Versions

Node.js 18 or higher

License

MIT