In this post, we are going to take a look at how we can build Freshworks Marketplace apps using popular JavaScript frameworks like React and Vue.
The official CLI tool provided by the App Development Platform of Freshworks has built-in scaffolding capabilities for building Marketplace apps using frameworks like React and Vue. At present only these two popular frameworks are being supported, I hope more frameworks will be supported by the CLI in the near future.
Freshworks CLI
The Freshworks CLI is a command-line tool which can be installed using the Node package manager npm. Of course, you need to have Node.js installed in your machine before installing the Freshworks CLI. You can find more information about the pre-requisites for installing the CLI here
npm install https://dl.freshdev.io/cli/fdk.tgz -g
You can verify the CLI installation by running following command:
fdk version
You should get something like the installed version of your fdk cli and also about any new versions that have been released so that you can upgrade.
The library exposes an executable called fdk using which you can bootstrap Marketplace apps. fdk also comes with pre-built templates for various frameworks and libraries for building the apps without having to set up the project boilerplates from scratch.
Templates
The fdk can take inputs on which type of boilerplate the Marketplace app is going to use. This is provided through the --template option which can be passed to the fdk create command.
If the --template option is not provided with the create command, you are prompted to select a template. The most common and recommended template for first-time users will be the your_first_app template.
At present there are about 7-8 templates available to choose from, if you are building the app for the Freshdesk product. Each and every product supports various kinds of templates best suited for the typical use cases supported by the respective products. Try choosing a different product in the first prompt (the product prompt) and you will be presented with a different set of templates.
Let's have a brief information about some of the most widely used templates.
your_first_app
This is the basic template which just displays the contact information for your app in the Ticket Details page sidebar. If you are just starting with the fdk or don't know what type of template to use, this is the recommended template for beginners, to get a grip on the components of a Marketplace app.
your_first_serverless_app
If you want to build Serverless apps for the Marketplace, this is the starter template you should be using. With this template, you can build apps which cater to various use cases like custom automations, data synchronization, alerts and notifications.
sample_crm_app
This template will show you how to build apps that use the Customer data from the CRM product of Freshworks called Freshsales. This sample app will showcase the various API and interfaces you can use to interface with the CRM product. If you are not familiar with these API or if you are just starting to build an app using the CRM capabilities, this is the starter template you should be using.
advanced_iparams_app
This is another sample app template which has some placeholder configuration for the Installation Parameters used in a Marketplace app.
Installation Parameters also known as iparams in the Marketplace parlance are used to configure the app installation. These parameters help you to fine-tune the installation process by dynamically configuring the application parameters before installing the app inside the respective products.
your_first_react_app
This is the sample template for bootstrapping the apps using React.js as the primary tool for building the front-end of the app. I will show you how to use this template in the sections below.
your_first_vue_app
This is the sample template for bootstrapping the apps using the 2.x versions of Vue.js as the primary tool for building the front-end of the app.
your_first_vue3_app
This is the sample template for bootstrapping the apps using the latest version of Vue.js as the primary tool for building the front-end of the app.
React
For creating React apps with fdk you have to use the template your_first_react_app like below:
fdk create --app-dir my-react-mkp-app --products freshdesk --template your_first_react_app
This is how the generated folder structure will look like:
Let's take a look inside the App.js component for what is happening inside the React app. First the app is trying to inject the Fresh Client script into the head of the document through the useEffect hook of React in the component. Then after the script is successfully injected then it is rendering the HelloUser component by passing the client instance returned by the app.initialized promise. Since every Marketplace app is rendered inside an IFrame, all the communication between the app and parent page occurs through this client object.
Fresh Client
You might be wondering what is the significance of injecting the Fresh Client script in the component. Because it is the script that exposes the global client object in your apps to make HTTP requests and get data from 3rd party services via the request interface.
The client object also has the interface method through which you can obtain information among different instances your apps. Your apps can have multiple instances since they can be present in multiple locations on the same page. You can manipulate your app instances, communicate with different instances and get the context information of various instances using the instance method.
As soon as you inject the Fresh Client script, it will globally expose the sdk object which in our case the Fresh Client (client) object. In the initialization phase of the client object, the script will try to initialize services, dynamically add the stylesheets of the product and the tracking scripts, and so on.
So the Fresh Client script is an integral part of your app, it is your job to ensure that you have the client object readily available to your framework by having it injected in the beginning even before you do anything else in your code.
import React, { useState, useEffect } from 'react';
import './App.css';
import HelloUser from './components/HelloUser'
const App = () => {
const [loaded, setLoaded] = useState(false);
const [child, setChild] = useState(<h3>App is loading</h3>)
useEffect(() => {
const script = document.createElement('script');
script.src = 'https://static.freshdev.io/fdk/2.0/assets/fresh_client.js';
script.addEventListener('load', () => setLoaded(true));
script.defer = true;
document.head.appendChild(script);
}, []);
useEffect(() => {
if (!loaded) return
app.initialized().then((client) => {
setChild((<HelloUser client={client} />))
})
}, [loaded])
return (
<div>
{child}
</div>
)
}
export default App;
And inside the HelloUser component, we use this client instance to fetch the contact details of the current support agent and display the agent's name in the component UI.
const HelloUser = (props) => {
const [name, setName] = useState('')
props.client.data.get('contact').then((data) => {
setName(data.contact.name)
})
return (
<div>
<img src={icon} className="App-logo" alt="logo" />
<img src={reactLogo} className="App-logo" alt="logo" />
<h3>Hi {name},</h3>
<p>Welcome to your first react app in Freshdesk</p>
</div>
)
}
Vue
You can build Marektplace apps using Vue.js by using the templates your_first_vue_app and your_first_vue3_app for the 2.x and 3.x versions of Vue.js respectively.
For Vue 2.x
fdk create --app-dir my-vue-mkp-app --products freshdesk --template your_first_vue_app
For Vue 3
fdk create --app-dir my-vue3-mkp-app --products freshdesk --template your_first_vue3_app
This is how the Vue app is structured from the sample app template.
And in the App component, it is the same like our React app, we fetch the contact information inside the mounted() lifecycle hook of Vue.js components by calling the initialize method which is actually using the client data methods.
<template >
<Sidebar :agentName="name" />
</template>
<script>
import Sidebar from "./components/Sidebar.vue";
export default {
mounted() {
this.initialize();
},
name: "App",
components: {
Sidebar,
},
data() {
return {
name: "",
};
},
methods: {
initialize() {
app.initialized().then((client) => {
client.data.get("contact").then(
(data) => {
this.name = data.contact.name;
},
(error) => {
console.error("error", error);
}
);
});
},
},
};
</script>
<style scoped>
</style>
Sample apps
You can find the Github repository links of various sample apps built with various frameworks in the Sample Apps section of the Freshdesk Developers documentation portal.
References
Hope you enjoyed the post, and had some basic understanding on how to use the fdk CLI to create Marketplace apps using React and Vue. Please feel free to reach out to the community for any queries and help.
Top comments (1)
Great article, thanks for sharing! Check out these amazing React Native templates for a different starting point