New Version of ForceJS: A JavaScript Library for using the Salesforce APIs in ECMAScript 6 Apps

ForceJS is a micro-library that makes it easy to work with the Salesforce REST APIs in client-side JavaScript applications. I started the project a couple of years ago focusing on three key requirements:

  • Lightweight with no dependencies
  • Include an implementation of the OAuth User Agent workflow
  • Abstract differences between browser-based and Cordova-based application development to allow you to run an app in the browser and on device without code or configuration changes

These characteristics are still core to ForceJS, but a lot of things have changed in the JavaScript world in the last 2 years. Modern JavaScript applications are now built with ECMAScript 6 (aka ECMAScript 2015) and beyond. The current version of modern frameworks (such as React, Angular 2, and Ionic 2) are also built on top of ECMAScript Next.

To seamlessly support modern application development workflows, and naturally integrate with modern frameworks, I pushed a new and rearchitected version of ForceJS built on top of ECMAScript 6. The new version has the following characteristics:

  • Modular architecture. Currently includes two modules: forcejs/oauth and forcejs/data
  • Loaded as ECMAScript 6 modules
        import OAuth from 'forcejs/oauth';
        import Service from 'forcejs/data';
        
  • Works naturally with modern JavaScript frameworks: React, Angular 2, Ionic 2, etc.
  • Uses ECMAScript 6 promises instead of callbacks
  • Supports singleton or named instances to accommodate apps that work with a single or multiple Salesforce instances

GitHub Repo

The new version of ForceJS is available in this GitHub repository

The original ECMAScript 5 version is available in the es5 branch of the repository

Quick Start

Follow the instructions below to set up a project and create a simple JavaScript (ECMAScript 6) application that shows a list of Salesforce contacts:

  1. Create a new directory for your project, navigate (cd) to that directory, and type the following command to initialize a project that uses the npm package manager (accept all the default values):
        npm init
        
  2. Type the following command to install forcejs:
        npm install forcejs --save-dev
        
  3. Type the following command to install the force-server development server:
        npm install force-server --save-dev
        
  4. Type the following command to install Webpack and Babel:
        npm install babel-core babel-loader babel-preset-es2015 webpack --save-dev
        
  5. Using your favorite editor, open package.json and modify the scripts section as follows:
        "scripts": {
            "webpack": "webpack",
            "start": "force-server"
        },
        
  6. In your project’s root directory, create a file named webpack.config.js:
        var path = require('path');
        var webpack = require('webpack');
    
        module.exports = {
            entry: './app.js',
            output: {
                filename: 'app.bundle.js'
            },
            module: {
                loaders: [
                    {
                        test: /\.js$/,
                        loader: 'babel-loader',
                        query: {
                            presets: ['es2015']
                        }
                    }
                ]
            },
            stats: {
                colors: true
            },
            devtool: 'source-map'
        };
        
  7. In your project’s root directory, create a file named index.html:
        <!DOCTYPE html>
        <html>
        <body>
            <h1>Forcejs Quick Start</h1>
            <ul id="contacts"></ul>
            <script src="app.bundle.js"></script>
        </body>
        </html>
        
  8. In your project’s root directory, create a file named app.js:
        import OAuth from 'forcejs/oauth';
        import Service from 'forcejs/data';
    
        let oauth = OAuth.createInstance();
        oauth.login()
            .then(oauthResult => {
                Service.createInstance(oauthResult);
                loadContacts();
            });
    
        let loadContacts = () => {
            let service = Service.getInstance();
            service.query('select id, Name from contact LIMIT 50')
                .then(response => {
                    let contacts = response.records;
                    let html = '';
                    contacts.forEach(contact => html = html + `<li>${contact.Name}</li>`);
                    document.getElementById("contacts").innerHTML = html;
            });
        }
        
  9. On the command line, type the following command to build your project:
        npm run webpack
        
  10. Type the following command to start the app in a browser:
        npm start
        

    Authenticate in the OAuth login window. You should now see a list of contacts.

    You can sign up for a free developer environment here if you don’t already have one.

Feedback

Since this is a new version, I appreciate your feedback on the developer experience. Pull Requests welcome as well.

css.php