Tutorial: Using Styleguide to build your first theme
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 .
- (refer to your project's requirements for the version you should use).
- (classic).
Styleguide's architecture
Styleguide is an 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 . 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 .
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 . The visualization is based on the command webpack --config webpack.profile.js
.
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.