Using React in a Support app

In this tutorial, you'll use React to create a Zendesk Support app. To build the app, you'll use the Zendesk React app scaffold and Zendesk Garden React components. You can use the app's code as a starting point for your own app.

The app displays a timeline of events for a ticket requester. Agents can access the app while viewing a ticket in the Agent Workspace.

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk doesn't provide support for the app or example code in this tutorial. Zendesk doesn't support third-party technologies, such as React, Babel, or Vite.

What you'll need

To complete this tutorial, you'll need the following:

• Node.js 20.17.0 or later

• A Zendesk account with the Zendesk Suite Growth plan or above, or the Support Professional plan or above. To get a free eligible account for testing, see Getting a trial or sponsored account for development.

• The Zendesk Command Line Interface (ZCLI). To install or upgrade ZCLI, refer to Installing and updating ZCLI. You also need to authenticate ZCLI with your Zendesk account. See Authentication in the ZCLI documentation.

  ZCLI replaces the Zendesk Apps Tools (ZAT), which are in maintenance mode. To use ZAT instead, refer to Installing and using ZAT.

• Familiarity with the Zendesk Apps framework (ZAF). Before you start, complete the Zendesk app quick start.

Creating the app files

First, use the Zendesk React app scaffold to create starter files for an app named User events.

To create the app files

1. In your computer's terminal, navigate to the folder where you want to store the app. Example:

   cd projects

2. In the folder, run:

   zcli apps:new --scaffold=react

3. At the prompts, enter the following values:

   • Directory name: user_events
   • Author's name: Your name
   • Author's email: Your email address
   • Author's website: Leave blank and press Enter.
   • App name: User events

   ZCLI creates the files for your project in the user_events folder. To learn more about the React app scaffold's file structure, see the documentation on GitHub.

Installing dependencies

The React app scaffold includes React, Vite, and Zendesk Garden React component libraries as dependencies. Next, install the project's dependencies.

To install dependencies

1. In your computer's terminal, navigate to the project's root folder. Example:

   cd projects/user_events

2. In the project's root folder, run:

   npm install

   This command installs the dependencies listed in the project's package.json file.

Reviewing the project's source files

Browsers don't natively support JavaScript modules, such as those used to import React. Instead, React projects commonly use JavaScript bundlers like Rollup or Webpack to convert code written with JavaScript modules, along with other assets, into browser-ready files.

The app scaffold uses Vite, which uses Rollup under the hood to build Zendesk app files from source files in the src folder. When run, the final app files will be placed in a dist folder in the project's root.

As part of the build, Vite bundles any required JavaScript, CSS and static assets for the app. You can configure starting points for the bundle in the build.rollupOptions.input object of vite.config.js. Your project uses src/index.html as a starting point:

...
main: resolve(__dirname, 'src/index.html')
...

Any local JavaScript, CSS, or static assets referenced by index.html will be bundled into the dist directory.

When the app is created, the code in src/app/contexts/ClientProvider.jsx creates a new instance of the ZAF client and provides it to the app in the src/app/index.jsx. This lets you use the ZAF client in the app code via the useClient hook.

const client = useClient()

You can edit the TicketSideBar component in src/app/locations/TicketSideBar.jsx to make changes to the Zendesk app.

Adding the timeline component

Next, update the TicketSideBar component to fetch the ticket requester's events. Use Zendesk Garden's Timeline component to display the events in the app.

To add the timeline component

1. First, install Zendesk Garden's Timeline component by running:

   npm install --save @zendeskgarden/react-accordions

