Deploying to the Spiff Commerce Hub

This page will guide you on how to upload your theme once you've reached a point where you're ready to test your it on the Spiff Commerce platform.

This guide assumes you've followed the steps in the Getting Started page.

Configuring your project for deployment

All themes are expected to have a spiffTheme.json file in the root, which needs to be present in the deployed code. This file lists all of the files that the Theme requires to have been loaded into the page in order for the Theme to load.

Here's an example that lists the necessary files for the project from the previous section:

/spiffTheme.json
{
    "launchData": {
        "targetFiles": [
            {
                "type": "Javascript", // Case sensitive
                "filename": "assets/index.js", // Path is relative to your output directory
                "mimeType": "text/javascript"
            },
            {
                "type": "CSS",
                "filename": "assets/index.css",
                "mimeType": "text/css"
            }
        ]
    }
}

Using the Vite plugin

If you're using Vite, you can use the built-in plugin function from @spiffcommerce/theme-bridge to automatically build the spiffTheme.json file.

By default, this will automatically populate the launchData.targetFiles field with all CSS files, and all required JavaScript files. It will also set the base field in your Vite config to "".

/vite.config.ts
import { spiffThemePlugin, ThemeFileType } from "@spiffcommerce/theme-bridge";

export default defineConfig({
    plugins: [
        preact(),
        // Call the plugin function, optionally passing in an options object.
        // All fields are optional.
        spiffThemePlugin({
            // Set to false to disable automatic generation of the `targetFiles` array.
            autoGenerateTargetFiles: true,
            // If `autoGenerateTargetFiles` is `true`, this will override the configuration
            // for the file (matched by output name). Otherwise you must list all files manually.
            targetFiles: [{
                type: ThemeFileType.Javascript,
                mimeType: "text/javascript",
                filename: "assets/manualPreloadScript.js",
                preload: true,
            }]
        })
    ],
    build: {
        rollupOptions: {
            emptyOutDir: true,
        },
    },
});

Copying the spiffTheme.json file

If you're not using Vite, or if you wish to manually build your spiffTheme.json file, you can instead opt to have the file copied across. The information below is specifically for Vite/Rollup, but the concept can be carried across to any bundler.

tip

To get JSON schema validation for the spiffTheme.json files in Visual Studio Code, install our Theme Development Extension.

By default, Vite outputs the files suffixed with their hash, which is not desirable for our use-case so we'll need to prevent Vite from doing this. We'll also need to get Vite to copy the spiffTheme.json file across to our output.

To achieve these goals, we're going to manually specify the output file name structure, and add rollup-plugin-copy to our project as a dev dependency to copy extra files to the output automatically.

yarn add -D rollup-plugin-copy

/vite.config.ts
// ... other imports
import copy from "rollup-plugin-copy";

export default defineConfig({
    base: "",
    plugins: [
        preact(),
        copy({
            targets: [
                {
                    src: "spiffTheme.json",
                    dest: "dist", // Output directory of the build
                },
            ],
            hook: "writeBundle",
        }),
    ],
    build: {
        rollupOptions: {
            emptyOutDir: true,
            output: {
                // Specify static file names
                entryFileNames: "assets/[name].js",
                chunkFileNames: "assets/[name].chunk.js",
                assetFileNames: "assets/[name].[ext]",
            },
        },
    },
});

Automatically bundling your build

To upload your build to the Spiff Commerce Hub, you'll need to provide it as a .zip file. You can automate this process in a number of ways, but for this guide we're going to use bestzip. Update your build script in your package.json file to run bestzip after the build completes.

yarn add -D bestzip

/package.json
{
    "scripts": {
        // Navigate into 'dist' to ensure the contents will be at the root of the .zip
        "build": "tsc && vite build && cd dist && bestzip dist.zip *",
    }
}

Uploading to Hub

With your project built and zipped, you can now upload your files to Hub.

Open up your theme from the Themes page, from the Themes navigation menu item. If you haven't already done this, click "NEW THEME", give your theme a name, then save it and re-open it.
Under the "Theme Versions" section on your theme's edit page, click "NEW VERSION" to upload the first version of your theme.
Give the version a name. All version names must be unique within that theme. There are no strict naming conventions, but we recommend using a consistent pattern since this will be shown to users when they install the theme.
Upload the .zip file created from the build process. You'll be presented with a basic list of the files and configuration fields you've provided, so you can review them before submitting.
- If there's anything wrong with your .zip file, you'll be notified. Double-check that the spiffTheme.json file is in the root of the .zip, and that you've listed some targetFiles.
Click "SUBMIT" to upload your assets.
Your version will be marked as processing, which usually only takes a moment.
Once your version has finished processing, click "PUBLISH" to enable users to apply this version to their Installs.

Using your theme

In order to use your theme, you'll need to create an Install on your account.

