Let’s build React Components library!

Part 4— Auto deployment of the documentation to GitHub Pages

Tomasz Fiechowski
Sep 9 · 6 min read

If you haven’t yet, check out the first part where we actually built the components library foundation, we added tests in the second and then bundled and published the package to the NPM.

TravisCI, Styleguidist and GitHub Pages

At this point, we have a fully working library that’s published to NPM. Let’s now make it accessible and transparent for the users — we will publish the documentation to the GitHub Pages!

Generating documentation 📖

Styleguidist makes it possible to develop the components in real time, but its primary goal is to create a static page with the contents we’ve built.

Let’s start with modifying the package.json and adding the following script:

"docs:build": "styleguidist build"

Now open Styleguidist config file and add title and styleguideDir fields:

styleguide.config.js

By default, Styleguidist would generate the static site to styleguide directory, but let’s make name not coupled to the library name itself and just call it dist-docs. Add dist-docs to .gitignore too, there will be no need to commit the documentation along with the source code.

Run npm run docs:build now and open the generated dist-docs/index.html file. We can see the documentation running from a set of static files!

Preview of dist-docs/index.html

Now, let’s click on the “VIEW CODE” to see the source code of the example:

Source of the example of Button component usage

Now, if you wanted to use that Button in other project, I’m sure you would use a method that is one of the foundations of a software development: copy paste driven development.

I copy, but wait, there is no './Button' in my project… 😟

Do others a favour, make your code fully copy paste-able 💪

Styleguidist has the mechanism that is similar to the Babel module resolver plugin, that previously made it possible to change relative imports to absolute ones.

It will alias the specified package names and translate it to local directory paths. As an effect, we will be able to write the imports just like the user of our library would do!

In order to do that, let’s go to the styleguide.config.js and add a moduleAliases field:

styleguide.config.js

Whenever you import something from react-sample-components-library in the examples, Styleguidist will actually look for that in the src directory.

Let’s change the Button description to:

src/components/Button.md

Note: We imported the Button like import { Button } instead of just import Button, because the resolved path pointed to src/index.js where the Button is a named export.

Rebuild the docs or refresh the page if you’re running Styleguidist in the development mode. Our documentation should now look like this:

Copy-pasta fan wet dream 😇
(basically every programmer)

That’s it for generating the documentation itself. Let’s configure the auto deployment pipeline now.

GitHub setup

If you haven’t created the GitHub repository for your sample library yet, do it now. It will be connected to TravisCI for scheduling automated builds.

In order to make TravisCI and GitHub work with each other, we need to generate a personal access token on GitHub.

Go to this page, add a meaningful note and tick the first box on the list:

Generating personal access token on GitHub

Hit Generate token on the bottom and save it for later.

TravisCI setup

Time to setup up TravisCI. It has a really great integration with GitHub Pages, requiring us to add just a couple of lines in the config file.

Create the account if you don’t have it yet and then go to the list of your repositories. Find the repository with the component library, toggle the enable button and then go to Settings.

We need to add an environmental variable with GitHub token that will be later used by the deployment scripts. Let’s go to the Environmental Variables section and add GITHUB_TOKEN variable with the value of the token that we generated in the previous step.

Important note 🚨
Make sure that “Display value in the build log” is not checked!
Otherwise, your GitHub access token would be publicly visible.

That’s it for the setup of both GitHub and TravisCI. Let’s go back to the repo.

TravisCI configuration

Configuration for TravisCI should be in a .travis.yml file in the root of the repository. Create it and add the following content:

.travis.yml

In the top, we specify the environment for the pipeline and add caching of node_modules to speed up the builds. The builds have their lifecycle, and for the documentation deployment, we will obviously use before_deploy and deploy phases.

In the before_deploy phase, let’s build our documentation. For the deploy phase, TravisCI offers an extensive list of services that we can easily integrate with. They call them providers. Let’s use pages provider that will do the required job under the hood in order to publish our documentation to the GitHub Pages.

We also need to set skip_cleanup to true, so assets generated in the previous phase will not be cleaned up. The pages provider needs github_token, let’s set it to the environmental variable $GITHUB_TOKEN that we created before. Finally, point the provider to the place where the documentation is generated: local_dir: dist-docs. Everything happens on the master branch.

Deploying the documentation 📦

Commit the .travis.yml file and push the changes. After the moment, TravisCI should detect the changes on master branch and trigger the build:

Let’s check the logs while the build is running…

Magic. Black Magic 🎱

If you take a closer look at the Build log, you can actually see that there are npm ci and npm test commands ran. The first one makes sense, but we haven’t configured the build to run tests anywhere. What?!

Each environment on TravisCI has some default commands specified. For the NodeJS, install and script are defaulted to npm install/ci and npm test respectively. Personally, I don’t like this kind of implicit magic, so I encourage you to add those steps explicitly in the .travis.yml .

Hello, world! 🌎

After a succesfull build, we see the results on the GitHub Pages! You can enter the website by following the link with the format:

https://<username>.github.io/<repository-name>

In my case it’s tfiechowski.github.io/react-sample-components-library

Hopefully not 😂

Summary 🍕

We added some scripts and set up Styleguidist to generate the static bundle of the documentation. Then we hooked up GitHub with TravisCI using a generated token and .travis.yml configuration file. After pushing all the changes, builds were triggered and the documentation landed on GitHub Pages. And will automatically land there again every time master branch is updated!

Full code is available in the GitHub repository. You can checkout part4 tag (git checkout part4) to see the full example from this part!

Last words

Thanks for reaching the end! Hopefully without skipping the testing part! 😂

If you liked the series, feel free to share the links or express your opinion in the comments. Moreover, if you have spotted some mistakes or disliked something, even the whole thing, please give me feedback! That will be very valuable for me, so that I can write better and more valuable articles in the future!

If you want to get in touch, check out my LinkedId, Instagram profiles or just write me an email: tomasz.fiechowski@gmail.com.

Tomasz Fiechowski

Written by

Software engineer & Team leader @Codility

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade