SuiteCommerce Theme Development: From Setup to Activation

SuiteCommerce themes control templates, Sass, skins, fonts, images, and theme-specific overrides for active extensions. They do not use the same tools or source structure as SuiteCommerce Advanced core code.

This guide follows Oracle NetSuite's current Theme Developer Tools workflow. Check the linked Oracle pages before setup because the tool archive and supported Node.js versions change by Commerce release.

Decide whether the change belongs in a theme

Use a theme for presentation changes such as:

• typography, spacing, colors, and responsive styles;
• changes to existing Commerce templates;
• fonts and theme-owned images;
• skin presets exposed through Site Management Tools;
• Sass or template overrides for an active extension.

Use an extension for new application behavior, JavaScript, SuiteScript, configuration, custom page types, or new templates and Sass that belong to a feature. This distinction matters most with fallback themes, which can replace existing Base Theme files but cannot introduce new templates or Sass files. Oracle directs developers to use an extension for those additions.

1. Install the correct Theme Developer Tools

Your account needs SuiteCommerce or SuiteCommerce Advanced (SCA), plus SuiteCommerce Extension Management. Themes are supported for SuiteCommerce and SCA Aconcagua or later.

In NetSuite:

1. Go to Documents > Files > File Cabinet.
2. Open SuiteBundles/Bundle 521562/.
3. Download the ThemeDevelopmentTools-<version>.zip file for your implementation.
4. Extract it into a dedicated top-level development directory.

Oracle's current setup page names ThemeDevelopmentTools-26.1.x.zip. Aconcagua and SCA 2018.2 require ThemeDevelopmentTools-18.2.1.zip. Do not use a current archive against an old SCA release without checking compatibility.

Oracle documents the current path in Set Up Theme Developer Tools.

Do not move or edit the Gulp files inside the extracted directory. Install the Node.js version listed for your Commerce release, then install Gulp and the archive's dependencies:

npm install --global gulp
npm install

gulp -v
gulp

Oracle's current Node table lists Node.js 20.10.0 for SuiteCommerce, SuiteCommerce MyAccount, SCA 2025.2, and SCA 2026.a. Older SCA releases require older Node versions. Check Install Node.js instead of guessing from the release year.

Use a role with fetch and deploy permissions. Administrator and SCDeployer have these permissions by default. Current Commerce tools use token-based authentication for accounts with two-factor authentication. See Developer Tool Roles and Permissions.

Oracle recommends separate extracted tool directories for sandbox and production. It also allows only one theme per top-level theme workspace, so use another directory when developing a second theme.

2. Choose how to start the theme

There are two supported paths.

Create a fallback theme

Oracle calls this the preferred method:

gulp theme:create

The generated theme uses "subtype": "fallback" in its manifest. It inherits files from the installed SuiteCommerce Base Theme. Add only the Base Theme files that you need to replace, preserving their file names.

A fallback theme has two constraints:

1. It can replace existing Base Theme templates and Sass, but it cannot add new templates or Sass. Put new feature files in an extension.
2. Assets are all or nothing. If the custom theme defines an assets entry, its asset folder replaces the Base Theme assets rather than merging with them.

Read Create a Custom Theme before choosing this route.

Fetch the active theme

You can also use an active published or custom theme as a baseline:

gulp theme:fetch

For accounts with account-specific domains:

gulp theme:fetch --account 123456
gulp theme:fetch --account 123456-sb1

The command asks for an authentication ID, account and role, website, and domain. It downloads the active theme plus template, Sass, and asset files from active extensions.

Commit or back up the workspace first. gulp theme:fetch clears the existing Workspace/ contents before downloading. It can erase uncommitted theme work.

Published theme source cannot be overwritten. A fetched published theme can serve as a baseline for a separately named custom theme.

See Fetch Active Theme Files.

3. Know the workspace

A fetched Base Theme has this shape:

Workspace/
├── SuiteCommerceBaseTheme/
│   ├── assets/
│   ├── Modules/
│   ├── Overrides/
│   ├── Skins/
│   └── manifest.json
└── Extras/
    ├── Extensions/
    └── application_manifest.json

The top-level tool directory also contains generated LocalDistribution/ and DeployDistribution/ folders after local testing and deployment. Do not edit either output folder.

Theme files have distinct jobs:

• Modules/ contains module-level Sass/ and Templates/ folders.
• assets/ contains theme fonts and images.
• Skins/ contains JSON skin presets that an administrator can select in Site Management Tools.
• Overrides/ contains theme-specific template and Sass overrides for extensions.
• manifest.json lists templates, Sass entry points and files, skins, assets, and overrides.
• Workspace/Extras/Extensions/ contains reference files for active extensions. Do not edit or remove those files directly.

See Theme Development Files and Folders and Anatomy of the Base Theme.

4. Make small, traceable changes

