Extend a theme from a base theme

Note

The Retail Interest Group by Dynamics 365 Commerce has moved from Yammer to Viva Engage. If you don't have access to the new Viva Engage community, fill out this form (https://aka.ms/JoinD365commerceVivaEngageCommunity) to be added and stay engaged in the latest discussions.

This article describes how to extend a theme from a base theme for a Microsoft Dynamics 365 Commerce e-commerce site.

By using the Dynamics 365 Commerce online store extensibility software development kit (SDK), you can create either standalone themes or themes that extend a base theme. For example, you can have a base theme that defines Cascading Style Sheets (CSS) styles for modules, module view extensions, and module definition extensions. You can then have a different theme, or even a set of themes, that adds changes on top of the base theme. This capability is helpful when a single Dynamics 365 environment has multiple online sites that use different theme branding.

Specify a base theme

To specify the base theme for a theme, edit the theme definition file, and add a $ref section that points to the base theme.

In the following example, the $ref section references the fabrikam sample theme included as part of the module library.

{
    "$ref": "@msdyn365-commerce-modules/fabrikam-design-kit/dist/lib/modules/fabrikam/fabrikam.definition.json",
    "$type": "themeModule",
    "description": "This is SDK template theme module",
    "friendlyName": "adventureworks",
    "name": "adventureworks"
}

Examples

In the following example, use the add-theme command-line interface (CLI) command to create a base theme.

yarn msdyn365 add-theme base

Here's the definition file for the base theme that you create.

basetheme.definition.json

{
    "$type": "themeModule",
    "description": "This is SDK template theme module",
    "friendlyName": "base",
    "name": "base"
}

Next, use the CLI command to create a theme named extended.

yarn msdyn365 add-theme extended

The definition file for the extended theme can now reference the base theme by using a relative path, as shown here.

extended.definition.json

{
    "$ref": "../base/base.definition.json",
    "$type": "themeModule",
    "description": "This is SDK template theme module",
    "friendlyName": "extended",
    "name": "extended"
}

Include base theme styles

By default, the extended theme doesn't include base theme styles. To include the base theme styles, add a reference in the extended.theme.scss file, as shown here. This example also shows how to add other styles.

extended.theme.scss

@import "../../base/styles/base.theme.scss";

body {
    background-color: red;
}

The following example resembles the previous example. It shows that you can also add a reference to the base theme in the extended.definition.scss.json file, if you want.

extended.definition.scss.json

{
    "$ref": "../../base/styles/base.definition.scss.json",
    "name": "extended"
}

Additional resources

Theming overview

Create a theme

Configure theme settings

Configure theme style presets

Extend a theme to add module extensions

Override a module library component in a theme

Add custom resources to your customization code