Skip to content

v14.0.0

Latest

Choose a tag to compare

@steelbrain steelbrain released this 16 Nov 10:58

node-ssh 14 needs Node.js 22 or newer. It adds timeouts and AbortSignal support for commands, atomic uploads and skipping unchanged files, and fixes crashes and confusing errors around connection failures, large output and SFTP. The full list is in CHANGELOG.md.

Breaking changes

  • Node.js 22 or newer is required.
  • exec and execCommand reject with the connection's error when the connection fails while a command runs. They used to resolve with code: null. #132
  • With cwd, the command no longer runs when cd fails, for example because the directory doesn't exist. The result has the cd error in stderr and a non-zero code. The command used to run in the remote user's home directory.

New

  • timeout, signal and killSignal options for exec and execCommand. When the timeout passes or the AbortSignal aborts, node-ssh asks the server to send killSignal (default TERM) to the command, closes its channel and rejects. #465
    await ssh.execCommand('./build.sh', { timeout: 5000 }) // rejects with an SSHError, code 'ETIMEDOUT'
  • noBuffer option for exec and execCommand: output goes only to onStdout and onStderr, for commands with large output. #474
  • atomic option for putFile, putFiles and putDirectory: each file is uploaded to a hidden temporary file and renamed into place once complete, so readers never see a partial file. #349
  • skipUnchanged option for putFile, putFiles and putDirectory: files whose remote copy has the same size and modification time are not uploaded again. #466
  • config.privateKey accepts a Buffer. #446
  • A cwd that starts with ~/ is relative to the remote user's home directory. #443
  • The README has new sections on interactive programs (vim, nano, interactive shells), answering prompts, and keyboard-interactive authentication.

Fixes

  • Output that the server splits in the middle of a multi-byte UTF-8 character (or a base64 group) is no longer corrupted. #487
  • Output too large to return as a string rejects with an SSHError (ERR_OUTPUT_TOO_LARGE) instead of crashing the process. #474
  • An onStdout, onStderr or onChannel callback that throws rejects that command and closes only its channel, instead of closing the connection. #257
  • An error on an idle connection, such as ECONNRESET or a keepalive timeout, no longer crashes the process. #132
  • dispose() waits up to 2 seconds for SFTP close replies, so a read stream disposed on end no longer fails with No response from server. #471
  • More than 10 operations at once on one connection no longer print MaxListenersExceededWarning.
  • isConnected() is false until the connection is ready and right after connect() fails. #459
  • Clearer errors for putFile onto a directory (#312) and for SFTP sessions that fail to start (#414, #440).
  • Requests no longer wait about 40 ms per round trip on Node.js 26 (TCP_NODELAY is set).

TypeScript and packaging

  • The declarations no longer need esModuleInterop or allowSyntheticDefaultImports. #444
  • ESM projects get ESM declarations (lib/index.d.mts), CommonJS projects get lib/index.d.ts.
  • import NodeSSH from 'node-ssh' is now a TypeScript error everywhere; it used to compile in CommonJS projects and crash at runtime. Use import { NodeSSH } from 'node-ssh'.
  • @types/ssh2 is an optional peer dependency (^1.11.2). TypeScript projects install it themselves.
  • The build output moved to lib/index.js, lib/index.mjs, lib/index.d.ts and lib/index.d.mts. Importing node-ssh works as before; deep imports of the old lib/cjs, lib/esm or lib/typings paths no longer resolve.
  • ssh2 is now ^1.17.0. is-stream and make-dir are no longer dependencies.