80. Creating a component styleguide

In the second half of this module we'll be documenting our frontend code by creating a component styleguide. To do this, we'll be using a tool called Vue Styleguidist, which, like apiDoc, will automatically generate a styleguide website based on the doc blocks and other meta information we provide about our components.

However, unlike apiDoc, we're able to make our styleguide live and interactive by rendering our components within it.

Create config

Let's begin by creating a config file for Vue Styleguidist in our root directory by going to the terminal and typing:

$ touch styleguide.config.js

The config for Vue Styleguidist is in the form of a CommonJS module, so let's put module.exports in the file, and assign to that an object.

styleguide.config.js

module.exports = {};

Dev server

By leveraging Vue CLI 3, Vue Styleguidist can launch a local dev server to serve the generated docs when in development mode.

We can elect the port of that dev server by adding a serverPort property to the config, and we'll set that to 8060.

Now, if you're using the Vagrant development environment, you'll also need to swith on file system polling for the Webpack dev server. Generally, Vue Styleguidist prefers us to configure Webpack explicitly, but we can override specific Webpack settings by using the very descriptively named property dangerouslyUpdateWebpackConfig. This is a method property, which accepts the webpackConfig object as an argument.

In this method, we're now going to override the property webpackConfig.devServer by assigning it an object. We'll give it the property watchOptions and assign that to an object as well. We'll set the poll option on this object, giving it a value of 500 milliseconds so it's nice and responsive.

Finally, we'll return the webpackConfig object from the bottom of this method.

styleguide.config.js

module.exports = {
  serverPort: 8060,
  dangerouslyUpdateWebpackConfig (webpackConfig) {
    webpackConfig.devServer = {
      watchOptions: {
        poll: 500
      }
    };
    return webpackConfig;
  },
};
`

So that's our dev server configured.

Sections

Next, let's add a sections key to our config and assign to this an array. Vue Styleguidist is fairly flexible in how you structure your docs site, allowing you to add a variety of differernt sections, which can be component documentation, or whatever markdown you want to include.

So let's add our first section by declaring an object in this array and giving it a name property to which we'll assign "Components". We'll also give it a components property and assign to this the path to our component files, which "./client/components/*.vue".

You may note that we're including our custom components in the styleguide, but not our view components (I mean v,i,e,w components). The reason is that the view components don't really require any documentation since they're designed for single use and don't have any inputs or outputs.

styleguide.config.js

sections: [
  {
    name: "Components",
    components: "./client/components/*.vue"
  }
]

Add NPM scripts

In order to run Vue Styleguidist from the terminal, we can use its Vue CLI 3 command.

Rather than running that directly, though, let's add it as an NPM command. So we'll add to our scripts section "docs:serve:client" and assign to that the Vue CLI 3 command which is "vue-cli-service styleguidist".

We'll also add a build command which will be "docs:build:client": "vue-cli-service styleguidist:build". Obviously that latter command will build the docs site without running the dev server.

package.json

"scripts": {
  ...
  "docs:serve:client": "vue-cli-service styleguidist",
  "docs:build:client": "vue-cli-service styleguidist:build"
}

With done, let's go ahead and run npm run docs:serve:client to generate our styleguide and launch the dev server.

Once the dev server is running, come over to the browser and visit localhost:8060 and you'll see the the styleguide up and running.

We can see that Vue Styleguidist has successfully identified our components. There isn't yet much in the way of meaningful content in the docs yet, though, since we haven't yet documented them.

We'll begin that process in the next video.

Discussion

3 comments