Deploy a Theme to NetSuite

After testing and verifying your theme locally, deploy your theme to NetSuite so you can activate it for a website domain.

Watch the following help video for information about how to deploy a theme:

To deploy your theme to NetSuite:

In your local developer environment, open a command line or terminal and access the top-level development directory.
Run the following command:

gulp theme:deploy

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:deploy --account, see Theme Developer Gulp Commands.

Warning:
Potential data loss. In addition to compiling and deploying your theme, the gulp theme:deploy command updates the manifest.json file for the theme. This action overwrites any manual changes you made to this file. To preserve any manual changes to your manifest.json file, run the gulp theme:deploy --preserve-manifest command instead. See Theme Manifest for details on this file.

When prompted, enter the following information.

Unless otherwise noted, create all entries using only alphanumeric characters without spaces.

Note:

These prompts appear the first time you deploy a new theme to NetSuite. To reset the login information and fill in these prompts again, use the gulp theme:deploy --to command.

Prompt	Description
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 operation, 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 deploy to 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 you want to deploy to 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 deploy to 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.
Website	Choose the website associated with your domain.
Vendor	Enter the name of the vendor building this theme.
Name	Enter a name for your custom theme. This cannot contain special characters and spaces.
Fantasy Name	Provide a name for your theme as you want it to appear in the NetSuite user interface. This can contain special characters and spaces.
Version	Enter a version for your theme. Important: To take advantage of theme update requirements, assign a version number to your themes. Version numbers should follow this format, where `d` is a single digit: `dd.dd.dd`.
Description	Enter a brief description for your theme. The description appears in NetSuite when you select themes to activate.
Supported Products	Select the product or products (SuiteCommerce Online or SCIS) to which you are deploying. An asterisk () identifies a selected product. SuiteCommerce Online* applies to SuiteCommerce and SuiteCommerce Advanced. Use the spacebar key to select or deselect an option. Use the UP and DOWN arrow keys to scroll through the options. Toggle the A key to select or deselect all options.
Target Version	Using Commerce versioning schema, enter a string to declare the target versions to which this theme applies. The developer tools prompt you for a target version for each product specified earlier. Leaving these prompts blank results in compatibility with all versions of the associated Commerce products. See Declare Target Versions and SuiteScript 2.x Bundle Installation Script Type for more information.

Prompt

Description

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 operation, 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 deploy to 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 you want to deploy to 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 deploy to 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.

Website

Choose the website associated with your domain.

Vendor

Enter the name of the vendor building this theme.

Name

Enter a name for your custom theme. This cannot contain special characters and spaces.

Fantasy Name

Provide a name for your theme as you want it to appear in the NetSuite user interface. This can contain special characters and spaces.

Version

Enter a version for your theme.

Important:

To take advantage of theme update requirements, assign a version number to your themes. Version numbers should follow this format, where d is a single digit: dd.dd.dd.

Description

Enter a brief description for your theme. The description appears in NetSuite when you select themes to activate.

Supported Products

Select the product or products (SuiteCommerce Online or SCIS) to which you are deploying. An asterisk (*) identifies a selected product.

SuiteCommerce Online applies to SuiteCommerce and SuiteCommerce Advanced.

Use the spacebar key to select or deselect an option.
Use the UP and DOWN arrow keys to scroll through the options.
Toggle the A key to select or deselect all options.

Target Version

Using Commerce versioning schema, enter a string to declare the target versions to which this theme applies. The developer tools prompt you for a target version for each product specified earlier. Leaving these prompts blank results in compatibility with all versions of the associated Commerce products.

See Declare Target Versions and SuiteScript 2.x Bundle Installation Script Type for more information.

When you run the gulp theme:deploy command, the theme developer tools validate your customizations, copy them into a local DeployDistribution directory, and update the manifest file with any necessary overrides. The theme developer tools then upload the theme files to your NetSuite account, making them available for activation. For details, see What Happens When You Deploy a Theme?

Continue theme activation as outlined in Next Steps.

What Happens When You Deploy a Theme?

The deployment process uploads theme files and extension overrides (if applicable) to a location in your NetSuite File Cabinet. This process compiles the theme source files to test them before uploading them to NetSuite.

During the deployment process, the theme developer tools:

Copy all custom theme development files (modules, assets, and overrides) into the DeployDistribution folder in your local top-level development directory. If this directory does not exist, the developer tools create it.
Test and validate your customizations.
Update the manifest.json file to include any overrides.
Upload the theme source files to your NetSuite File Cabinet as bundled files (maintaining the same organizational structure).

Note:
The gulp theme:deploy command uploads your theme development files in groups of files called chunks. The default number of files in a single chunk is 80. If needed, you can configure the number of files in each chunk. See Troubleshooting the Developer Tools for more information.

When the theme source files are uploaded to the File Cabinet, NetSuite creates an Extension record for the custom theme. Like a published theme or extension, the source files have not compiled into usable files, but they are available for activation.

Note:

Extension overrides exhibit the following behaviors:

Your extension overrides always deploy as part of a custom theme. If you activate a custom theme but fail to activate any extension for which the theme includes overrides, the application ignores the overrides and your site functions normally.
If you deploy a theme with extension overrides and later activate new extensions for the same domain, your deployed customizations do not apply to the new extensions. You must update your theme to include these customizations.

Example

You download the source files for the active theme (SuiteCommerce Base Theme) and the active extension (PublishedExtension1). You follow best practices and procedures to customize your theme files and override your extension files. After testing on a local server, you decide to deploy your customizations.

You run the gulp theme:deploy command, and the theme development tools update the manifest file with any overrides, validate your customizations, and copy the contents of your theme directory to your DeployDistribution directory. The development tools then upload your development files to a location in your NetSuite File Cabinet. These files are not compiled into any usable runtime files, but they are now available for activation on a site and domain.

When you run the gulp theme:deploy command, the development tools prompt you for a new theme name, which you call MyCustomTheme1. Finally, the development tools rename your Workspace/SuiteCommerceBaseTheme directory to Workspace/MyCustomTheme1 and update the manifest and configuration file with the new theme name. This prepares the local environment to function with the new name.

Next Steps

After deploying theme files, you must activate the theme to apply it to your website domain. See Activating Themes and Extensions for instructions on activating your new theme for the domain or domains of your choice.

To deploy your theme to NetSuite:

What Happens When You Deploy a Theme?

Example

Next Steps

Related Topics