Developer Tools

Kibo eCommerce provides several command-line tools to make developing applications and themes across your local development environment and Dev Center easier. To install and use these tools, your system must meet the following requirements:

Refer to the following table for a list of Kibo eCommerce development tools and links to more information on installing and using them:

Third-Party Software Kibo eCommerce Tools
Yeoman
  • Kibo eCommerce Actions Generator—Generates the Kibo eCommerce application directory structure, JavaScript templates that correspond to the actions you choose to install, and a test framework for validating your code before uploading it to Dev Center.
  • Kibo eCommerce Theme Generator—Generates the Kibo eCommerce theme directory structure, common theme files, build process, and test framework for validating your code before uploading it to Dev Center. This tool also configures your local directory as a Git repository and can connect other theme Git repositories as remotes to make upgrading themes easier.
  • Kibo eCommerce Application Generator—Configures code in an existing application or theme directory with a new Dev Center application key so you can upload the files to your developer account.

Refer to the following topics for more information:

Grunt
  • mozutheme—Runs “compile” or “check” commands (depending on your configuration) during the build process. This task is built into the Theme Utility Helpers for compiling and maintaining Kibo eCommerce themes.
  • mozusync—Takes a Kibo eCommerce environment configuration (supplied either manually in Gruntfile.js or through mozu.config.json) and synchronizes application or theme files in a local directory with Dev Center.

Refer to the following topic for more information:

npm
  • Theme Utility Helpers—Provides a library of common tasks for checking, compiling, and maintaining Kibo eCommerce themes.
  • Arc.js Utility Helpers—Provides a library for running common tasks in Arc.js actions.
  • Arc.js Action Simulator—Provides unit and integration tests for Arc.js actions.
  • Sync Utility Helpers—Provides the library for the mozusync Grunt task.
  • Kibo eCommerce Node.js SDK—Provides the base library for all Node.js communication with the Kibo eCommerce API.
  • Kibo eCommerce Multipass—Provides an authentication storage plugin for the Kibo eCommerce Node.js SDK.

Kibo eCommerce Theme Generator

Kibo eCommerce themes are designed to leverage inheritance, so all of your theme development should extend the latest Kibo eCommerce Core theme. We recommend using the Kibo eCommerce Theme Generator to manage your theme assets. The Kibo eCommerce Theme Generator:

Create a New Theme

The Kibo eCommerce Theme Generator is a Yeoman plugin that generates the scaffolding (e.g., directory structure, reference files, and build files) necessary to package a Kibo eCommerce theme and upload it to Dev Center. It’s designed to augment, not overwrite, existing themes. If you have a theme that extends the Kibo eCommerce Core theme, you can safely run this tool in that directory without overwriting your existing files. Whenever Kibo eCommerce releases a Core theme upgrade, you can use this tool to merge changes from the Core theme ( or any other theme Git repository) with your theme.

To create a brand new theme that inherits from the latest Kibo eCommerce Core theme:

  1. Open a terminal (OS X) or a command prompt (Windows).
  2. Install the Yeoman command-line tool globally:
    npm install -g yo
  3. Install the Grunt command-line tool globally:
    npm install -g grunt-cli
  4. Install the Kibo eCommerce Theme Generator globally:
    npm install -g generator-mozu-theme
  5. Create a new folder for your theme on your local machine and navigate to it:
    mkdir your_theme && cd your_theme
  6. Run the Yeoman generator inside your theme directory:
    /your_theme/$ yo mozu-theme
  7. Note: If you have an old version of the tool installed, you’ll be prompted to update it. Press <Ctrl+C> to exit the application and enter the following command: npm install -g generator-mozu-theme
  8. Select Brand new theme.
  9. Enter the public name of your theme.
  10. (Optional) Enter a short description of your theme.
  11. Enter the initial version.
  12. Select Mozu Core Theme as the base theme from which your new theme will inherit.
  13. Select which version of the Kibo eCommerce Core theme from which your new theme will inherit.
  14. Enter your theme’s Dev Center Application Key.
  15. Note: If you’re using a package other than Release, make sure you enter the correct Application Key. Package names are appended to the Application Key of each package for identification purposes. The build tools rely on the Application Key to upload files to the right place in Dev Center.

  16. Enter your Developer Account login email.
  17. Enter your Developer Account password.
  18. Select your developer account.

You now have a blank theme based on the latest Kibo eCommerce Core theme, which you can modify, build, and upload to Dev Center. Since the Kibo eCommerce Core theme Git repository is connected to this Git repository as a remote, you’ll be able to merge upstream updates from the Core theme with your theme in the future.

