29 Next Theme Kit

Theme Kit is a cross-platform command line tool to build and maintain storefront themes with Sass Processing support on the 29 Next platform.

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 with 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.

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 dependecies to reduce potential conflicts or errors, more on creating a Python Virutal Environment.

Updating Theme Kit

Update to the latest version of Theme Kit with the following command:

pip install next-theme-kit --upgrade

⚠️ Important

As of version 1.0.2, the store authentication uses Oauth and requires creating a store Oauth App with theme:read and theme:write permissions.

Usage

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

Available Commands

• ntk init - initialize a new theme
• ntk list - list all available themes
• ntk checkout - checkout an existing theme
• ntk pull - download existing theme or theme file
• ntk push - push current theme state to store
• ntk watch - watch for local changes and automatically push changes to store
• ntk sass - process sass to css, see Sass Processing

Important - You must pass the apikey and store parameters for all commands if there is not an existing config.yml file in your current directory.

Init

Initialize a new theme which will create the theme on a store and create an initial config.yml file

ntk init --name="<Theme Name>" --apikey="<api key>" --store="<https://storedomain.com>"

Required flags without config.yml

Short	Long	Description
-a	--apikey	API Key used to connect to the store.
-s	--store	Full domain of the store.
-n	--name	Name of the new theme

List

List all themes installed on the theme.

ntk list --apikey="<api key>" --store="<https://storedomain.com>"

Required flags without config.yml

Short	Long	Description
-a	--apikey	API Key used to connect to the store.
-s	--store	Full domain of the store.

Checkout

Checkout a theme from your store to pull it into your directory.

ntk checkout --theme_id=<id> --apikey="<api key>" --store="<https://storedomain.com>"

Required flags without config.yml

Short	Long	Description
-a	--apikey	API Key used to connect to the store.
-s	--store	Full domain of the store.
-t	--theme_id	ID of the theme.

Pull

Pull a theme from your store to into your directory.

ntk pull --theme_id=<id> --apikey="<api key>" --store="<https://storedomain.com>"

Required flags without config.yml

Short	Long	Description
-a	--apikey	API Key used to connect to the store.
-s	--store	Full domain of the store.
-t	--theme_id	ID of the theme.

Push

Push all theme files from your local directory to the store.

ntk push --theme_id=<id> --apikey="<api key>" --store="<https://storedomain.com>"

Required flags without config.yml

Short	Long	Description
-a	--apikey	API Key used to connect to the store.
-s	--store	Full domain of the store.
-t	--theme_id	ID of the theme.

Watch

Watch for file changes and additions in your local directory and automatically push them to the store.

ntk watch --theme_id=<id> --apikey="<api key>" --store="<https://storedomain.com>"

Required flags without config.yml

Short	Long	Description
-a	--apikey	API Key used to connect to the store.
-s	--store	Full domain of the store.
-t	--theme_id	ID of the theme.

Sass

Process sass files to CSS files for inclusion in your storefront. See Sass Processing for more details.

ntk sass

Optional flags

Short	Long	Description
-sos	--sass_output_style	Options are nested, expanded, compact, or compressed

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.

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
│   ├── styles.css // reference this asset file in templates
├── sass
│   ├── _base.scss
│   ├── _variables.scss
│   └── styles.scss // processed to assets/main.css

Important - 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.

Configure Default Output Style

Change the default sass output style in config.yml, example below.

development:
  apikey: <api key>
  sass:
    output_style: compressed // options: nested, expanded, compact, or compressed
  store: <store url>
  theme_id: <theme id>