Registry / devops / gulp-jsforce-deploy

gulp-jsforce-deploy

JSON →
library1.1.2jsnpmunverified

A Gulp plugin for deploying Salesforce metadata packages using JSforce's Metadata API, eliminating the need for the Force.com Migration Tool (Ant/Java). Version 1.1.2 is the latest stable release. It handles zip packaging and deployment with configurable login URL, poll timeout, and API version. Differentiators include pure Node.js implementation, seamless integration with Gulp build pipelines, and no external Java dependencies.

devops
npm install gulp-jsforce-deploy
package ↗
INSTALL
IMPORT
SIG · GULP-JSFORCE-DEPLO
G
gulp-jsforce-deploy
devopsjavascriptv1.1.2
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

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

forceDeploy
✓ import forceDeploy from 'gulp-jsforce-deploy'
✗ const forceDeploy = require('gulp-jsforce-deploy')
ESM named default export; CommonJS require works but not recommended for new projects
default
✓ const forceDeploy = require('gulp-jsforce-deploy')
✗ const { forceDeploy } = require('gulp-jsforce-deploy')
Plugin exports a single function as default export; destructured import will be undefined

Shows complete Gulp task that zips a Salesforce metadata directory and deploys it using credentials from environment variables.

const gulp = require('gulp'); const zip = require('gulp-zip'); const forceDeploy = require('gulp-jsforce-deploy'); gulp.task('deploy', function() { return gulp.src('./pkg/**', { base: '.' }) .pipe(zip('pkg.zip')) .pipe(forceDeploy({ username: process.env.SF_USERNAME ?? '', password: process.env.SF_PASSWORD ?? '', loginUrl: process.env.SF_LOGIN_URL ?? 'https://login.salesforce.com', pollTimeout: 120 * 1000, pollInterval: 10 * 1000, version: '55.0' })); });
Debug
Known issues
gotchaThe plugin requires gulp-zip to be piped before forceDeploy; missing zip step will cause deployment failure.
fix
Always pipe .pipe(zip('pkg.zip')) before forceDeploy.
affects: all
gotchaThe plugin returns a stream; you must return the stream from the gulp task or call done() to avoid premature exit.
fix
Use return gulp.src(...).pipe(...).pipe(forceDeploy(...)) or use async/await with promise.
affects: all
deprecatedThe plugin uses an older metadata API version (33.0 default); newer API versions may have different metadata types.
fix
Explicitly set version to your Salesforce API version (e.g., '55.0').
affects: all
gotchaIf username/password are missing or environment variables are not set, the plugin will fail without clear error.
fix
Always check that SF_USERNAME and SF_PASSWORD are set before running.
affects: all
gotchaThe plugin uses JSforce's Metadata API deploy; it does not support destructive changes or retrieve.
fix
Use JSforce directly for advanced operations like destructive deployments.
affects: all
Errors
Common errors & fixes
Error: ENOENT: no such file or directory, open 'pkg.zip'
Missing gulp-zip step before forceDeploy; the plugin expects a zipped stream.
fix
Add .pipe(zip('pkg.zip')) before forceDeploy.
Error: Invalid login attempt. Make sure you are using a valid username and password.
Incorrect or missing Salesforce credentials.
fix
Provide valid username and password via environment variables or options.
Error: The requested metadata type is not supported in this organization
Metadata version mismatch between plugin default (33.0) and Salesforce org.
fix
Set version option to match your Salesforce API version.
Error: Cannot read property 'asyncResultId' of null
Deployment failed; zip might be malformed or package.xml invalid.
fix
Check package.xml and ensure zip structure is correct (base folder as root).
Upgrade
Version history
1.1.2latest on npm
Audit
Dependencies
gulprequiredPeer dependency; plugin is designed for Gulp task runner
gulp-ziprequiredRequired to zip the deployment package before deploying
jsforcerequiredUnderlying Salesforce API client library
Agent activity
6 hits · last 30 days
node
6
Resources
packagegulp-jsforce-deploy ↗
gulp-jsforce-deploy — npm install gulp-jsforce-deploy · libregistry