Set up Workbench on your local environment

Get the Workbench CLI tool set up on your local machine. This is recommended for production development.

Step 1: Set up your local environment

To use the Workbench CLI tool effectively, you need a few things installed on your machine. This works on Mac, Windows and Linux.

1.1. Install NodeJS

We need to install NodeJS in order to set up and use the Workbench CLI tool.

Download NodeJS and install it to your machine.

1.2. Install VS Code

We need a code editor in order to use the Workbench CLI tool. We generally prefer VSCode, by Microsoft, but any IDE will work such as Sublime Text.

Download VS Code and install it to your machine.

1.3. Install Project Snippets extension (optional)

Some IntelliSense functionality in the Workbench CLI tool depends on the Project Snippets extension in VSCode.

Visit Project Snippets to install the extension in VSCode.

Step 2: Install the Workbench CLI tool

Now that we have NodeJS and a code editor set up, we can proceed to install the Workbench CLI tool.

Mac instructions

If you are on Mac, open your Terminal.

🚧

Install global npm packages in an unrestricted directory

If you are using a Mac, you may run into permission issues when trying to install global npm packages to the default directory.

We recommend configuring npm to install global packages into a directory that doesn't require strict permissions. You can do this by running the following commands in your terminal:

Bash example:

mkdir ~/.npm-packages
npm config set prefix ~/.npm-packages
echo 'export PATH=$PATH:$HOME/.npm-packages/bin' >> ~/.bashrc

Zsh example:

mkdir ~/.npm-packages
npm config set prefix ~/.npm-packages
echo 'export PATH=$PATH:$HOME/.npm-packages/bin' >> ~/.zprofile && exec zsh

Alternatively, you can avoid installing Workbench locally by prefixing any workbench commands with npx. Read more here.

In Terminal, type (or copy/paste) npm install -g @rootplatform/cli and press enter. This will download and install the Workbench CLI tool on your machine.

Once that command finishes, you can test that the Workbench CLI tool installed correctly by typing rp help. (All Workbench CLI tool commands use the format rp [command] [options].)

The Workbench CLI tool and your environment is now set up and ready to go.

❗️

Node V16

If you're using Node V16, you might run into some usage issues. This can be resolved by using a tool like nvm to install and run Node V14.x or V12.x. If you use nvm, you may be able to configure your shell to automatically use the correct Node version when running commands in the product module directory.

Windows instructions

If you are on Windows, open Command Prompt.

In Command Prompt, type (or copy/paste) npm install -g @rootplatform/cli and press enter. This will download and install the Workbench CLI tool on your machine.

Once that command finishes, you can test that the Workbench CLI tool installed correctly by typing rp help. (All Workbench CLI tool commands use the format rp [options] [command].)

Your local environment is now set up and ready to go.

Step 3: Clone a product module to your local machine

Now go back to your Terminal (or Command Prompt) and clone (download) your Dinosure product module using the Workbench CLI tool.

  1. cd to your working directory, e.g. Documents (Mac help, Windows help) or just stay in the current directory.
  2. Clone the product module using the command rp clone <api_key> <product_module_key> -h <host>, for example:
rp clone sandbox_ZGEyYzQdOWUtNTM1My00ZmQ5LTk4NDItYmJiMjYwZWQ3NzA5LkCJYkZzYmptUlJ3UmNvTGtVN3ltRl9yQVRCT3ZFNDZb dinosure_jane -h https://sandbox.uk.rootplatform.com

Here you can paste the API key from your clipboard using Cmd+V (Mac) or Ctrl+V (Windows). If you need to verify the name of the product module, you can navigate to " Workbench > Product modules" on the dashboard.

📘

Use the correct host when cloning your product module

Copy the sandbox URL for your region from the domains section of the API reference.

  1. Now navigate with your Terminal/Command Prompt into that project directory using cd <product-module-key> (e.g. cd dinosure_jane). Try ls (Mac) or dir (Windows) to list all the files in the directory. To double check that all the files were downloaded correctly, take a look at the File and folder structure guide.

This new project directory can now be opened with your code editor to see and edit all the files and components of your Dinosure product module.

Well done! You have successfully completed the basic Workbench CLI tool setup. In the next tutorial you will use the Workbench CLI tool to implement your first product update.