1. Commerce
  2. Commerce Developer Documentation
  3. Develop Themes
  4. Develop Your Theme
  5. Fetch Active Theme Files

Fetch Active Theme Files

To create a theme, you first download files for the currently active theme to use as the baseline for your own custom theme. You can download files of any published theme or any previously deployed custom theme.

Warning:

When you fetch a theme, the developer tools download the active theme’s development files to your theme directory. This action overwrites any theme files currently stored in your local workspace. This can result in loss of development files if you are not careful.

Prerequisites

Before you can fetch active theme files, you need to:

To fetch the active theme and extension files:

  1. Open a command line or terminal.

  2. Access the top-level theme development directory you created when you downloaded the developer tools.

  3. Enter the following command:

    gulp theme:fetch

    Note:

    For release 2021.2.1 and later accounts that have account-specific domains, specify your account number with the gulp command to enable access to the NetSuite account. For more information about using gulp theme:fetch --account, see Theme Developer Gulp Commands.

  4. When prompted, enter the following information:

    Authentication ID

    Enter an ID to represent your NetSuite account and role.

    If you already created an authentication ID in a previous fetch or deploy, the theme developer tools do not prompt you for an ID and continue to use the existing ID for each subsequent fetch or deploy.

    To fetch from a NetSuite account that is different from the account used to create the existing authentication ID, use the --to parameter. When you use the use the --to parameter, you can choose a different authentication ID or create a new one. For more information, see Token Based Authentication.

    Account and Role

    If you are creating a new authentication ID, you need to select the NetSuite account and role to use with that new authentication ID. If using an existing ID, you are not prompted for this information.

    In NetSuite, select the account that contains the files you want to fetch and the role you want to use for authentication. Click the Allow button to generate the authentication token and secret.

    Note:

    You must specify a role that provides the permissions needed to fetch from NetSuite. By default, the Administrator and SCDeployer roles provide these permissions. To learn more, including how to create a custom role that provides the required permissions, see Developer Tool Roles and Permissions.

    Choose Your Website

    Select your website that includes the domain you are customizing.

    Choose Your Domain

    Select your domain with the active themes and extensions you want to download.

    When you run the gulp theme:fetch command, the theme developer tools download all editable theme-related files for the active theme and place them in your theme workspace. For details see What Happens When You Fetch an Active Theme?

    Continue theme development as outlined in Next Steps.

What Happens When You Fetch an Active Theme?

When you run the gulp theme:fetch command, the theme developer tools:

  • Create the Workspace directory in your theme development directory. If the Workspace directory already exists, the developer tools clear its contents before downloading. This action overwrites any files currently stored in your local workspace with the files being fetched.

  • Download all theme-related HTML and Sass files for the active theme and store them in your workspace, by module, within a directory specific to the theme. For example, Workspace/<THEME_DIRECTORY>/Modules. The theme directory is intuitively named to match the name of the active theme.

  • Download all theme-related assets to Workspace/<THEME_DIRECTORY>/assets.

  • Download all theme-related skin preset files to Workspace/<THEME_DIRECTORY>/Skins.

  • If you are downloading a theme that includes previously deployed overrides, the developer tools download these into ../Workspace/<THEME_DIRECTORY>/Overrides.

  • Validate that all files declared in the theme’s manifest.json have been downloaded correctly. If any problems occurred, the developer tools list all missing files and direct you to execute the gulp theme:fetch command again.

If the chosen domain includes any active extensions when you fetch the active theme, the developer tools:

  • Download all extension-related HTML and Sass files for the active extensions and store them in your workspace, by module, within directories specific to each active extension. For example, Workspace/Extras/Extensions/<EXTENSION_DIRECTORY>/Modules. The extension directories are intuitively named to match the name of each active extension.

  • Download all extension-related assets to ../Workspace/Extras/Extensions/<EXTENSION_DIRECTORY>/assets.

When you fetch the active theme, you are basically downloading the HTML, Sass, and asset files for the active theme to use as a baseline for your own theme development. Because a published theme is protected by copyright, you cannot overwrite any files for that theme. You can, however, use an existing theme as a baseline for your own, which you later deploy as a unique theme. The SuiteCommerce Base Theme SuiteApp provides a good starting point for building your own theme.

Note:

Although you cannot overwrite a published theme, you can make any development changes to your own themes.

When you fetch a theme for a domain, the developer tools download the HTML, Sass, and asset files for the active theme plus any HTML, Sass, and asset files of any extensions active at the time you run the gulp theme:fetch command. The local server needs these files to compile your theme when testing locally. You also have the opportunity to override the HTML and Sass for the active extensions with custom changes or add new assets. Any overrides you declare affect the domain once activated. Be aware that this only affects your domain. You are not overwriting any published extension’s code.

Example:

Your domain has an active theme, SuiteCommerceBaseTheme, and an active extension, PublishedExtension1. Your vendor name is ACME. You run the gulp theme:fetch command and specify your domain.

In this example, your Workspace directory structure should look similar to following:

                 Workspace/
      Extras/
         Extensions/
            ACME/
               PublishedExtension1/
                  assets/
                  Modules/
                  manifest.json
               application_manifest.json
      SuiteCommerceBaseTheme/
         assets/
         Modules/
         Overrides/
         Skins/
         manifest.json

When the gulp processes are complete, your theme developer environment should look similar to the following:

File Types

Workspace Subdirectory

Theme-related HTML and Sass files

../SuiteCommerceBaseTheme/Modules/

Theme-related asset files

../SuiteCommerceBaseTheme/assets/

Theme-related skin presets

../SuiteCommerceBaseTheme/Skins/

Extension-related HTML and Sass source files (sorted by module)

../Extras/Extensions/ACME/PublishedExtension1/Modules/

Extension-related asset files

../Extras/Extensions/ACME/PublishedExtension1/assets/

Pre-existing extension overrides

../SuiteCommerceBaseTheme/Overrides/

Next Steps

After fetching active theme files, you can customize the files from the active theme, create new files, enable customization from the Site Management Tools, and more as described in the following topics:

For guidance about how best to customize your themes, see:

Related Topics

General Notices