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.

  • Sören G.

    Hello Christophe,

    thanks for this tutorial. I was able to follow all the steps until step 9 where I get the following error message during build. Thanks for your help on this.

    > forcejsdemo@1.0.0 webpack /Users/xxx/forceJsDemo
    > webpack

    (node:90242) DeprecationWarning: loaderUtils.parseQuery() received a non-string value which can be problematic, see https://github.com/webpack/loader-utils/issues/56
    parseQuery() will be replaced with getOptions() in the next major version of loader-utils.
    Hash: f23a18b275d83dbc8a15
    Version: webpack 2.2.1
    Time: 639ms
    Asset Size Chunks Chunk Names
    app.bundle.js 9.96 kB 0 [emitted] main
    app.bundle.js.map 15.6 kB 0 [emitted] main
    [0] ./~/forcejs/oauth/index.js 5.07 kB {0} [built]
    [1] (webpack)/buildin/module.js 521 bytes {0} [built]
    [2] ./app.js 886 bytes {0} [built]

    ERROR in ./app.js
    Module not found: Error: Can’t resolve ‘forcejs/data’ in ‘/Users/xxx/forceJsDemo’
    @ ./app.js 7:12-35

    npm ERR! Darwin 16.3.0
    npm ERR! argv “/usr/local/bin/node” “/usr/local/bin/npm” “run” “webpack”
    npm ERR! node v6.9.5
    npm ERR! npm v4.2.0
    npm ERR! code ELIFECYCLE
    npm ERR! errno 2
    npm ERR! forcejsdemo@1.0.0 webpack: `webpack`
    npm ERR! Exit status 2

    • Drew

      change line 2 of app.js to read:
      import Service from ‘forcejs/data-service’;
      the api of this package changed.

      has anyone gotten the oauth login window to appear when running `npm start` in the last step?

  • Aadhya Krishna

    Hey! I love your blog post. Its a very relevant and important topic and I think

    you’ve explained multiple aspects very well. Thanks for the information.

  • Oktay Seo

    Bindallı çarıkları ; her modelde olmayıp sadece bazı modeller için tasarlanıp genellikle kişinin isteğine göre kombin edilmektedir. Rahatını düşünen gelin adayları için düztaban olup ucunda tüm kıyafetle uyumlu bir ponpon ve üzerinde desenler vardır. Bindallı çarıklarının renkleri ise altın sarısı zemine kırmızı desenler veya kırmızı zemine altın sarısı desenler şeklinde hazırlanmaktadır.
    Bindallı kaftan modelleri için bağdat kaftan ile iletişime geçebilirsiniz.

    http://bagdatkaftan.com/

  • Oktay Seo

    Kaftan fiyatları işçiliğe ve işlemelere göre farklılık göstermektedir. Özellikle son zamanlarda bir çok kişi çoğunlukla kiralık kaftan fiyatları hakkında bilgi sahibi olmak istemektedir. Bunu nedeni ise bir gün giyildikten sonra daha çok anı olarak saklanmasıdır.

    http://bagdatkaftan.com/kaftan-fiyatlari/

  • Oktay Seo

    Kaftan modelleri Günümüzde kına gecelerinin dışında gece hayatı için kullanılan kaftan ceketler de oldukça iddialı parçalar olarak gözümüze çarpmakta. Özellikle şık takımları tamamlayan bu parça bütün moda takipçilerinin göz bebeğidir. Kaftan ceketlerin günlük hayatta kullanılır hale gelmesi gerek vücut hatlarına olan uyumuyla gerekse rahatlığıyla onları tercih edilir hale getiriyor.

    http://bagdatkaftan.com/kaftan-modelleri/

  • Mark de Valk

    Hello Christophe, Thanks for your great contribution.

    I am using forcejs in Ionic and use the request method in data-service to call a custom REST Api on Salesforce. I am using query parameters and a JSON body object. Now this is working fine for web (using XMLHttpRequest). But once running in IOS, the implementation for the Request method is using the cordova network plugin. When looking in the code I see at some point that a choice is made between query-parameters and body (obj.data || obj.params).
    Based on this it seems that it is using either params or body. The API does require both params and a body. Do you have any thoughts on this?

    Thanks,

    Mark

  • Panel çit konusunda uzman ekip tecrübesi ile kendinize özel, güzel alanlar yaratın.

    http://www.demirhan.com.tr

css.php