Get started with e-commerce online extensibility development

Article
05/28/2024

This article provides an overview to help you get started developing e-commerce customizations using the Microsoft Dynamics 365 Commerce online software development kit (SDK)..

You can use the Commerce online SDK to develop and debug e-commerce modules, data actions, and themes. It can be installed and used in any Windows 10 environment, and doesn't require a deployed Commerce environment. However, it can also be useful to connect to a live cloud environment (for example, "Dev," "Test," "UAT," or "Prod"). In this way, you can do deeper debugging and test changes against a cloud environment without having to deploy or destabilize the environment.

The typical process when you extend the Commerce platform includes the following actions:

Install the required development tools.
Install the latest online SDK.
Optional: Set up an Azure DevOps build pipeline for code sharing and build management.
Build and extend modules, data actions, and themes as required.
Test modules, data actions, and themes by using mock data.
Optional: Test modifications against a cloud environment.
Build a Commerce configuration package of all changes.
Deploy the configuration package to a cloud environment.

Architectural overview

Before you start Commerce extensibility development, we recommend that you learn about the Commerce architecture. The Dynamics 365 Commerce architecture overview and E-commerce architectural overview articles are great places to start. Additionally, the E-commerce components article provides an overview of the main extensible e-commerce components, such as modules, data actions, and themes.

Set up a local online SDK development environment

Development system requirements

Before you set up a development environment, make sure that your environment meets the minimum requirements that are specified in System requirements for a Dynamics 365 Commerce online extensibility environment.

Install development tools and the online SDK

Commerce development uses some free open-source tools, such as Node.js for the JavaScript runtime, Yarn for dependency management, and Visual Studio Code for source editing. For detailed information about how to install each of these tools, see Set up a development environment. That article also explains how to run a Node app to test and preview modules that are under development, and describes the command-line interface (CLI) tools that are used to create and clone a module.

Develop against a cloud-hosted Commerce environment

The online SDK lets you develop and debug modules, data actions, and themes without having to use a deployed Commerce environment. There might be scenarios where you must debug your live e-commerce website or test configuration changes against a live cloud environment, such as a "Dev," "Test," "UAT," or "Prod" environment. This section explains how to configure your development environment against a cloud-hosted Commerce environment.

Configure the SDK environment .env file

The online SDK includes an .env file in the root folder. This file has several environment variables that you can use to configure your development environment against a cloud environment. For detailed information about each environment variable, see Configure a development (.env) file.

Configure against a cloud environment

For detailed information about how to configure the .env file so that it points to a cloud environment, see Debug against a tier 1 Commerce development environment. That article also provides guidance that will help you set the correct URL for each variable in the .env file.

There are two main scenarios that you can set up. In the first, you point the .env file to a cloud Retail Server, and in the second, you point it to a cloud e-commerce site.

Configure against a cloud-hosted Retail Server

By configuring a development environment so that it points to a cloud-hosted Retail Server, you can debug modules and data actions against live data. After the server is configured, all data action calls go directly to it and pass real data back to your development environment. This setup gives you a great way to see how a module will be rendered. Otherwise, you must use mock data to render your modules. For more information, see Test modules with mock data and Test data action with mocks.

The .env file contains a MsDyn365Commerce_BASEURL variable that must point to the URL of a cloud-based Retail Server. Additionally, you must point to a specific channel and channel operating unit number (OUN).

The following example shows an .env file that points to a specific Retail Server, channel, and OUN.

...
MSDyn365Commerce_BASEURL=https://e-comdevtestf1d01de665c744a7devret.cloud.retail.dynamics.com/
MSDyn365Commerce_CHANNELID=68719478279
MSDyn365Commerce_CATALOGID=0
MSDyn365Commerce_OUN=128
...

Note

The catalog ID variable, MSDyn365Commerce_CATALOGID, must always be set to 0 (zero), because Commerce doesn't support multiple catalogs.

Configure against a cloud-hosted e-commerce site

You can also configure a development environment so that it points to a cloud-hosted e-commerce site. In this way, e-commerce pages that are created in Commerce site builder can be rendered in the local environment under the local Node.js JavaScript server. This setup is useful because you can test changes to modules, data actions, and themes against live pages without affecting the live site. For example, you can test module view changes that you've made locally for any e-commerce page, without affecting the live e-commerce site or customer views of it.

Commerce site pages are stored in the Commerce content management system (CMS) as JavaScript Object Notation (JSON) files that can be saved and used as mock files. The JSON files contain the breakdown of modules and their configuration values. Those configuration values are used to render pages. In this scenario, the local development environment renders the local modules. Therefore, you can quickly test and iterate your changes.

For information about how to use page mocks to test modules, see Test modules by using page mocks. That article includes information about how to create a page mock from a live page by using the ?item=nodeserviceproxy:true query string parameter.

The following example of a JSON file shows how to set up the MSDyn365_HOST variable so that it points to your Commerce environment.

MSDyn365_HOST=www.fabrikam.com
MSDyn365Commerce_BASEURL=https://e-comdevtestf1d01de665c744a7devret.cloud.retail.dynamics.com/
MSDyn365Commerce_CHANNELID=68719478279
MSDyn365Commerce_CATALOGID=0
MSDyn365Commerce_OUN=128
...

For more information about how to set up the MSDyn365_HOST variable so that it points to your Commerce environment, see Debug against a tier 1 Commerce development environment.

Change modules, data actions, and themes

After you've set up a Commerce development environment, you're ready to build custom modules, data actions, and themes.

Package creation and deployment

After you've completed all your changes, you can build a zip file package and upload it to Microsoft Dynamics Lifecycle Services (LCS). You can then see all your changes in the cloud-hosted environment that the package was deployed to. For more information and instructions, see Package configurations and deploy them to an online environment.