Getting Started for Developers

1: Getting Started – Prerequisites

In order to run a local instance of the Ultra Commerce React storefront on your machine, there are a number of environmental requirements.

Install Node.js

Firstly you will need to install node.js “v16.6.0” built with current templates on your operating system of choice. https://nodejs.org/en/download/

Tip: We recommend using node version manager and switching between versions easily if running multiple projects on a different version.

Setting the $PATH

For Mac users, ensure your $PATH variable is correct and matches.

/usr/local/bin

For reference: https://stackoverflow.com/questions/7703041/editing-path-variable-on-mac

Install NPM & NPX

Next update the node version by running the following terminal command

sudo npm install npm –global

Install npx via this terminal command:

sudo npm install -g npx

Create Storefront & React App

Create the React environment with this command:

npx create-react-app my-new-storefront –template @ultracommerce/cra-template-ultra-commerce-storefront

Tip: ‘my-new-storefront’ is the name of your new project. By default, this will download a variety of this project, not the full source code but will be a fully functional app.

Ok to proceed? (y)

Type y and hit enter. A number of dependent packages will be installed over a few minutes.

After a successful installation, you should see this message.

2. Ultra Commerce Source Code

You can navigate to Github to access the complete Ultra Commerce source code for the React template and other helpful documentation. https://github.com/ten24/ultracommerce-storefront-react

3. Ultra Commerce API

Ultra Commerce is a headless eCommerce platform driven by API and an SDK.

The complete Developer API documentation is found here. https://publicapi.ultracommerce.co/

You can view this complete API in Postman and pull in the collection to run it and test scripts against your environment. Its purpose is to demonstrate all of the public APIs we offer.

The storefront ties back into the API and has been wrapped in a Javascript SDK that works via browser JS or node server. The SDK also includes helpful links back to Postman and the Ultra Commerce React Storefront. This code is also available via the Github repository.

Tip: Code releases are generally built and published on a monthly basis.

4. Ultra Commerce SDK

This SDK below is the exact same that Ultra Commerce uses to build the storefront

https://www.npmjs.com/package/@ultracommerce/ultracommerce-sdk

5. Creating your Storefront

Let’s start reviewing the core codebase. To do this, you will need a preferred visual tool installed. We suggest Visual Studio Code, it’s free and can be downloaded for your operating system of choice. https://code.visualstudio.com/download

Follow this stack overview guide to allow you to open code directly from the Mac Terminal command line. https://stackoverflow.com/questions/29971053/how-to-open-visual-studio-code-from-the-command-line-on-osx

Run the following terminal command to open the code.

-n my-new-storefront

Once VS Code is installed and running, open the folder “my-new-storefront/”

Next we can edit the basic configuration variables by selecting “.env” from the left navigation pane. In order for the site to function, a setting is required for the follow 4 x variables.

REACT_APP_SITE_CODE=
REACT_APP_API_URL=
REACT_APP_ADMIN_URL=
REACT_APP_HOST_URL=

Site code is the name of the site inside your Ultra Commerce instance you wish to run against. Ultra Commerce supports multiple sites so be sure to select the one you wish to use.

URL for API and host/admin URL’s need to be added.

Tip: If you are using Kontent or another application, you will need to modify the .env property accordingly

You can use the following example:

REACT_APP_SITE_CODE=sports-shop
REACT_APP_HOST_URL=https://uc-develop.ultracommerce-dev.co/
REACT_APP_API_URL=https://uc-develop.ultracommerce-dev.co/index.cfm/
REACT_APP_ADMIN_URL=https://uc-develop.ultracommerce-dev.co/index.cfm/

Next open the terminal window in Code: code → terminal → new terminal

Run the following command

npm run start

Visual Studio Code will fire up a browser instance of the Storefront on http://localhost:3006/

You should now see the Ultra Commerce React Storefront running.

Storefront Basic Authentication

If you’re blocked from accessing the website by a basic authentication login box, you will need to sign in with the following credentials.

Username: Ultra
Password: 10Yellow24

Tip: This will not work on an iPhone due the way basic auth is handled.