Although the Kibo eCommerce Theme Generator is the recommended method for creating and uploading themes, you can also complete the process manually. To manually upload theme files from within Dev Center:

  1. Compress your local theme project into a .zip file.
  2. Log in to Dev Center.
  3. Click Develop > Themes.
  4. Double-click the theme where you want to upload files.
  5. Click the Packages tab.
  6. Select the package you want to upload files to from the Active Package drop-down menu.
  7. Click More > Upload.
  8. Drag and drop your theme .zip file into the Upload files dialog box.
  9. Wait for confirmation that the upload is complete.
  10. Click Done.
  11. You should see the contents of your theme in the Packages tab.

Merge Updates from the Latest Kibo eCommerce Core Theme

If the latest Kibo eCommerce Core theme is already connected to your repository as a remote, you can merge changes from the Core repository into your theme. You must resolve any merge conflicts that arise and commit your changes to complete the upgrade process. Kibo eCommerce recommends conducting user acceptance, automated unit, and end-to-end testing of your site to ensure the latest Core theme works for your site.

To merge updates from the latest Kibo eCommerce Core theme:

  1. Examine the merged Github Pull Requests or Theme Release Notes to see what individual features are coming over from the latest Core theme. You can also use the Compare View in Github to compare different versions of the Kibo eCommerce Core Theme.
  2. Open a terminal or command prompt and navigate to your local theme directory.
  3. Enter grunt mozutheme:check to see if any updates are available.
  4. Select the version you’d like to merge with your theme and use the following command syntax to merge: git merge <commitID>
  5. Replace <commitID> with the value displayed next to the selected version:
  6. Resolve all merge conflicts and ensure your repository is in a clean state before proceeding. 
  7. Install your upgraded Core-based theme on a development sandbox and activate it.
  8. Activate Debug Mode in the storefront by adding the query parameter debugMode=true to any storefront URL. For example, yourSite.com/about-us?debugMode=true.
  9. Visually examine your theme for problems.
  10. Test your site for issues:
    • View a category
    • Search for products
    • Configure a product
    • Manipulate the cart
    • Check out and place an order
    • Make changes to your account page, etc.
  11. Make any necessary corrections based on visual or console errors.
  12. Continue testing and developing until your theme is free from errors and regressions.

Upgrade a Legacy Theme

You must manually upgrade themes that extend legacy versions of the Kibo eCommerce Core theme (version 8 and earlier) to use the latest Core theme instead. The Kibo eCommerce Theme Generator connects the latest Core theme to your repository as a remote so you can merge changes from the Core Git repository into your theme. You must resolve all merge conflicts and commit your changes to complete the upgrade process. Kibo eCommerce recommends conducting user acceptance, automated unit, and end-to-end testing of your site to ensure the latest Core theme works for your site.

To upgrade a legacy theme:

  1. Examine the merged Github Pull Requests or Theme Release Notes to see what individual features are coming over from the latest Core theme. You can also use the Compare View in Github to compare different versions of the Kibo eCommerce Core Theme.
  2. Run the Kibo eCommerce Theme Generator to upgrade your theme to inherit from the latest Core theme:
    1. Open a terminal or command prompt and navigate to your local theme directory.
    2. Enter yo mozu-theme.
    3. Select Upgrade now.
    4. Resolve all merge conflicts and ensure your repository is in a clean state before proceeding.
  3. Install your upgraded Core-based theme on a development sandbox and activate it.
  4. Activate Debug Mode in the storefront by adding the query parameter debugMode=true to any storefront URL.
  5. Visually examine your theme for problems.
  6. Test your site for issues:
    • View a category
    • Search for products
    • Configure a product
    • Manipulate the cart
    • Check out and place an order
    • Make changes to your account page, etc.
  7. Make any necessary corrections based on visual or console errors.
  8. Continue testing and developing until your theme is free from errors and regressions.

Build and Sync Files with Dev Center

You need to build and upload your theme files to Dev Center in order to apply your theme to a site. You can manually compress and upload your theme files, but we recommend using the theme build tools instead. To prepare and upload your theme files using the build tools:

  1. Open a terminal (OS X) or a command prompt (Windows).
  2. Navigate to the root directory containing your theme files.
  3. Run a Grunt plugin command:

What does grunt do and what are the common options you can use with it?

grunt grunt build-production grunt mozusync:wipe && grunt grunt watch

Kibo eCommerce Application Generator

You may download a Kibo eCommerce theme, application, or Arc.js action from a colleague or from a public repository that hasn’t been configured to sync with Dev Center. You can configure existing code to upload to your Kibo eCommerce Developer Account just by adding a mozu.config.json file in the working directory.

Configure an Existing Theme to Sync with Dev Center

  1. Open a terminal (OS X) or a command prompt (Windows).
  2. Install the Yeoman command-line tool globally:
    npm install -g yo
  3. Install the Kibo eCommerce Application Generator globally:
    npm install -g generator-mozu-app
  4. Navigate to your local working directory.
  5. Run the generator:
    yo mozu-app

It will prompt you only for the information it needs to create a configuration file. It will not store your password in plain text; it only uses your password to download your list of developer accounts at the time that it runs.

Options