Access Local Development Applications on a Retail Digital Commerce Server

OSF supports isolating different versions of assets on a Retail Digital Commerce server instance, allowing developers to work on local versions of an application independently while taking advantage of the features provided by remote rendering.

The key to sharing a Retail Digital Commerce server instance is for each developer to supply a local development application name for his or her version of the application. The local development application name should be different for each developer, and each local development name should be different from the hosted application name (which is the same for every developer). For example, the name for the hosted application might be storefront-app, while the local development names could be fsmith-app, jjones-app, and so on.

The location of the source code for the application is the same in each local workspace, and reflects the hosted application name (for example, /packages/apps/storefront-app).

Use the Local Development Application Name

You can use the --localDevAppName flag to specify the local development application name to use when deploying and accessing the assets that are specific to the local workspace. For example, you could enter:

yarn occ deploy storefront-app --localDevAppName fsmith-app

This command deploys the local version of the application to the Retail Digital Commerce server as fsmith-app.

The following commands all accept the --localDevAppName flag:

create-template, delete, deploy, deploy-log, deploy-status, download, download-assets, serve, upload-demo-search-keywords, upload-search-config

A local development name can also be configured persistently for an application so that it does not have to be included explicitly in commands. For example:

yarn occ configure-app storefront-app --localDevAppName fsmith-app

The setting is stored in the application configuration file (/packages/apps/storefront-app/.occ/config.js). For example:

module.exports = {
  "localDevAppName": "fsmith-app"
};

Override the Local Development Application Name

A developer can use the --no-localDevAppName flag to remove the local development name from the application configuration. For example, the following command deletes the setting from the application's .occ/config.js file:

yarn occ configure-app blank-store --no-localDevAppName

The --no-localDevAppName flag can also be used with the commands that accept --localDevAppName to override the local development application name without removing the name from the application configuration. For example:

yarn occ deploy storefront-app --no-localDevAppName

This command deploys the application to the server as storefront-app, but leaves the local development application name setting in the application configuration. For example, a developer might use this to check the deployment status of the hosted application in the preview or live context.

Render a Local Development Application in a Local Workspace

Local development applications deployed to a Retail Digital Commerce server cannot access the Node.js instances on the server, and therefore cannot be hosted in the server's preview or live context. Only the hosted version of the application can be installed in these environments.

To view and test a local application while accessing the application-specific asset versions, a local workspace's Node.js instance must be used to render the design assets that are on the Retail Digital Commerce server. So, for example, the following commands might be used to specify the local application name, deploy the application to the Retail Digital Commerce server, and then run the application locally while accessing assets on the server:

yarn occ configure-app blank-store --localDevAppName fsmith-app
yarn occ deploy blank-store
yarn occ serve blank-store --dsAssetMode remote

Access Local Application Assets in the Administration Interface

Although a local development application that is deployed to a Retail Digital Commerce server cannot be rendered on the server, its assets can be accessed in the administration interface. Multiple developers may have their own local development versions of the same application, and to avoid conflicts, each version has a separate entry in the application selector dropdown on the Design page. To distinguish the different versions, the description that appears for each application in the dropdown is prefixed by the local development name of the application.

Update a Fosted Application

Each local application can have a separate version of a specific asset. Even when a local asset is deployed to a Retail Digital Commerce server and published, each version of the application can have a different version of that asset.

This means that developers must ensure that they do not overwrite each other's changes when they commit them to version control. Code must be merged carefully to resolve conflicts. Keep in mind that in addition to changes made in local workspaces, developers and designers may also makes changes on the server that must be managed as well, as discussed in Sync assets on a Retail Digital Commerce server with a local workspace.

To minimize risks, it is a good idea to use a continuous integration server that runs the code that has been committed to version control, and deploy changes to the hosted application from there.

Deploy a Local Development Application as the Hosted Application

As discussed above, a local development application's assets can be deployed to a Retail Digital Commerce server, but for the application to run it must be rendered in a local workspace.

In some cases, a developer may want to deploy a local version of an application to the server, and have it be rendered there so other developers can access the running application. Before doing this, make sure that all of the assets from the "true" hosted version have been checked into source control so that the version can easily be re-created later; there should be no pending changes. Then deploy the local application using the --no-localDevAppName flag, so that it becomes the hosted application. For example:

yarn occ configure-app blank-store --reset --no-localDevAppName

Note that the --reset flag forces all of the assets from the local application to be deployed to the server, overwriting the assets from the hosted version.