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.
![Styleguide's initial view](https://brightspot.brightspotcdn.com/dims4/default/eb2ff09/2147483647/strip/true/crop/940x606+0+0/resize/940x606!/quality/90/?url=http%3A%2F%2Fbrightspot-brightspot.s3.amazonaws.com%2Fbsp%2F86%2F91%2Fcf657136498b8f84852011a0c41e%2Fstyleguide-initial-view.png)
![Styleguide's initial view](https://brightspot.brightspotcdn.com/dims4/default/1973b38/2147483647/strip/true/crop/940x606+0+0/resize/800x516!/quality/90/?url=http%3A%2F%2Fbrightspot-brightspot.s3.amazonaws.com%2Fbsp%2F86%2F91%2Fcf657136498b8f84852011a0c41e%2Fstyleguide-initial-view.png)
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
.
![Theme bundle profile](https://brightspot.brightspotcdn.com/dims4/default/0c99b88/2147483647/strip/true/crop/992x851+0+0/resize/992x851!/quality/90/?url=http%3A%2F%2Fbrightspot-brightspot.s3.amazonaws.com%2Fbsp%2F8b%2Fef%2F4dd1c63f4ea3ac564d2b8bc7aee3%2Fyarn-profile.png)
![Theme bundle profile](https://brightspot.brightspotcdn.com/dims4/default/efb8a18/2147483647/strip/true/crop/992x851+0+0/resize/800x686!/quality/90/?url=http%3A%2F%2Fbrightspot-brightspot.s3.amazonaws.com%2Fbsp%2F8b%2Fef%2F4dd1c63f4ea3ac564d2b8bc7aee3%2Fyarn-profile.png)
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.