2. In the src/app/locations folder, open TicketSideBar.jsx. Replace the file's contents with the following:

   import { useEffect, useState } from 'react'
   import { useClient } from '../hooks/useClient'
   import { Timeline } from '@zendeskgarden/react-accordions'
   import { Span } from '@zendeskgarden/react-typography'
   import styled from 'styled-components'
   import { ThemeProvider, DEFAULT_THEME } from '@zendeskgarden/react-theming'
   import { formatDate, toSentenceCase } from '../../lib/formatting'
   
   export const StyledSpan = styled(Span).attrs({ isBold: true })`
     display: block;
   `
   
   const TicketSideBar = () => {
     const client = useClient()
     const [sortedEvents, setEvents] = useState([])
   
     useEffect(() => {
       ;(async () => {
         client.invoke('resize', { width: '100%', height: '450px' })
         const requesterId = await client.get('ticket.requester.id')
         const eventRequestOptions = {
           url: `/api/v2/users/${requesterId['ticket.requester.id']}/events`,
           data: `page[size]=5`
         }
         const events = await client.request(eventRequestOptions)
         setEvents(events.events.sort((a, b) => (a.created_at > b.created_at ? 1 : -1)))
       })()
     }, [])
   
     return (
       <ThemeProvider theme={{ ...DEFAULT_THEME }}>
         <Timeline>
           {sortedEvents.map((event) => {
             return (
               <Timeline.Item key={event.id} data-event-id={event.id}>
                 <Timeline.Content>
                   <StyledSpan>{toSentenceCase(event.type)}</StyledSpan>
                   <Span hue="grey" data-type="date">
                     {formatDate(event.created_at)}
                   </Span>
                 </Timeline.Content>
               </Timeline.Item>
             )
           })}
         </Timeline>
       </ThemeProvider>
     )
   }
   
   export default TicketSideBar

   The code exports the TicketSideBar component. It uses the ZAF client's get() method to fetch the ticket requester's user id. It then uses the id to make a request() call to the Get Zendesk User Events endpoint. The endpoint returns up to five events for the requester.

   The component loops through the events returned by the Get Zendesk User Events request. It renders each event's type and created_at values using Zendesk Garden's Timeline component.

   The file also imports the toSentenceCase and formatDate functions to format event values. You'll create these functions in the next step.

3. Finally, in the src/lib folder, create a new file named formatting.js. Add the following toSentenceCase and formatDate functions to the bottom of the file:

   ...
   /**
   * Helper to convert snake case strings to sentence case
   * @param {String} string Snake case string
   * @return {String} Sentence case string
   */
   export function toSentenceCase (string) {
     const finalString = string.replace(/_/g, ' ')
     return finalString.charAt(0).toUpperCase() + finalString.slice(1)
   }
   
   /**
   * Helper to format ISO 8601 timestamps as human-readable datetime
   * @param {String} date ISO 8601 timestamp
   * @return {String} Formatted date. Example: Sep 1, 2099 2:55 PM
   */
   export function formatDate (date) {
     const formattedDate = new Date(date)
     const options = {
       year: 'numeric',
       month: 'short',
       day: 'numeric',
       hour: 'numeric',
       minute: 'numeric'
     }
     return formattedDate.toLocaleDateString('en-us', options)
   }

Running the app locally

Run your app locally to ensure it displays the Timeline component.

To run the app locally

1. In the project's root folder, run:

   npm run dev

   The command uses Vite to start a development server which compiles and hot reloads your code on every file save.

   Note: To stop the command, press Ctrl+C.

2. In another terminal session, run the following command in the project's root folder:

   npm run start

   The command starts a local ZCLI web server.

   Note: To stop the command, press Ctrl+C.

3. In your browser's private or incognito window, sign in to Zendesk Support and go to the Agent Workspace. From the workspace, open a new or existing ticket.

   The URL should look like this:

   https://{subdomain}.zendesk.com/agent/tickets/{ticket_id}

4. Append ?zcli_apps=true to the URL and press Enter. The URL should now look like this:

   https://{subdomain}.zendesk.com/agent/tickets/{ticket_id}?zcli_apps=true

5. Click the Apps icon.

   

6. The app displays the event timeline.

   

Installing the app

As an optional step, you can upload and install the app as a private app in your Zendesk Support instance.

To install the app

1. If running, stop the npm run dev and npm run start commands by pressing Ctrl+C in the respective terminal sessions.

2. In the project's root folder, run:

   npm run build

   The command builds outputs the app files to the dist folder.

3. In the project's root folder, run:

   zcli apps:create ./dist

   ZCLI packages, uploads, and installs the app to your Zendesk instance.

4. In Admin Center, click the Apps and integrations icon () in the sidebar. Then select Apps > Zendesk Support apps.

   The app appears in the list of installed apps on the My Apps page.

   

Congratulations! You've created a Zendesk app that uses React. As a next step, you can get your app ready for production. Consider tackling the following tasks:

• Adding error handling for the ZAF client's request() call

• Limiting the Get Zendesk User Events request to specific event sources or times

• Localizing the app's strings using the React app scaffold's i18n module

• Updating the unit tests in the spec folder