SuiteCommerce Theme Development: From Design to Deployment

Your SuiteCommerce store looks like every other NetSuite e-commerce site. Same layouts. Same color scheme variations. Same generic feel that screams "template."

We've built over 40 custom SuiteCommerce themes, and the difference between a generic-looking store and a brand-defining one comes down to understanding the theme architecture deeply. Sites with custom themes see 15-25% higher engagement metrics and stronger brand recall—because customers can tell when a store has personality versus when it's a checkbox implementation.

This guide takes you from design concept to deployed theme, covering every technical detail you need to build themes that perform and convert.

What Makes SuiteCommerce Themes Different

SuiteCommerce themes aren't just CSS files you drop into a folder. They're integrated packages combining SASS stylesheets, Handlebars templates, configuration files, and JavaScript modules. Understanding this architecture is essential before writing a single line of code.

Theme Architecture Overview

A SuiteCommerce theme consists of:

The theme system uses a fallback architecture—your custom theme only needs to include files you want to override. Everything else falls back to the base theme. This is powerful: you can create complete visual transformations with minimal file changes.

Fallback Themes: The Modern Approach

Since the 2024 releases, SuiteCommerce introduced fallback themes as the recommended customization approach. Instead of copying the entire base theme (and inheriting maintenance headaches), you create a lightweight theme that references the base and overrides only what you need.

// manifest.json for a fallback theme
{
    "name": "MyCustomTheme",
    "fantasyName": "My Custom Theme",
    "vendor": "stenbase",
    "version": "1.0.0",
    "type": "theme",
    "sub_type": "fallback",
    "target": "SCS",
    "skins": [
        {
            "name": "default",
            "file": "default.json"
        }
    ],
    "base_theme": "starter_theme"
}

The sub_type: "fallback" property tells SuiteCommerce to use inheritance. When a file isn't found in your theme, the system checks the base_theme.

Setting Up Your Development Environment

Before touching theme files, you need a properly configured development environment. This setup determines your productivity for the entire project.

Prerequisites

You'll need these installed on your development machine:

# Required versions (as of 2026)
Node.js: v18.x or v20.x LTS
npm: 8.x or higher
Gulp: 4.x (installed globally)

Installation verification:

node --version
# Should return v18.x.x or v20.x.x

npm --version
# Should return 8.x.x or higher

gulp --version
# Should return CLI version 2.3.0 or higher

Installing the Theme Development Tools

Download the Theme Development Tools from your NetSuite File Cabinet:

Navigation: File Cabinet → SuiteBundles → Bundle 387395 → ThemeDevelopmentTools-version.zip

Extract the archive and install dependencies:

# Navigate to extracted directory
cd ThemeDevelopmentTools-24.1.0

# Install npm dependencies
npm install

# Verify installation
gulp
# Should display available commands

Connecting to Your NetSuite Account

The first time you run a gulp command, you'll need to authenticate:

gulp theme:fetch

This prompts for:

• Website: Your SuiteCommerce domain
• Email: NetSuite login email
• Password: NetSuite password (or token if using token-based auth)
• Role: Select a role with Commerce permissions

The tool stores credentials in .nsdeploy for subsequent runs. Add this file to .gitignore—never commit credentials.

Project Structure

After fetching an existing theme or creating a new one, your project structure looks like this:

ThemeDevelopmentTools/
├── gulp/
│   ├── config/
│   │   └── config.json        # Deployment configuration
│   └── tasks/                 # Gulp task definitions
├── Themes/
│   └── MyCustomTheme/
│       ├── manifest.json       # Theme metadata
│       ├── Modules/           # SASS and template modules
│       │   ├── BaseSassStyles/
│       │   ├── Header/
│       │   ├── Footer/
│       │   ├── ProductDetails/
│       │   └── ...
│       ├── Skins/             # Skin configurations
│       │   └── default.json
│       └── assets/            # Images and static files
├── LocalDistribution/         # Local build output
├── node_modules/
├── package.json
└── .nsdeploy                  # Credentials (gitignore this)

Creating Your Theme

