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.

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

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

webpack.common.jsContains the core webpack configurations for the project. The entry point and output are defined here.
webpack.dev.jsDefines the webpack configurations for development mode.
webpack.prod.jsDefines the webpack configurations for production mode.
webpack.profile.jsInstantiates 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

  1. Change to frontend/bundle/default/.
  2. Run yarn install.
  3. 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

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

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

Styleguide's initial view Styleguide's initial view
Styleguide's initial view

Building and sharing a theme

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

Visualizing a theme's bundle

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

Styleguide displays the visualization at The visualization is based on the command webpack --config webpack.profile.js.

Theme bundle profile Theme bundle profile
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.

Our robust, flexible Design System provides hundreds of pre-built components you can use to build the presentation layer of your dreams.

Asset types
Module types
Page types
Brightspot is packaged with content types that get you up and running in a matter of days, including assets, modules and landing pages.

Content types
Landing pages
Everything you need to know when creating, managing, and administering content within Brightspot CMS.

Admin configurations
A guide for installing, supporting, extending, modifying and administering code on the Brightspot platform.

Field types
Content modeling
Rich-text elements
A guide to configuring Brightspot's library of integrations, including pre-built options and developer-configured extensions.

Google Analytics
Apple News