Quick Start

In this section, you will learn to build a simple Freshsales app using the following steps.

Step 1: Install NVM

Step 2: Install Node

Step 3: Install the CLI

Step 4: Create your First App

Step 5: Test your App

Step 6: Validate and Pack

Apps built on the Freshworks platform are compatible with the latest two versions of the following browsers.

  • Google Chrome
  • Firefox
  • Edge
  • Safari
  • Internet Explorer - Not supported

Install NVM

It is recommended to use Node Version Manager (NVM) to install Node.js as it enables you to install and work with multiple versions of Node easily.

Check if Node exists in your computer by running the following command: node --version and uninstall any existing Node version on your computer and remove all folders related to Node and NPM.

You can skip step 1 if you have already installed NVM.

  1. To install NVM:
    1. For Mac/Linux, refer to the steps given here.
    2. For Windows, click here to download and extract the installer from nvm-setup.zip listed under Assets.
  2. To verify the installed nvm version, run the following command. $ nvm --version
Install Node

To install Node.js, follow the given steps.

  1. To install Node using NVM, run the following command. $ nvm install 10.18

    Note: Support for Node 8.10.x has been deprecated.

  2. To verify the installed node version, type the following command. $ node --version

    Note: For Windows, if the node version is not displayed, you may need to enable nvm by running the command: nvm on

  3. To set the default node version with NVM, run the following command: $ nvm alias default 10.18
  4. For Windows, you need to install a few required tools and configurations by using the following command. $ npm install --global --production windows-build-tools For further reference, click here.
Install the CLI

You need to install the Freshworks CLI on your machine to build, test, and publish apps in Freshsales Marketplace.

1. Uninstall the previous CLI version by using the npm uninstall fdk -g command.
2. By installing the CLI, you agree to these Terms and Conditions.

  • To install the CLI, run the following command.
  • Copied Copy
    npm install https://dl.freshdev.io/cli/fdk.tgz -g
  • To verify the version, run the following command.
  • Copied Copy
    fdk version
Create your First App

In this section, you will learn to create a simple app to display the Freshsales logo and sample text on the Lead Details page.

Open the terminal window, navigate to an empty directory in which you want to create your app, and follow the given steps.

  1. At the prompt, type fdk create
  2. From the product list, select a product and press Enter.
  3. From the template list, select your_first_app and press Enter.

The following app files appear in the directory.

Directory/File Description
app/ This directory contains all the files (HTML, JS, CSS, images, library) required for the front-end component of your app. The JS files must follow the ES5 standard.
app/icon.svg This is the product icon file in the app directory created as part of the sample project. You can replace it with your own assets while building your app.
Note: The icon file should be of SVG type with a resolution of 64 x 64 pixels.
app/template.html This file contains the HTML required for the app’s UI which is rendered in an IFrame.
config/ This directory contains the installation parameters and OAuth configuration files.
config/iparams.json This file contains all the installation parameters which you will have to specify/set when you install the app. For more information on installation parameters and related APIs, see Installation Parameters.
manifest.json This file contains details about your app and its characteristics.
README.md This file contains any additional instructions or specifications which you might want to outline.

1. The iparam_test_data.json file has been deprecated. Before testing the app, navigate to http://localhost:10001/custom_configs and enter appropriate values for the configured installation parameters.
2. If you use React, Ember, Vue, or any other front-end framework, include the source files of your app in the src directory. This will ensure quick app reviews.

For a detailed walkthrough of the app, see Code Walkthrough.

Test your App
  • To test your app, use the latest version of Chrome.
  • Ensure that you sign up for a Freshsales account.
  1. From the command line, navigate to the directory that contains the app related files and run the following command. $ fdk run
  2. Log in to your Freshsales account.
  3. To the Freshsales account URL, append ?dev=true. Example URL: https://subdomain.freshsales.io/leads/1?dev=true
  4. To allow the Chrome browser to connect to the test server that runs on HTTP,
    1. On Chrome 79 and higher versions:
      1. Navigate to Settings -> Advanced -> Privacy and security -> Site settings -> Insecure content.
      2. In the Allow section, click Add and enter the Freshsales account URL. Example URL: https://subdomain.freshsales.io
    2. On Chrome 78 and lower versions:
      1. In the address bar, if a shield icon is displayed, click the icon. A warning message is displayed as the Support portal runs on HTTPS and the test server runs on HTTP.
      2. Click Load Unsafe Scripts to continue testing.
  5. On the Home page, from the left global sidebar, select the Leads tab and click any lead. The rendered app is displayed at the bottom of the page.
  6. Notes:
    1. Each component in the coverage summary should be at least 80% for apps to be submitted in Freshworks Marketplace. See Code coverage for more information.
    2. If you have any issues when testing your app, attach detailed logs of the output in your support ticket for quick resolution from the support team.
    3. Testing a full-page app locally is not supported. To test a full-page app, publish it as a custom app.

Validate and Pack

To check if the app is error-free and package it for submission, follow the given steps.

  1. To validate the code, run the following command. $ fdk validate [--app-dir DIR]

    Here, DIR is the relative or absolute path to the app directory. If there are errors in the code, corresponding violations are displayed. To auto-fix certain errors and display only those that need manual fixing, use the $fdk validate --fix command. Ensure to fix all violations before packing the app.

  2. To pack the app for submission, run the following command. $ fdk pack [--app-dir DIR] The command generates the dist/<app_directory>.zip file.
  3. To publish the app to the Freshworks Marketplace, navigate to the Freshsales developer portal and upload the packed file. For more information on the app submission process, see Types of Apps.