With your environment ready, let's build a theme from scratch. We'll create a fallback theme that establishes a new visual identity while maintaining all base functionality.

Initializing a New Theme

gulp theme:create

Follow the prompts:

• Theme name: mycustomtheme (lowercase, no spaces)
• Fantasy name: My Custom Theme (display name)
• Version: 1.0.0
• Base theme: Select the starter theme for your SuiteCommerce version

The tool generates the folder structure with a minimal manifest and starter files.

Understanding the Manifest

Your manifest.json controls how SuiteCommerce interprets your theme:

{
    "name": "mycustomtheme",
    "fantasyName": "My Custom Theme",
    "vendor": "yourcompany",
    "version": "1.0.0",
    "type": "theme",
    "sub_type": "fallback",
    "target": "SCS",
    "base_theme": "starter_theme",
    "scss": {
        "entry_points": {
            "shopping": "Modules/[email protected]/index-shopping.scss",
            "myaccount": "Modules/[email protected]/index-myaccount.scss",
            "checkout": "Modules/[email protected]/index-checkout.scss"
        }
    },
    "templates": {
        "application": {
            "Shopping": "Modules/[email protected]",
            "MyAccount": "Modules/[email protected]",
            "Checkout": "Modules/[email protected]"
        }
    },
    "skins": [
        {
            "name": "default",
            "file": "Skins/default.json"
        },
        {
            "name": "dark",
            "file": "Skins/dark.json"
        }
    ],
    "assets": {
        "img": "assets/img",
        "fonts": "assets/fonts"
    }
}

Key properties:

• entry_points: Define which SASS files compile for each application (Shopping, MyAccount, Checkout)
• templates: Map template overrides to applications
• skins: Define color/style variations customers can select
• assets: Reference static resources

SASS Architecture and Styling

SuiteCommerce uses SASS (SCSS syntax) for styling, with a structured variable system and modular organization. Mastering this architecture is the key to efficient theme development.

Color Variable System

SuiteCommerce defines colors using a semantic naming convention:

// Base color definitions (BaseSassStyles/_sc-colors.scss)

// Theme palette
$sc-color-theme: #5b7f8c;
$sc-color-theme-light: #9cb6bf;
$sc-color-theme-background: #e4eff5;
$sc-color-theme-background-light: lighten($sc-color-theme-background, 3.5%);
$sc-color-theme-border: desaturate(darken($sc-color-theme-background, 8%), 3%);

// Action colors
$sc-color-primary: #f15c28;
$sc-color-secondary: #15607B;
$sc-color-tertiary: #ffffff;

// Semantic colors
$sc-color-success: #4a7f35;
$sc-color-success-background: #eef7e4;
$sc-color-warning: #8e7728;
$sc-color-warning-background: #f9f5cd;
$sc-color-error: #C33C48;
$sc-color-error-background: #FFE9F1;
$sc-color-info: $sc-color-theme-light;

Best practice: Never use hex values directly in component styles. Always reference or extend these variables. This ensures skin variations work correctly.

Typography System

Typography uses t-shirt sizing from extra-small to triple-extra-large:

// Typography variables (BaseSassStyles/_sc-typography.scss)

// Font families
$sc-font-family-base: 'Open Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
$sc-font-family-heading: $sc-font-family-base;
$sc-font-family-monospace: 'Source Code Pro', Menlo, Monaco, monospace;

// Font sizes (using rem for accessibility)
$sc-font-size-xxxl: 2.5rem;    // 40px
$sc-font-size-xxl: 2rem;       // 32px
$sc-font-size-xl: 1.5rem;      // 24px
$sc-font-size-lg: 1.25rem;     // 20px
$sc-font-size-md: 1rem;        // 16px (base)
$sc-font-size-sm: 0.875rem;    // 14px
$sc-font-size-xs: 0.75rem;     // 12px

// Line heights
$sc-line-height-base: 1.5;
$sc-line-height-heading: 1.2;
$sc-line-height-tight: 1.25;

// Font weights
$sc-font-weight-light: 300;
$sc-font-weight-normal: 400;
$sc-font-weight-medium: 500;
$sc-font-weight-semibold: 600;
$sc-font-weight-bold: 700;