Open up the Theme Installs page, from the Themes navigation menu item.
Click "INSTALL THEME", and select your theme from the modal. This will make a new Install of your theme on your Partner account, and redirect you to the list of configurations for the Install.
Create a new Configuration, or select the Default Configuration that is automatically created for you.
Select the version you just published in the "Version" field.
Click "SAVE"

Applying to an Integration

warning

To use Marketplace Themes with external integrations (e-commerce websites), you'll need to ensure you're using Application Keys. If an Application Key is not present when launching the experience, it will fall back to our internal themes.

Once you've configured your Install, you can use your configuration on any of your Integrations.

To test it internally before deploying to your site, you can use the Internal integration that should be automatically created. If one doesn't exist, try opening up one of your Products and creating a design.

Open the Integrations, from the Partner navigation menu item. Select the Integration you wish to edit.
Scroll to the bottom of the page, to the Marketplace Themes section.
Select your Theme Install, then select your Install Configuration.
Click "SAVE CHANGES"

That's it! Now whenever this Integration is used, it will open your Theme instead of our internal ones.

Enhancing Customizability

When you're developing your theme, you may wish to provide Partners a way to customize the look and feel of your theme. For example, giving Partners a way to specify a custom logo, or a custom background color.

Inside the spiffTheme.json file you can specify a Configuration Schema, which allows you to list any number of custom fields that you want the Partner to be able to customize.

/spiffTheme.json
{
    "launchData": {
        "targetFiles": [
            ...
        ]
    },
    "configurationSchema": {
        "fields": [
            {
                "type": "Text",
                "key": "custom-title",
                "title": "Custom Title",
                "required": true
            },
            {
                "type": "Asset",
                "key": "logo",
                "title": "Custom Logo",
                "assetType": "Image"
            },
            {
                "type": "Color",
                "key": "background-color",
                "title": "Background Color",
                "defaultValue": "#fff"
            },
            {
                "type": "Number",
                "key": "max-quantity",
                "title": "Maximum Quantity",
                "defaultValue": "4"
            },
            {
                "type": "Select",
                "key": "layout-direction",
                "title": "Layout Direction",
                "defaultValue": "horizontal",
                "options": [
                    {
                        "key": "horizontal",
                        "value": "Horizontal"
                    },
                    {
                        "key": "vertical",
                        "value": "Vertical"
                    }
                ]
            }
        ]
    }
}

These fields will be made available on the context that is passed to your theme, on the configuration object.

warning

All field values will always be represented as a string. This includes the defaultValue in your schema, and the value fields present on each field in the configuration object present on the context.

Field Type	Description	Parameters
Asset	An Asset that lives in Spiff.	title, key, assetType*, required
Boolean	True/False value.	title, key, required OR defaultValue
Color	A CSS Color Value.	title, key, required OR defaultValue
Heading	A heading to display in the configuration form. Non-editable.	title*
Number	A floating-point number.	title, key, required OR defaultValue
Select	Displays a drop-down for the Partner to choose from a list of options. Each option is an object with a key and value.	title, key, options*, required OR defaultValue
Text	A String value.	title, key, required OR defaultValue, multiLine

Using the Vite plugin

If you're using the Vite plugin from @spiffcommerce/theme-bridge, you can pass the configuration schema object to the plugin function and it will write the JSON representation of your schema into your spiffTheme.json file.

/src/configurationSchema.ts
import { AssetType, FieldType, ThemeConfigurationSchema } from "@spiffcommerce/theme-bridge";

export const configurationSchema: ThemeConfigurationSchema = {
    fields: [
        {
            type: FieldType.Asset,
            assetType: AssetType.Font,
            key: "font",
            title: "Font",
        },
        {
            type: FieldType.Color,
            key: "textColor",
            title: "Text Color",
            defaultValue: "#292929",
        },
        {
            type: FieldType.Color,
            key: "primaryColor",
            title: "Primary Color",
            defaultValue: "#c2c2c2",
        },
        {
            type: FieldType.Color,
            key: "secondaryColor",
            title: "Secondary Color",
            defaultValue: "#ffffff",
        },
    ],
};

/vite.config.ts
import { spiffThemePlugin } from "@spiffcommerce/theme-bridge";
import { configurationSchema } from "./src/configurationSchema"

export default defineConfig({
    plugins: [
        spiffThemePlugin({
            configurationSchema: configurationSchema,
        }),
    ],
});

Configuring your project for deployment​

Using the Vite plugin​

Copying the spiffTheme.json file​

Automatically bundling your build​

Uploading to Hub​

Using your theme​

Applying to an Integration​

Enhancing Customizability​

Using the Vite plugin​

Configuring your project for deployment

Using the Vite plugin

Copying the spiffTheme.json file

Automatically bundling your build

Uploading to Hub

Using your theme

Applying to an Integration

Enhancing Customizability

Using the Vite plugin