Install the Storefront Toolkit

You can install the Storefront Toolkit on either MacOS or on Windows 10.

The Toolkit has certain prerequisite programs that must be in place before you can install it. The Toolkit installation itself is performed from the command line.

A video tutorial of an installation is available here.

After you have installed the Toolkit, you can use it to set up your workspace and your first theme.

Install prerequisite programs

Before you can install and use the Storefront Toolkit, you must install certain third-party programs as prerequisites. These include the Node.js environment and the node-sass library.

For MacOS

1. Node.js—Cross-platform JavaScript runtime environment for servers and applications. On MacOS, we recommend that you use the nvm application for installation. This application is a version manager for node.js, designed to be installed per-user, and invoked per-shell.

   To install nvm, run this command at the command line: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh \| bash

   For more information, check the github repository for nvm.

   Important: Version 4.0 and later of the Storefront Toolkit requires version 18.x or 16.x of Node.js and version 8.x of npm. To use custom components with this new Toolkit version, be sure to use @appdirect/sfb-theme-components npm library version 0.0.293 and above.Earlier versions (1.x.x to 3.x.x) require versions 10.x and 12.x of Node.js, and version 6.x.x of npm. Ensure that you use the correct versions of Node.js and npm for your version of the Toolkit.

2. Node-sass—This is a library that provides binding for Node.js to LibSass and it must be installed as a global dependency. To install it, run npm -g install node-sass from the command line.

3. Text editor—For code, markup, and prose, such as Sublime Text.

4. Xcode—Development environment for macOS containing a suite of software development tools.

5. Command line tools—Specifically for Xcode, it includes a package that enables UNIX-style development through Terminal by installing command-line tools and macOS SDK frameworks and headers. To download command line tools for Xcode

   1. Click Xcode in the top menu bar, then click Open Developer Tool > More Developer Tools.
   2. Enter your Apple ID password. The Downloads for Apple Developers page opens.
   3. Select and download the Command Line Tools that is compatible with your computer. You must download the package that is compatible with both your macOS and Xcode versions.
   4. Open the Command Line Tools folder and download the file.

For Windows 10

1. Node.js—Cross-platform JavaScript runtime environment for servers and applications. On Windows, we recommend that you use the node.js .msi setup file for this installation. During the installation, include the optional tools for native modules.

   Important: Version 4.0 and later of the Storefront Toolkit requires version 18.x or 16.x of Node.js and version 8.x of npm. To use custom components with this new Toolkit version, be sure to use @appdirect/sfb-theme-components npm library version 0.0.293 and above.Earlier versions (1.x.x to 3.x.x) require versions 10.x and 12.x of Node.js, and version 6.x.x of npm. Ensure that you use the correct versions of Node.js and npm for your version of the Toolkit.

2. Node-sass—This is a library that provides binding for Node.js to LibSass and it must be installed as a global dependency. To install it, run npm -g install node-sass from the command line.
3. Text editor—For code, markup, and prose, such as Sublime Text.

Install the Toolkit

After you install the necessary third-party programs, you can install the Storefront Toolkit through the command line.

To install the Toolkit

1. Open a command-line window.

2. Type npm install -g @appdirect/sfb-toolkit@latest --legacy-peer-deps and press Enter. Wait for the command to finish.

   Note: If you are upgrading your Toolkit to version 4.0 from an earlier version, you may receive warnings and error messages when you start it. For instructions on how to resolve these warnings and errors, see Upgrading to 4.0 and later.

Set up your workspace

After the Toolkit has been installed, you can use its setup command to create the workspace. This folder structure will contain a sample theme, which you can use as a starting point for your own theme.

During this setup you must specify the marketplace to which the theme is linked. This enables you to draw on that marketplace for data during theme development.

To set up a theme

1. Go to the directory to where you want to store your theme content.

2. Type sfb-toolkit setup _themeFolderName_ and press Enter. You are prompted to agree to the terms of the license agreement,
   The _themeFolderName_ is the top-level folder for your workspace. It contains a themes folder where your themes are stored.

3. Type agree and press Enter. You are prompted to select one of the standard marketplace themes as a starting point for your first theme. The choices are classic and Plaza.

4. Use the arrow keys to highlight the base theme you want, and press Enter.

5. Type a theme name and press Enter. A folder with the specified name is created on your computer. It includes all of the files required to create a custom theme. You are prompted to type the marketplace path.

6. Type your full marketplace URL.

   Important: Ensure that you include https:// in the URL.

7. Press Enter. You can now import data from the specified marketplace when you Use the developer toolbar in your browser.

Enable custom components

Components are re-usable and configurable UI elements that appear on a page, such as a sidebar or a slider. If your theme is based on the Plaza theme, you can work with components in the Storefront Toolkit during theme development, or you can build and customize your storefront pages in the marketplace itself using the Storefront Builder visual editor. The Storefront Toolkit includes several standard components that you can use for your pages: for example, you can integrate the Slider, Carousel, ProductBanner, and many more components in a Plaza-based theme.

If none of the existing components suit your needs, you can create custom components. Custom components are components that you can create and customize through the schema object.

To work with custom components, you must enable them for your theme in the command line:

sfb-toolkit components

This enables custom components for the current default theme, and creates a customComponents subfolder within the theme folder.

The documentation for components is provided by also activating the Storybook utility for the theme:

sfb-toolkit storybook

When it is completed, this command launches the Storybook utility on your machine and in your browser (at http://localhost/6099). This utility provides documentation for the components in your theme.

See the main Enable custom components topic for more information.

note

You must enable custom components independently for each theme that is to use them. This means that you must Switch between themes to the target theme before running the components and storybook commands.