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