Skip to content
A starterkit to create styleguides with Fractal and Webpack.
JavaScript CSS
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets Update dependencies, especially Babel to version 7 Oct 17, 2018
babel.config.js Update dependencies, especially Babel to version 7 Oct 17, 2018
webpack.config.js Replace style-loader by MiniCssExtractPlugin May 21, 2019

Styleguide starterkit

A starterkit to create web styleguides with Fractal and Webpack.

  • Fractal pre-configured with Nunjucks
  • JavaScript bundling with Webpack and Babel
  • Sass compilation, including Autoprefixer
  • SVG icons sprite generation
  • Live reload (with hot module replacement) for comfortable development
  • Automated release management with release-it


Prerequisites: Node.js >= 6, <= 10

Inside the directory of your choice, install a copy of the starterkit with:

curl -L | tar zx --strip 1

Then install the npm dependencies with:

npm install

Getting started

To start the development server, run:

npm start

You can now access your styleguide at localhost:3000.

You’re all set, start to:

  • Create components as .nunj (Nunjucks) files inside the components directory
  • Write some style inside assets/scss/common.scss
  • Write JavaScript inside assets/scripts/common.js
  • Put some *.svg icons in the assets/icons directory
  • Write documentation as .md (Markdown) files inside the docs directory.


You can build a static version of the styleguide to deploy it wherever you like by running:

npm run build

The generated files go to the dist directory.


The starterkit comes with a preconfigured release management tool. It will automatically update the file at the root of the project based on the commit messages as long as they follow the Angular commit guidelines. It will also bump the version number in the package.json, run the build command above, commit, tag and push the changes. This process is interactive and you’ll be able to skip steps manually if you like.

To release a new version run:

npm run release [patch|minor|major|version_number]

By default the version bump is automatically determined based on the commits messages.

Read more in the release-it documentation.


To deploy a build of the styleguide, simply replace the blank command in the package.json, under scripts -> deploy. This will be automatically invoked at the end of the release process described above.

An example of a simple deploy command using rsync:

"deploy": "rsync -avz --delete --exclude='.*' dist/"

⚠️ Notice the --delete flag which means all files not present locally will be deleted on the remote server. Be careful, this can leads to data loss!

You can also deploy manually at any time by running:

npm run deploy


Browsers support

The browsers support is defined in .browserslistrc. It’s used both by Autoprefixer for the CSS and by @babel/preset-env for the JavaScript.

Check browserslist’s documentation to change the browser support.


Icons placed inside assets/icons are combined into a sprite called icons.svg when referenced. To load them, either reference them in your JavaScript:

import 'icons/foo.svg';

Or in your stylesheet:

background-image: url('../icons/foo.svg');

Webpack will automatically rewrite the links to the sprite with the correct identifier. See svg-sprite-loader documentation for more information.

You can then easily use an icon in a template with the icon snippet:

{% render '@icon', { id: 'foo', class: 'bar' } %}

Warning: This method of including remote SVG file is not supported by Internet Explorer 11 and below. You may want to polyfill it with svgxuse.

You can’t perform that action at this time.