Next Commerce Theme Kit

Theme Kit is a command line tool for developers to build and maintain storefront themes programmatically, allowing theme developers to:

• Work on theme templates and assets using their local code editor or favorite IDE.
• Use git version control to work on a theme collectively with many theme collaborators.
• Use a pipeline to manage deployments of theme updates.

Installation

Theme Kit is a Python package available on PyPi.

If you already have python and pip, install with the following command:

pip install next-theme-kit

Mac OSX Requirements

See how to install python and pip with HomeBrew. Once you have completed this step you can install using the pip instructions above.

Windows Requirements

• Option 1 (Recommended) — Windows 10 and above feature WSL (Windows Subsystem for Linux) which provides a native Linux environment, see how to Install WSL with Ubuntu. Once you have installed WSL, follow the best practice guides to configure and use with VS Code and then follow the pip instructions above to install Theme Kit.
• Option 2 — Installing python in Windows natively can be done through the Windows App Store. Recommend using Windows Powershell. This route is a little more tricky and some knowledge on how to manage Python in Windows will be required.

[!TIP] Use Python Virtual Environments — For Mac, Windows, and Linux, it's a best practice to use a Python Virtual Environment to isolate Python packages and dependencies to reduce potential conflicts or errors, more on creating a Python Virtual Environment.

Setup

Connect ntk to a store in three steps.

1. Create the API Key

Store authentication uses OAuth 2.0 and requires creating a store OAuth App with the themes:read and themes:write permissions.

1. In the Storefront admin, go to Settings > API Access.
2. Click Create App.
3. Give the app a name and assign a user.
4. In the Permissions tab, enable themes:read and themes:write.
5. Save. Copy the generated API key — you will need it in the next step.

2. Configure Theme Kit

ntk reads its connection settings from two places: command flags (--apikey, --store, --theme_id) and the config.yml file in your theme directory. You do not need to create config.yml by hand — ntk checkout and ntk init write it for you, and after that commands run without flags:

development:
  apikey: <api key>
  store: https://{store}.29next.store
  theme_id: <theme id>

[!WARNING] Keep the API key out of source control. Do not commit config.yml to git if it contains the key.

[!TIP] For CI or scripts, set the API key with the NTK_APIKEY environment variable instead of a flag or config.yml. The key is resolved in this order: NTK_APIKEY, then --apikey, then config.yml. A key from NTK_APIKEY is never written to config.yml.

[!NOTE] config.yml supports multiple environments. Commands use the development entry by default; pass -e / --env to target another environment (for example ntk push --env=production). The [development] prefix in command output is the active environment.

3. Connect to a Theme

Work from a copy of an existing theme rather than an empty directory — a complete theme is the reference for the required directories, templates, and settings.

Work on a theme already on the store — ntk checkout downloads the theme into your current directory and writes config.yml:

ntk checkout --theme_id=<id> --apikey="<api key>" --store="https://{store}.29next.store"

Add a new theme to the store — start from a copy of an existing theme, such as the Intro Bootstrap starter theme, then register it as a new theme with ntk init and upload the files with ntk push:

ntk init --name="<Theme Name>" --apikey="<api key>" --store="https://{store}.29next.store"
ntk push

Usage

With the package installed, you can now use the commands inside your theme directory and work on a storefront theme.

Browse Store Themes

To see what themes exist on the store, run ntk list to print the theme ID and name of each, with the active theme marked.

ntk list

Output looks like:

[development] Available themes:
[development] 	[42] 	Spring Launch
[development] 	[43] 	Holiday Promo (Active)

If you do not have a config.yml, also pass --apikey and --store.

Work on an Existing Theme

To start working on a theme that already exists on the store, ntk checkout downloads it into your directory and writes config.yml with the theme ID.

ntk checkout --theme_id=<id>

--theme_id / -t is required. If you do not have a config.yml, also pass --apikey and --store:

ntk checkout --theme_id=<id> --apikey="<api key>" --store="https://{store}.29next.store"

ntk checkout differs from ntk pull in one way: checkout writes config.yml so the directory is ready for subsequent ntk push / ntk watch runs; pull downloads the same files without writing config.yml.

Add a New Theme to the Store

ntk init registers your current directory as a new theme on the store and writes a config.yml. It does not download or scaffold any files — run it inside an existing theme codebase, then ntk push to upload the files.

[!WARNING] Building a theme from an empty directory is not advised. Start from a copy of a complete theme — the Intro Bootstrap starter theme or an existing theme from your store via ntk checkout.

ntk init --name="<Theme Name>"

--name / -n is required. If you do not have a config.yml yet, also pass --apikey and --store:

ntk init --name="<Theme Name>" --apikey="<api key>" --store="https://{store}.29next.store"

On success, ntk init logs the new theme ID and name, and persists the theme ID into config.yml so subsequent commands can omit --theme_id.

Sync Files to the Store

To sync files between your local directory and the store, use ntk push to upload and ntk pull to download. Both upload or download the whole theme by default, and both accept file paths as positional arguments to limit the operation to specific files.

[!NOTE] File paths are relative to the theme root. ntk push only uploads files inside the theme directories (assets, configs, layouts, locales, partials, sass, templates) with valid theme file extensions — a path outside of them is skipped silently, not reported as an error. ntk pull still downloads the checkout directory, but ntk push skips it: the store does not accept uploads to it.

Watch for File Changes

ntk watch monitors your theme directory and automatically pushes changed files to the store. Use it while you develop — save a file and the change is uploaded moments later.

ntk watch

On start, ntk watch logs the store, theme ID, a preview-theme URL, and the directory it is watching. Press Ctrl + C to stop.

[!WARNING] Deletes sync too — deleting a local file while ntk watch is running deletes that file from the theme on the store.

[!NOTE] ntk watch only uploads files with valid theme extensions. It does not accept file arguments. To scope changes to specific files, run ntk push with file paths instead.

Sass Processing

Theme kit includes support for Sass processing via Python Libsass. Sass processing includes support for variables, imports, nesting, mixins, inheritance, custom functions, and more.

[!WARNING] Sass processing is only supported on local, files in the sass directory are uploaded to your store for storage but cannot be edited in the store theme editor.

How it works

1. Put scss files in top level sass directory.
2. Run ntk sass or ntk watch to process theme sass files.
3. Top level scss files will be processed to css files in the asset directory with the same name.

Example Theme with Sass Structure

├── assets
│   ├── main.css // reference this asset file in templates
├── sass
│   ├── _base.scss
│   ├── _variables.scss
│   └── main.scss // processed to assets/main.css