1. Developing Open Storefront Framework Applications for Oracle Commerce
  2. Set Up a Development Environment
  3. Set up a workspace

Set up a workspace

A workspace is a local directory hierarchy containing code and configuration for your storefront applications.

To create a workspace, you copy resources from one of the following:

  • A prepackaged Commerce application that serves as an accelerator template.
  • An existing deployed application.

This section describes how to create a workspace from an accelerator template. For information about creating a workspace from a deployed application, see Create a workspace from a deployed application.

Create a workspace from an accelerator template

You can use one of the following applications as a template for creating a workspace:
  • blank-store – a minimal application that contains a single custom component
  • core-commerce-reference-store – a more complete application that includes reference implementations of widgets and other components

To create the workspace, enter the following command:

npx @oracle-cx-commerce/cli-init create-workspace <workspace-dir> --template <template-name>

<workspace-dir> is the absolute or relative path to the top-level directory of the workspace. This directory must currently not exist or else be empty.

For example:

npx @oracle-cx-commerce/cli-init create-workspace my-workspace --template blank-store

This command uses the cli-init tool in the registry to run the Commerce create-workspace command. The command creates a subdirectory named my-workspace that contains the files and directories from the blank-store application.

The workspace top-level directory contains a number of files and directories, including the following:

  • A package.json file that designates the workspace as a private package, specifies package dependencies, and defines several scripts.
  • A packages/apps directory with a child directory containing the selected application (for example, packages/apps/blank-store).

You can also specify a different package name and Node.js module for your application when you create a workspace, by using the --appPackageName flag. For example: 

npx @oracle-cx-commerce/cli-init create-workspace another-workspace --template blank-store --appPackageName @my-module/my-storefront

This command creates a new workspace with an application named my-storefront in a module named @my-module.

Once you have created a workspace, you can begin creating your application by modifying or replacing the application code and configuration in the workspace.

Install package dependencies

Now install the package dependencies for the workspace. (These include the Commerce storefront framework and its dependencies.) To do this, go to the workspace directory and enter this command: 

yarn install

This creates and populates the node_modules directory under your workspace directory. Notice that the node_modules/@oracle-cx-commerce subdirectory contains a symbolic link to the application directory (such as blank-store) in your workspace’s packages/apps directory.

Note: When you run yarn install, you may see warnings similar to the following: 

warning " > @oracle-cx-commerce/cli@1.0.0" has unmet peer dependency "react@*".

You can safely ignore these warnings. For further information, see the following:

https://github.com/yarnpkg/yarn/issues/5347#issuecomment-463038189

Configure the workspace to access your server

Your local workspace requires access to a Commerce administration server environment to upload your application to and invoke REST API endpoints on. Typically, your organization is provided with three server environments (test, staging, and production). The process for configuring access to any of these servers is the same, differing only by which environment’s URL you specify.

The first step is to generate an application key by registering the application on the specific server you want to access, as described in Extending Oracle Commerce. Then enter the following command to configure your workspace: 

yarn occ configure --appKey --appServerAdmin <admin-server-URL>

where <admin-server-URL> is the URL of your Commerce administration interface. For example: 

yarn occ configure --appKey --appServerAdmin https://myhost-admin.oc-test.com

When you enter this command, you are prompted for an application key:

Please provide an appKey:

Enter the application key that was generated when you registered the application. (See Register applications.) When the command completes, it returns a listing of the various configuration settings for the workspace. Many of these settings are stored in the config.js file in the .occ directory of the workspace. You can update these settings with the configure command.

Build the application

To build the application in development mode, enter the following command:

yarn build

This invokes a script that runs Babel and Rollup to transpile all of the application’s source code into code that is suitable for use in environments such as Node.js and web browsers.

Note: In development mode, Rollup remains active and occupies the shell window it is in, watching for changes in the source code to rebuild its output accordingly. If you want to build just once, you can safely use Ctrl-C to exit from Rollup once you see the "waiting for changes" message.

Upload the application to the administration server

To make your application’s page layouts and components available in the administration interface, and to be able to preview and publish the application, you need to deploy the application to the administration server you configured access to. To deploy the application, enter this command:

yarn occ deploy

To move these assets from the preview context to the live context, log into the administration interface and publish the current change list.

Note that to see your deployed application’s layouts and other assets you may need to change the active application to the one you uploaded. To do this, select the application from the dropdown list near the top right corner of the Design page.

Run the application

Enter the following command to run the application in development mode:

yarn start

This invokes a script that uses the nodemon utility to start a local Express web server. The server hosts the application, and is restarted whenever the application is updated.

You can now access the application’s home page at http://localhost:80.

Note: The default port for the web server is 80, which may conflict with other web servers you have running locally. You can use a different port for the Express web server if necessary. For example, to use port 3000, enter the command: 

yarn occ configure --httpPort 3000

This setting is stored in the workspace's .occ/config.js file.