React application in ServiceNow
This quick tutorial explains how to 1) create, 2) build and 3) deploy React application to ServiceNow.
The first two steps are about general React development, so we’ll provide just a few details on how to start if you’re not familiar with React. There are many React tutorials and courses all over the internet, you can start learning on reactjs.org or Udemy.
1. Create React application
When you start a new web application you don’t always start from scratch. A common approach is to use a boilerplate.
A boilerplate is a template which you can clone and reuse for every project. Boilerplate includes dev environment configurational settings and may include some basic html/js/css files.
The easiest way to start with React app is to use the most popular React boilerplate — Create React App (CRA).
Make sure you have nodejs installed (run the following command in a terminal/mac or cmd/windows):
If it’s not installed in your system then navigate to https://nodejs.org and install LTS version.
- Install the CRA boilerplate. The following command creates my-app folder, downloads all boilerplate files and installs the dependencies.
npx create-react-app my-app
As a result, you will get a simple React application with a pre-defined folder structure:
That is easy enough. You have your first React application ready.
2. Run the application. Navigate to my-app folder and execute the following command:
This starts a local development server and you can check the app by navigating to http://localhost:3000
CRA provides many features out of the box, hot reloading is one of them. Try to add some code in App.js (I added line #10), save it and your browser will be updated automatically:
That’s it. You just installed React boilerplate with a simple React app and hosted the application with a local dev server.
2. Build the application
Building (packaging) the application is a pretty straightforward step as well. You can build the app using
npm run buildcommand. That will create a build folder, where all files for production deployment will be placed.
Before building the app, we want to modify packaging options — the primary goal is to have just 3 files (html/js/css). You still can use OOB settings, it just produces more files and you will need to update more dependencies when deploying to ServiceNow. So, for now, I recommend changing OOB settings as described below.
build-no-split.jsfile to the root folder of your React application.
package.jsonwith the following:
"build": "node build-no-split.js"
npm install rewire
And now you are ready to build the application:
npm run build
The application package will be compiled and saved into the build folder:
You will find multiple files there, however, we need only 4 of them:
- index.html — main .html file for our application
- /static/js/main.<hash>.js — js bundle file
- /static/css/main.<hash>.css — combined CSS file
- /static/media/logo.<hash>.svg — just a logo image used in the application
We are not going to deep dive into details of other files, you can skip them. They are not necessarily required for our deployment.
3. Deploy React application to ServiceNow
There are three basic steps need to be performed when deploying React application to ServiceNow:
- Import .js and .css assets
- Upload static images
- Deploy the core HTML file
Import .js and .css assets
This is the key part of the deployment procedure since js bundle contains the entire logic of your application. I would even say THAT IS your application, sometimes you may not have a .css file at all, you can package css into js bundle.
The most efficient and simplest way to import your .js and .css assets into ServiceNow is to store them as Content Management Style Sheets:
- Navigate to Content Management/Style Sheets
- Create a new Style Sheet for each asset (name does not matter)
- Copy js/css code from your package files, save the Style Sheet
As a result, you should have two Style Sheets — one for js code and another one for css. Why Style Sheets? Because you can access the content (code) just by navigating to the following URL:
The content of stylesheets is publicly available, and you don’t need to log in to view the content.
You can also serve .js code as a ServiceNow UI script (System UI -> UI Scripts), it works absolutely the same way like style sheets, just reference it as <UI_script_API_name>.jsdbx
There is a catch — you won’t be able to host the code which size is greater than 1.3MB. If that’s the case, then you need to serve it in a different way. You may store the file as a regular attachment in ServiceNow and then reference it like this:
Attachment method is slower than .cssdbx, you have to be logged in and have permissions to download the attachment content. However, there is no limitation on the file size.
We will use .cssdbx method because it is easier, faster and can be used for public pages/applications.
Upload static images
We do have one image (React logo) in our first React application.
The most appropriate way to host static images is to store them as Image records in ServiceNow instance:
- Navigate to System UI/Images
- Create a new record, upload the image
- Provide the appropriate name for your image. This is very important: the image name should be the entire path to your image in a build folder. Your image name should end up with something like
Deploy the core HTML file
Index.html is a shell (container) for the React application. When loaded in a browser it retrieves and then executes js bundle.
One of the options on how to deploy Index.html to ServiceNow is a UI page:
- Create a UI page, set Direct to
- Copy content of Index.html
- Remove <!doctype html> (UI page does not support it)
- Remove references to
- Add closing / to <link> tag (line #7)
- Update references to .css and .js files with the corresponding .cssdbx links
- Save UI page
That’s it. Click Endpoint link to open the React application in a new tab:
If you just click “Try It” on UI page form, the application will be loaded directly into UI16:
You just created, packaged and deployed your first React application to ServiceNow.