Start with the smallest set of files that can express the design. Copying every Base Theme file into a custom theme makes later reviews harder and hides which behavior you intended to change.

Sass

Use the variables and mixins supplied by the target Base Theme. Their names and module versions can change, so inspect the fetched source instead of copying variable lists from another release.

When editing Sass:

• keep selectors scoped to the component;
• preserve focus styles and usable color contrast;
• test long translated text and dynamic content;
• avoid !important unless you have traced the cascade and cannot remove the conflict;
• avoid importing the same partial into several application entry points by accident;
• check shopping, checkout, and My Account separately if the file can affect all three.

For a fallback theme, replace an existing Sass file with the same name and relative role as the Base Theme file. If the design needs a new Sass file, create an extension rather than forcing an unsupported manifest shape.

Templates

A .tpl file is a Handlebars template rendered with context supplied by SuiteCommerce. Before changing one:

1. Find its matching file in the Base Theme.
2. Identify child-view placeholders and data-action hooks.
3. Preserve accessibility attributes and form semantics.
4. Confirm every context value exists in the target release.
5. Keep translated strings inside the provided translation helper.

Do not invent template context fields. A template cannot read a value that its view does not supply. If the requirement needs new data or behavior, implement it through an extension and the public Extensibility API.

Extension overrides

Files under Workspace/Extras/Extensions/ are references. To change how an active extension looks, use Oracle's override method so the changed file lives under the theme's Overrides/ directory. The developer tools add detected overrides to the theme manifest during deployment.

An override is tied to the extension file it replaces. Recheck it whenever the extension is updated, and remove it if the extension is no longer active.

Skins

A skin preset is a JSON file under Skins/. Local theme testing does not apply skin changes or Sass variables exposed to Site Management Tools. Deploy and activate the theme on a test domain to verify them.

5. Treat the manifest as generated source

Workspace/<THEME>/manifest.json tells the tools which resources belong to the theme. You may need to edit it when adding resources to a non-fallback custom theme or changing skin labels.

Both local and deploy commands update the manifest. If you made a required manual edit, preserve it explicitly:

gulp theme:local --preserve-manifest
gulp theme:deploy --preserve-manifest

Review the manifest diff after each build. Do not paste a manifest from a different theme or Commerce release. See Edit the Theme Manifest.

6. Test locally

Run:

gulp theme:local

The task compiles the theme into LocalDistribution/, starts a local server, and watches existing Sass and template files. Open the local shopping, checkout, and My Account URLs for the target domain.

Restart gulp theme:local after adding a file or changing an extension override. The watch task recompiles changes to known Sass and template files, but it does not discover new files or process new overrides automatically.

Local testing covers frontend theme changes. It does not show skin changes or Sass variables exposed to Site Management Tools until the theme is deployed and activated.

Test at least:

• header, navigation, search, cart, and footer;
• product list and product detail pages;
• cart and every checkout step;
• signed-in and guest states;
• My Account pages if the theme targets them;
• empty, loading, validation, and error states;
• supported browsers, keyboard use, zoom, and mobile widths;
• any active extension with a theme override.

See Test a Theme on a Local Server.

7. Deploy and activate

Deploy from the top-level Theme Developer Tools directory:

gulp theme:deploy

For an account-specific sandbox domain:

gulp theme:deploy --account 123456-sb1

The command validates the theme, copies source into DeployDistribution/, updates the manifest, and uploads the theme files to NetSuite. It does not make the theme live.

Activate it separately:

1. Go to Commerce > Extensions > Extension Manager.
2. Create or edit an activation for the development website and domain.
3. Select the deployed theme and required extensions.
4. Activate and wait for compilation to finish.
5. Test the domain before changing a production activation.

Oracle recommends testing activations on a development domain before using a live domain. See Deploy a Theme to NetSuite and Activating Themes and Extensions.

Release checklist

Before production activation:

• Confirm the tool and Node.js versions match the Commerce release.
• Confirm the manifest target version and theme version.
• Back up or commit the workspace before any fetch.
• Review every file copied from the Base Theme.
• Test all target applications and active extension overrides.
• Deploy and activate first on a development or sandbox domain.
• Save screenshots and test notes for key page types.
• Keep the prior theme version available until post-release checks pass.

Command summary

# One-time setup
npm install --global gulp
npm install

# Preferred new-theme workflow
gulp theme:create

# Alternative: download the active theme and extension references
gulp theme:fetch

# Compile and serve locally
gulp theme:local

# Validate and upload to NetSuite
gulp theme:deploy

# Show commands supported by the downloaded tools
gulp

Use Oracle's Gulp command reference for supported flags. Commands such as theme:local --reload, theme:local --theme, sass:compile, and certificates:generate are not listed for the current Theme Developer Tools and should not be presented as portable SuiteCommerce commands.