Create a new application by copying a template

You can create the basic directory structure for your application by copying an existing application directory from your workspace’s packages/apps directory into a new subdirectory of packages/apps.

For example, if you have downloaded the blank-store template and you want your new application to be named my-app, go to your workspace’s packages/apps directory and copy the entire blank-store directory and its subdirectories into a new directory named my-app. Then enter the following command:

yarn occ configure --appName my-app

This modifies the config.js file in the workspace’s .occ directory to make my-app the default application for the workspace. Now the workspace commands and scripts such as build, deploy, and start will operate on this application instead of the template application.

At this point, the my-app application is identical to blank-store. You can now modify the my-app application to implement your own application.

Modify the application’s package.json file

The top-level directory of an application (for example, my-workspace/packages/apps/my-app) contains an application-specific package.json file. This file is distinct from the package.json file in the top level of the workspace.

After creating a new application, you need to modify this package.json file. Change the values of the following settings:

name – The name for your application (for example, @my-apps/my-app).
version – The version number for your application (for example, 0.0.1). You can use whatever numbering scheme you want, but it is a good idea to track the version using this field.
description – The value of this setting is used to identify your application in the Design page application selector dropdown.

For example:

"name": "@my-apps/my-app", 
"version": "0.0.1",
"private": true, 
"description": "My storefront application",

In addition, change these settings in the file’s occ object:

locales – An array of the locales for which you are including translation strings for your application. You may want to set this to a single locale while you’re getting started and update the setting later.
allowedUrls – An array of the URLs that the application calls out to. These URLs are added to the list maintained by your Oracle Commerce environment. Calls to these URLs (including any subpaths) are permitted. Calls to domains that are not on this list are blocked.

For example:

"occ": {
  "namespace": "occ.react",
  "locales": [
    "en",
    "de"
  ],
 "allowedUrls": [
    "http://www.example.com",
    "http://www.example2.com"
  ] 
}

Note: The allowedUrls property replaces the whiteListedUrls property that was formerly used for specifying external domains. The whiteListedUrls property has been deprecated. If you currently have an application whose package.json file has the whiteListedUrls property, you should rename the property to allowedUrls. If you do not rename the property, Commerce will continue to permit access to the domains specified in whiteListedUrls. However, if you add the allowedUrls property without removing whiteListedUrls, Commerce will ignore whiteListedUrls and permit access only to the domains specified in allowedUrls.

After you have updated the settings in this package.json file, run yarn install to create the symbolic link to your application directory.

At this point, if you build, upload, and start the application, you will see your application in your browser when you access the local web server. You can now proceed to make functional changes to the application by creating your own pages and components.

For information about how to build storefront components and include them in pages, see Create Custom Widgets and Design Storefront Pages.