Tutorial: Using Styleguide to build your first theme

10 minutes

Estimated Time

In a coupled front-end/back-end environment, Brightspot provides the theme to render assets. Themes are a set of Handlebars, JSON, and Less files that Brightspot uses at build or run time.

Styleguide is the front-end development environment included with Brightspot. Using Styleguide, you can do the following:

Render sample content over a local server as you code the theming files.
Output a theme to a zip file.
Visualize the theme's contents.
Format the Handlebars, JSON, and Less files.

This tutorial provides an understanding of the Styleguide architecture, explains how to install and run Styleguide, and also explains how to build a theme that admins can deploy inside a Brightspot instance.

Assumptions
You need the following on your laptop to complete this tutorial:

A copy of Brightspot's standard edition, available from https://github.com/perfectsense/brightspot-go.
Node.js (refer to your project's requirements for the version you should use).
Yarn v1 (classic).

Styleguide's architecture

Styleguide is an Express application that provides a development environment for creating themes. Styleguide enables developing front-end components and pages, requiring minimal coordination with back-end development. Styleguide promotes efficient development by providing mock data generation, debugging tools, UI component organization, and search capabilities.

The latest versions of Styleguide are powered by webpack. The following webpack configuration files are in the directory frontend/bundle/default/.

File	Description
`webpack.common.js`	Contains the core webpack configurations for the project. The entry point and output are defined here.
`webpack.dev.js`	Defines the webpack configurations for development mode.
`webpack.prod.js`	Defines the webpack configurations for production mode.
`webpack.profile.js`	Instantiates the Webpack Bundle Analyzer to visualize the size of webpack output files.

Developers familiar with webpack can modify these configuration files to customize Styleguide for a particular development or production environment.

Installing Styleguide

Change to frontend/bundle/default/.
Run yarn install.
Wait until a message similar to Done in 18.36s. appears.

The install program creates a directory node_modules/ containing all the dependencies.

Running Styleguide

Change to frontend/bundle/default/.
Run yarn server:styleguide.
Point a browser to http://localhost:8080/.

You will see the Styleguide UI showing your theme, including the associated colors, typefaces, buttons, and layouts.

Building and sharing a theme

Change to frontend/bundle/default/.
Run yarn build.
Wait until the message [BRIGHTSPOT Styleguide] Finished! appears.
Send the built theme build/theme.zip to an admin, who installs it in Brightspot.

Visualizing a theme's bundle

Change to frontend/bundle/default/.
Run yarn profile.

Styleguide displays the visualization at http://127.0.0.1:8888/. The visualization is based on the command webpack --config webpack.profile.js.

Theme bundle profile

The visualization reports the contents of your bundle, the largest modules, and other insights. You can use the visualization to optimize the theme's bundle.