Creating a Custom Color Palette

Let's define a custom brand palette that replaces the defaults:

// Modules/[email protected]/_custom-colors.scss

// Brand colors
$brand-primary: #2D5A27;      // Forest green
$brand-secondary: #8B4513;    // Saddle brown
$brand-accent: #DAA520;       // Goldenrod

// Override SuiteCommerce theme colors
$sc-color-theme: $brand-primary;
$sc-color-theme-light: lighten($brand-primary, 20%);
$sc-color-theme-background: lighten($brand-primary, 55%);
$sc-color-theme-background-light: lighten($brand-primary, 60%);
$sc-color-theme-border: darken($sc-color-theme-background, 10%);

// Action color overrides
$sc-color-primary: $brand-accent;
$sc-color-secondary: $brand-secondary;

// Semantic colors (keep standard unless brand requires changes)
$sc-color-success: #2E7D32;
$sc-color-error: #C62828;
$sc-color-warning: #F9A825;

Module-Specific Styling

Each component in SuiteCommerce has its own SASS module. To customize the header:

// Modules/[email protected]/_header.scss

.header-main {
    background-color: $sc-color-theme;
    padding: $sc-spacing-md $sc-spacing-lg;
    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);

    &__logo {
        max-height: 60px;
        width: auto;
        
        @media (max-width: $sc-breakpoint-md) {
            max-height: 45px;
        }
    }

    &__navigation {
        display: flex;
        align-items: center;
        gap: $sc-spacing-lg;
    }

    &__nav-link {
        color: $sc-color-tertiary;
        font-size: $sc-font-size-sm;
        font-weight: $sc-font-weight-medium;
        text-decoration: none;
        text-transform: uppercase;
        letter-spacing: 0.5px;
        transition: color 0.2s ease;

        &:hover,
        &:focus {
            color: $sc-color-primary;
        }

        &--active {
            color: $sc-color-primary;
            border-bottom: 2px solid $sc-color-primary;
            padding-bottom: 4px;
        }
    }
}

SASS Entry Points

Entry points control which files compile into your final CSS bundles. Each application (Shopping, MyAccount, Checkout) has its own entry point:

// Modules/[email protected]/index-shopping.scss

// Base imports (order matters!)
@import 'sc-variables';        // All variable definitions
@import 'sc-mixins';           // Reusable style mixins
@import 'custom-colors';       // Your custom color overrides
@import 'sc-reset';            // CSS reset/normalize
@import 'sc-typography';       // Type styles
@import 'sc-grid';             // Grid system
@import 'sc-utilities';        // Helper classes

// Component imports
@import '../[email protected]/header';
@import '../[email protected]/footer';
@import '../[email protected]/product-list';
@import '../[email protected]/product-details';
@import '../[email protected]/cart';
@import '../[email protected]/facets';

// Custom module imports
@import '../[email protected]/custom-banner';
@import '../[email protected]/custom-promo';

Template Customization

SuiteCommerce uses Handlebars templates (.tpl files) for HTML structure. Templates receive data from Backbone views and render dynamic content.

Template Syntax Basics

{{!-- Modules/[email protected]/Templates/product_details_full.tpl --}}

