Building custom components with UI Framework is pretty easy, but setting up the development environment is still a tricky part and one can be discouraged very quickly.
Here you can find a step-by-step tutorial on how to set up your development environment incl. fixing one of the most common issues. Enjoy!
As I am a Windows user, everything here is aimed mainly at Windows users
Preparations
1. Node.js & npm
The currently supported Node.js version is 12.16.1. Make sure you don't use any other. Npm version 6.13.4 comes with it so you are fine here.
Now-cli installation
If your Windows username contains spaces (eg. C:/Users/Jan Moser), don't install now-cli globally. It won't work. You need to take some extra steps before moving forward. Move to " Space in username fix" at the end of this guide (don't worry, it will ship you back to continue on " Component development" ;)).
If there are no spaces in your Windows username, you can continue further down with no worries.
1. Install now-cli
npm install @servicenow/cli@{instance} -g
Example: npm install @servicenow/cli@rome -g
2. yo
You will be probably prompted to install the "yo" library as well. Do it.
Component development
1. Instance check
Make sure your instance is up and running
2. Folder for your component
Create a new EMPTY folder wherever you want to store your component files.
The folder needs to be completely EMPTY indeed.
3. Login
While being in your component folder, run the following command to connect to your instance
now-cli login --host https://{your_instance}.service-now.com --method basic --username {username} --password {password}
4. Scaffolding component files
While being in your component folder, run the following command to scaffold files for your component
now-cli project --name {name} --description '{description}'
Project name must contain at least one "-".
Example: now-cli project --name @jan/some-demo --description 'Some demo'
5. Installing npm dependencies
While being in your component folder, run the following command to install all component dependencies
npm install
6. Hello world
Go to your component and write obligatory “Hello World” there. Save it.
7. Starting the dev server
While being in your component folder, run the following command to start the dev server to see your component alive:
now-cli develop –open
8. Working on your component
Now, you can keep working on your component (not part of this tutorial). Each time you save any of your component files, you will see changes in the browser.
Component deployment
10. Deploying your component
While being in your component folder, run the following command to deploy your component to your instance
now-cli deploy
If it is not your first component deployment, you need to use "-f" to force override the existing one in your instance.
now-cli deploy -f
After the deployment is over, your component is available in UI Builder for use 😊
Known issues
| Issue | Fix |
| Non-empty folder when creating a new project | The folder for the new component (before you run the now-cli project… command) must be completely empty. |
| “Error: Module did not self-register:” or any other error after running now-cli | Make sure you are using Node.js version 12.16.1. Especially when you use nvm (Node Version Manager), sometimes you might forget to switch to the correct version. |
| Error: Cannot find module 'keytar' | Probably again the wrong Node.js version. Switch to the correct Node.js version and reinstall everything (incl. now-cli) |
| exit status 1: 'C:\Users\{firstName}' is not recognized as an internal or external command, operable program or batch file | This is probably the most annoying problem. When your username in Windows is something like “Jan Moser” (so your user folder is something like “C:/Users/Jan Moser”), now-cli fails. |
| Uncaught ReferenceError: process is not defined after you run command "now-cli develop --open" | This error is caused because of a new version of react-error-overlay. This new version is not currently compatible with now-cli. A quick workaround is to manually install the previous version using the following command (from within your project folder): npm i -ED react-error-overlay@6.0.9 Thanks to |
Space in username fix
When you have space in username in Windows, then you have a problem, now-cli won’t work. Here is the fix. (I consider you are doing a fresh new installation of everything. Now-cli cannot be installed globally in this approach.)
1. Node.js and npm
Stays the same (see above in " Preparations")
2. Finding out your short username
Run the following command in folder „C:/Users“
dir /x
You should see what „short name“ has got your username.
Example: JANMOS~1
3. Adjusting npm environment variable
Open Environment variables and change your {name surname} in the path to npm to {your_shortname}
Example: C:\Users\JANMOS~1\AppData\Roaming\npm
4. Folder for now-cli and your projects
Create a new folder without spaces for your UI Framework projects
Example: C:/ServiceNowProjects
5. now-cli local installation
Run the following command in your newly created folder
npm install --prefix ./install/ @servicenow/cli@{instance}
6. Adding "install" folder into Environment variables
Open Environment variables and add there the path to your subfolder “install”
Example: C:/ServiceNowProjects/install
Now, whenever you want to develop a component, just create a new folder for it here in “C:/ServiceNowProjects” (sibling of “install” folder) and now-cli will work just fine.
You can continue by jumping back up to " Component development".
That's it.
Enjoy your component development.
JM
