Access local development applications on a Commerce server
OSF supports isolating different versions of assets on a 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 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 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 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 Commerce server. So, for example, the following commands might be used to specify the local application name, deploy the application to the 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 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 hosted application
Each local application can have a separate version of a specific asset. Even when a local asset is deployed to a 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 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 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.