<div class="product-details" itemscope itemtype="https://schema.org/Product">
    {{!-- Image gallery --}}
    <div class="product-details__gallery">
        {{#if images.length}}
            <div data-view="ProductDetails.ImageGallery"></div>
        {{else}}
            <img src="{{resizeImage thumbnail.url 'main'}}" 
                 alt="{{thumbnail.altimagetext}}"
                 class="product-details__main-image">
        {{/if}}
    </div>

    {{!-- Product info --}}
    <div class="product-details__info">
        <h1 class="product-details__name" itemprop="name">
            {{pageHeader}}
        </h1>

        {{#if showRating}}
            <div class="product-details__rating" data-view="Rating"></div>
        {{/if}}

        <div class="product-details__price" itemprop="offers" itemscope itemtype="https://schema.org/Offer">
            {{#if onSale}}
                <span class="product-details__price-original">
                    {{item._priceFormatted}}
                </span>
                <span class="product-details__price-sale" itemprop="price" content="{{item._price}}">
                    {{item._comparePriceFormatted}}
                </span>
            {{else}}
                <span class="product-details__price-current" itemprop="price" content="{{item._price}}">
                    {{item._priceFormatted}}
                </span>
            {{/if}}
            <meta itemprop="priceCurrency" content="{{currency}}">
        </div>

        {{!-- Quantity and Add to Cart --}}
        <div class="product-details__actions">
            <div class="product-details__quantity">
                <label for="quantity">{{translate 'Quantity:'}}</label>
                <input type="number" 
                       id="quantity" 
                       name="quantity" 
                       value="{{quantity}}" 
                       min="{{minimumQuantity}}"
                       class="product-details__quantity-input"
                       data-action="setQuantity">
            </div>

            <button class="product-details__add-to-cart {{#unless isReadyForCart}}disabled{{/unless}}"
                    data-action="addToCart"
                    {{#unless isReadyForCart}}disabled{{/unless}}>
                {{translate 'Add to Cart'}}
            </button>
        </div>
    </div>
</div>

Key Handlebars Helpers

SuiteCommerce provides custom helpers for common patterns:

{{!-- Translation (i18n) --}}
{{translate 'Add to Cart'}}
{{translate 'Items: $(0)' itemCount}}

{{!-- Image resizing --}}
{{resizeImage url 'thumbnail'}}
{{resizeImage url 'main'}}
{{resizeImage url 'zoom'}}

{{!-- URL generation --}}
{{objectToAtrributes item}}

{{!-- Conditional blocks --}}
{{#if condition}}...{{/if}}
{{#unless condition}}...{{/unless}}
{{#each collection}}...{{/each}}

{{!-- Child view placeholders --}}
<div data-view="ChildViewName"></div>

Creating Custom Templates

When overriding a template, copy the original and modify. Let's customize the product list item:

{{!-- Modules/[email protected]/Templates/product_list_item.tpl --}}

<div class="product-item {{#if item._isOnSale}}product-item--sale{{/if}}"
     data-track-productlist-item="{{item._id}}"
     data-sku="{{item._sku}}"
     itemscope 
     itemtype="https://schema.org/Product">

    {{!-- Sale badge --}}
    {{#if item._isOnSale}}
        <div class="product-item__badge product-item__badge--sale">
            {{translate 'Sale'}}
        </div>
    {{/if}}

    {{!-- New badge --}}
    {{#if item._isNew}}
        <div class="product-item__badge product-item__badge--new">
            {{translate 'New'}}
        </div>
    {{/if}}

    {{!-- Image --}}
    <a href="{{item._url}}" class="product-item__image-link">
        <img src="{{resizeImage item._thumbnail.url 'thumbnail'}}"
             alt="{{item._thumbnail.altimagetext}}"
             class="product-item__image"
             loading="lazy"
             itemprop="image">
        
        {{!-- Secondary image on hover (if available) --}}
        {{#if item._secondaryImage}}
            <img src="{{resizeImage item._secondaryImage.url 'thumbnail'}}"
                 alt="{{item._secondaryImage.altimagetext}}"
                 class="product-item__image product-item__image--hover"
                 loading="lazy">
        {{/if}}
    </a>

    {{!-- Content --}}
    <div class="product-item__content">
        <h3 class="product-item__name" itemprop="name">
            <a href="{{item._url}}">{{item._name}}</a>
        </h3>

        {{!-- Rating --}}
        {{#if showRating}}
            <div class="product-item__rating" data-view="Rating"></div>
        {{/if}}

        {{!-- Price --}}
        <div class="product-item__price" itemprop="offers" itemscope itemtype="https://schema.org/Offer">
            {{#if item._isOnSale}}
                <span class="product-item__price-original">{{item._priceFormatted}}</span>
                <span class="product-item__price-sale" itemprop="price" content="{{item._salePrice}}">
                    {{item._salePriceFormatted}}
                </span>
                <span class="product-item__savings">
                    {{translate 'Save $(0)' item._savingsFormatted}}
                </span>
            {{else}}
                <span class="product-item__price-current" itemprop="price" content="{{item._price}}">
                    {{item._priceFormatted}}
                </span>
            {{/if}}
        </div>

        {{!-- Quick add (optional) --}}
        {{#if enableQuickAdd}}
            <button class="product-item__quick-add"
                    data-action="quickAdd"
                    data-item-id="{{item._id}}">
                {{translate 'Quick Add'}}
            </button>
        {{/if}}
    </div>
</div>

Responsive Design Implementation

Mobile commerce accounts for over 70% of e-commerce traffic. Your theme must work flawlessly across devices.

Breakpoint System

SuiteCommerce defines standard breakpoints:

// Breakpoints (BaseSassStyles/_sc-variables.scss)

$sc-breakpoint-xs: 0;
$sc-breakpoint-sm: 576px;
$sc-breakpoint-md: 768px;
$sc-breakpoint-lg: 992px;
$sc-breakpoint-xl: 1200px;
$sc-breakpoint-xxl: 1400px;

// Media query mixins
@mixin media-breakpoint-up($breakpoint) {
    @media (min-width: map-get($breakpoints, $breakpoint)) {
        @content;
    }
}

@mixin media-breakpoint-down($breakpoint) {
    @media (max-width: map-get($breakpoints, $breakpoint) - 0.02px) {
        @content;
    }
}

Mobile-First Styling Pattern

Always write mobile styles first, then enhance for larger screens:

// Modules/[email protected]/_product-details.scss

.product-details {
    // Mobile base styles
    display: flex;
    flex-direction: column;
    gap: $sc-spacing-md;
    padding: $sc-spacing-md;

    &__gallery {
        width: 100%;
        order: 1;
    }

    &__info {
        width: 100%;
        order: 2;
    }

    &__name {
        font-size: $sc-font-size-xl;
        margin-bottom: $sc-spacing-sm;
    }

    &__actions {
        display: flex;
        flex-direction: column;
        gap: $sc-spacing-sm;
    }

    &__add-to-cart {
        width: 100%;
        padding: $sc-spacing-md;
        font-size: $sc-font-size-md;
    }

    // Tablet and up
    @media (min-width: $sc-breakpoint-md) {
        flex-direction: row;
        gap: $sc-spacing-xl;
        padding: $sc-spacing-lg;

        &__gallery {
            width: 55%;
            order: 1;
        }

        &__info {
            width: 45%;
            order: 2;
            position: sticky;
            top: 100px;
            align-self: flex-start;
        }

        &__name {
            font-size: $sc-font-size-xxl;
        }

        &__actions {
            flex-direction: row;
        }

        &__add-to-cart {
            width: auto;
            min-width: 200px;
        }
    }

    // Desktop
    @media (min-width: $sc-breakpoint-lg) {
        &__gallery {
            width: 60%;
        }

        &__info {
            width: 40%;
        }
    }
}

Touch-Friendly Elements

Ensure interactive elements meet minimum touch target sizes (44x44px per WCAG guidelines):

// Touch target sizing
.button,
.nav-link,
.product-item__quick-add {
    min-height: 44px;
    min-width: 44px;
    
    @media (min-width: $sc-breakpoint-lg) {
        min-height: 36px;
        min-width: auto;
    }
}

// Larger tap targets for mobile navigation
.mobile-nav {
    &__item {
        padding: $sc-spacing-md $sc-spacing-lg;
        min-height: 48px;
        display: flex;
        align-items: center;
    }

    &__link {
        width: 100%;
        font-size: $sc-font-size-md;
    }
}

Performance Considerations

Theme choices directly impact page speed. Every kilobyte of CSS and every DOM node affects Core Web Vitals.

SASS Optimization

Avoid deep nesting:

// Bad - compiles to verbose selectors
.header {
    .nav {
        .item {
            .link {
                &:hover {
                    color: red; // .header .nav .item .link:hover
                }
            }
        }
    }
}

// Good - flat, specific selectors
.header-nav__link {
    &:hover {
        color: $sc-color-primary;
    }
}

Use placeholder selectors for shared styles:

// Define once
%button-base {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    padding: $sc-spacing-sm $sc-spacing-md;
    border-radius: 4px;
    font-weight: $sc-font-weight-medium;
    transition: all 0.2s ease;
    cursor: pointer;
}

// Extend everywhere (no duplicate CSS generated)
.btn-primary {
    @extend %button-base;
    background: $sc-color-primary;
    color: white;
}

.btn-secondary {
    @extend %button-base;
    background: transparent;
    border: 1px solid $sc-color-secondary;
    color: $sc-color-secondary;
}

Template Performance

Minimize DOM depth:

{{!-- Bad - unnecessary wrapper divs --}}
<div class="wrapper">
    <div class="container">
        <div class="row">
            <div class="col">
                <div class="product-item">
                    <h3>{{name}}</h3>
                </div>
            </div>
        </div>
    </div>
</div>

{{!-- Good - semantic, minimal --}}
<article class="product-item">
    <h3 class="product-item__name">{{name}}</h3>
</article>

Lazy-load below-the-fold images:

{{!-- Add loading="lazy" to images below initial viewport --}}
<img src="{{resizeImage url 'thumbnail'}}"
     alt="{{altText}}"
     loading="lazy"
     decoding="async">

Critical CSS Considerations

For maximum LCP performance, inline critical CSS. While SuiteCommerce doesn't support this natively, you can structure your SASS to make critical styles identifiable:

// _critical.scss - styles needed for first paint
// Header, hero, above-fold product grid

// _deferred.scss - styles for below-fold and interactive elements
// Footer, modals, checkout forms

Creating Theme Skins

Skins allow customers to select color variations from Site Management Tools without code changes. This is powerful for A/B testing designs or seasonal themes.

Skin Configuration Structure

// Skins/default.json
{
    "name": "Default",
    "group_id": "default",
    "properties": {
        "colors": {
            "sc-color-theme": "#2D5A27",
            "sc-color-theme-light": "#4A8743",
            "sc-color-theme-background": "#E8F5E9",
            "sc-color-primary": "#DAA520",
            "sc-color-secondary": "#8B4513"
        },
        "typography": {
            "sc-font-family-base": "'Lato', sans-serif",
            "sc-font-family-heading": "'Playfair Display', serif"
        },
        "layout": {
            "header-height": "80px",
            "container-max-width": "1200px"
        }
    }
}

Creating a Dark Mode Skin

// Skins/dark.json
{
    "name": "Dark Mode",
    "group_id": "dark",
    "properties": {
        "colors": {
            "sc-color-theme": "#1A1A2E",
            "sc-color-theme-light": "#2D2D44",
            "sc-color-theme-background": "#0F0F1A",
            "sc-color-theme-background-light": "#1A1A2E",
            "sc-color-theme-border": "#3D3D5C",
            
            "sc-color-primary": "#FFD700",
            "sc-color-secondary": "#E0E0E0",
            "sc-color-tertiary": "#121212",
            
            "sc-color-text-primary": "#FFFFFF",
            "sc-color-text-secondary": "#B0B0B0",
            "sc-color-text-muted": "#707070"
        },
        "typography": {
            "sc-font-family-base": "'Inter', sans-serif"
        }
    }
}

SASS Integration with Skins

Your SASS must reference skin-configurable variables correctly:

// Use !default flag so skin values take precedence
$sc-color-theme: #2D5A27 !default;
$sc-color-primary: #DAA520 !default;
$header-height: 80px !default;

// Use variables in your styles
.header-main {
    height: $header-height;
    background-color: $sc-color-theme;
}

Local Development and Testing

Efficient local testing prevents endless deploy cycles. SuiteCommerce provides a local development server.

Running the Local Server

# Start local development server
gulp theme:local

# With live reload
gulp theme:local --reload

# Targeting specific theme
gulp theme:local --theme mycustomtheme

This spins up a local server (typically on port 7777) that proxies your NetSuite site while serving local theme files.

Testing Workflow

1. Start local server: gulp theme:local
2. Open browser: Navigate to https://localhost:7777
3. Accept certificate warning (self-signed cert for local HTTPS)
4. Make changes to SASS or templates
5. Refresh browser to see changes (or wait for live reload)

Debugging Tips

View compiled CSS:

# Check LocalDistribution folder for compiled output
ls -la LocalDistribution/css/

Validate SASS compilation:

# Compile only (don't start server)
gulp sass:compile

# Check for errors in terminal output

Template debugging in browser:

// In browser console, access Backbone views
SC.ENVIRONMENT.TEMPLATES // List all templates
SC.Application.getComponent('PDP').view // Access product detail view

Deployment Process

When your theme is ready, deploy to your NetSuite account for production use.

Pre-Deployment Checklist

Before deploying, verify:

• All SASS compiles without errors
• Templates render correctly at all breakpoints
• No console errors in browser dev tools
• Images optimized (WebP format where possible)
• manifest.json version updated
• Tested in Safari, Chrome, Firefox, Edge
• Mobile testing on real devices

Deploying to Sandbox

Always deploy to sandbox first:

# Deploy theme to sandbox
gulp theme:deploy

# Select sandbox environment when prompted
# Or specify in command:
gulp theme:deploy --to sandbox

Sandbox Testing

After sandbox deployment:

1. Navigate to Commerce → Websites → Manage
2. Select your website
3. Go to Themes tab
4. Activate your new theme
5. Test thoroughly before production deployment

Production Deployment

# Deploy to production
gulp theme:deploy --to production

Zero-downtime activation:

1. Deploy theme (doesn't affect live site yet)
2. Test on a non-published skin variation if possible
3. Activate theme during low-traffic period
4. Monitor for issues
5. Have rollback plan ready (previous theme still available)

Rollback Procedure

If issues arise post-deployment:

1. Go to Commerce → Websites → Manage
2. Select website → Themes tab
3. Activate previous theme version
4. Investigate issues in sandbox

Troubleshooting Common Issues

SASS Compilation Errors

"Undefined variable" error:

Error: Undefined variable: "$sc-color-theme"

Fix: Ensure variable definition files are imported before usage in entry points.

Template Not Found

Theme shows base template instead of custom:

Verify:

1. Template path matches exactly in manifest.json
2. Template file extension is .tpl
3. Module folder uses correct version notation (@1.0.0)

Styles Not Applying

CSS changes not visible:

1. Clear browser cache (hard refresh)
2. Check if SASS file is included in entry point
3. Verify no specificity conflicts with base styles
4. Check for typos in class names

Local Server Issues

"ECONNREFUSED" or certificate errors:

# Regenerate local certificate
gulp certificates:generate

# Clear node_modules and reinstall
rm -rf node_modules
npm install

FAQ

Q: How long does a custom theme project typically take?

A: A complete custom theme typically takes 4-8 weeks depending on complexity. Simple color/typography changes can be done in days. Full visual redesigns with custom templates take longer.

Q: Can I use CSS frameworks like Tailwind with SuiteCommerce?

A: Not recommended. SuiteCommerce's build system expects its SASS architecture. You can incorporate utility-class patterns within the existing structure, but replacing it entirely causes compatibility issues.

Q: Should I upgrade to fallback themes if I have an existing full theme?

A: Yes, when you next need significant theme changes. Fallback themes dramatically reduce upgrade maintenance. Plan this as a dedicated project—it's worth the investment.

Q: How do I handle custom fonts?

A: Upload fonts to assets/fonts, reference them in your SASS with @font-face declarations, and use the variable system for font-family assignments. Consider performance impact—each font file adds to page weight.

Q: Can multiple skins use different layouts, not just colors?

A: Skins primarily control variables, so layout changes are limited to what can be controlled by CSS values (spacing, widths, heights). For structural layout changes, you need template modifications.

Next Steps

Building a custom SuiteCommerce theme is a significant undertaking, but the results—stronger brand identity, better UX, improved conversions—justify the investment.

If you're starting a theme project and want expert guidance, our team has built custom themes for dozens of SuiteCommerce stores. We can help you avoid common pitfalls and deliver results faster.

Get a Free Theme Consultation →

Need immediate help with your SuiteCommerce theme? Contact our development team for expert assistance.