gulp-force-developer
v0.1.16
Published
A gulp library for salesforce and force.com development
Downloads
77
Maintainers
Readme
gulp-force-developer
A gulp library for salesforce and force.com development. Designed to help force.com developers to work using the benefits of gulp and a folder structure when developing.
See: (https://github.com/jkentjnr/sfdc-gulp-travisci-boilerplate) for a boilplate solution.
npm install gulp-force-developer --save-dev
Once the plugin has been installed, it may be enabled inside your Gulpfile with this line of JavaScript:
var gulp = require('gulp'),
gutil = require('gulp-util');
forceDeveloper = require('./gulp-force-developer').registerForGulp(gulp, gutil);
Overview
Using gulp and the gulp-force-developer
tasks, developers for salesforce & force.com can:
- Manage their projects / packages in any folder structure they like.
- Integrate the full suite of gulp tasks into their deployment process.
- Ensure only new & modified code is published as part of each deployment / build. This enables a developer to code using any IDE, pushing changes via gulp.
To use gulp-force-developer
as quickly as possible, we recommend starting with the gulpfile.js
in examples.
Folder Structures
Traditional Folder Structure
Traditionally, when a developer is developing for salesforce / force.com, they are constrained by the mandated package structure. This structure is extremely limiting and, as the size of projects / packages grow, raplidly becomes unwieldy.
package.xml
== classes
-- PaymentController.cls
-- PaymentController.cls-meta.xml
-- UserManagement.cls
-- UserManagement.cls-meta.xml
== pages
-- Payment.page
-- Payment.page-meta.xml
-- UserManagement.page
-- UserManagement.page-meta.xml
== objects
-- Payment__c.object
gulp-force-developer Folder Structure
Using gulp-force-developer
, a developer can adopt a fully dynamic file structure that operates independent of the prescribed salesforce package structure. The below example is a snippet from a developer managing their package in structure with little constraints, appropriate for their project.
== .metadata
-- Payment.page-meta.xml
-- PaymentController.cls-meta.xml
-- UserManagement.page-meta.xml
-- UserManagementController.cls-meta.xml
== Admin
== Users
-- UserManagementController.cls
-- UserManagement.page
== Payments
-- PaymentController.cls
-- Payment.page
-- Payment__c.object
Gulp Tasks
To register the gulp tasks, you must use:
require('gulp-force-developer').registerForGulp(gulp, gutil);
force-package-config
Loads the options from the package.json
force-reset
Deletes the file used to track changes between force-commit
calls
force-package
Packages files that have changed since the previous force-commit
call
force-package-all
Packages all files
force-zip
Generates the output from the force-package
and force-package-all
calls as a zip, ready for deployment
force-commit
Updates the track changes file to refect the current state
force-mock-resources
Mocks resources from the package.json file. This is required when completing checkOnly tests that have Visualforce pages bound to resources.
Usage
To change your configuration, you may alter your project's package.json file.
{
"name": "salesforce project",
"version": "1.0.0",
"description": "",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "",
"license": "MIT",
"forceDeveloperConfig": {
"projectBaseDirectory": "src"
}
}
Or you may modify the options from within your gulpfile.
var gulp = require('gulp'),
gutil = require('gulp-util'),
forceDeveloper = require('gulp-force-developer').registerForGulp(gulp, gutil);
forceDeveloper.options.projectBaseDirectory = 'src';
In your project's gulpfile, register the tasks with gulp and extend as appropriate.
var salesforcePackageFile = './.package/package.zip',
username = '[email protected]',
password ='password',
token = 'Qr1ScFquCn1uT0YO6ywUj5je';
// ----------------------------------------------------------------
var gulp = require('gulp'),
gutil = require('gulp-util'),
forceDeploy = require('gulp-jsforce-deploy');
forceDeveloper = require('gulp-force-developer').registerForGulp(gulp, gutil);
// ----------------------------------------------------------------
// REGISTER GULP TASKS
gulp.task('deploy', function(done) {
return gulp.src(salesforcePackageFile)
.pipe(forceDeploy({
username: username,
password: password + token,
pollInterval: 5*1000
//, loginUrl: 'https://test.salesforce.com'
//, pollTimeout: 120*1000
//, version: '33.0'
}));
});
gulp.task('default', gulp.series(
'force-package-config',
'force-package',
'force-zip',
'deploy',
'force-commit'
));
Options
options.fileChangeHashFile
Type: String
Default value: '.force-developer.filehash.json'
Persists the file hashes to determine modified and new files.
options.forcePackageContinueSilent
Type: Boolean
Default value: false
By default force-package
ends the gulp sequence with an error when no new or modified code is available for deployment. When forcePackageContinueSilent
is true
it causes force-package
to continue with the subsequent gulp tasks. This behavior modification can be useful in complex deployment scenarios where multiple projects are merged together into one deployment.
options.metadataSourceDirectory
Type: String
Default value: 'app-metadata'
The folder used to store all '-meta.xml'
files for the project. A corresponding file is required for all pages, components, trigger and classes. If the projectBaseDirectory
isn't altered, the default location is ./project/app-metadata
.
options.projectBaseDirectory
Type: String
Default value: 'project'
Used to determine the root of the project folder.
options.outputDirectory
Type: String
Default value: '.package'
The folder used when the files are copied from the project folder into a salesforce package-compliant folder structure.
options.outputPackageZip
Type: String
Default value: './.package/package.zip'
The location where the zipped package is to be stored.
options.apiVersion
Type: Integer
Default value: 34
The api version to be used by the library. Used when creating on-demand meta-xml files.
options.mockResources
Type: Array (String)
Default value: []
A list of resource names required to be mocked so a test deployment can be completed successfully.
Contributing
All contributions welcome!
Release History
- 0.1.16
- Added Lightning / Aura definition bundle support
- 0.1.15
- Added support for modifying options from gulpfile
- 0.1.10
- Added resource mocking support
- 0.1.3
- Documentation updates.
- 0.1.0
- Inital release.