Deploy your component library to GitHub Pages

⏲ Time invest: 20 Minutes ––– 👩‍🎓 Level: Expert

What to expect

Component libraries built with patternplate are all about sharing your work and having a common place to refer to - the much discussed Single Source of Truth.

To establish your component library as such you'll want to deploy it as a website.

We will …

• … learn how to use the patternplate build CLI command.
• … push and publish your component library to GitHub Pages.

You'll need

• ✅ You are all set if you followed along Guide: Build a component

• ✍️ Text editor
• 📁 patternplate project (Getting Started Guide)

Before you start

• Be comfortable with terminal usage
• Have a working knowledge of git
• Have a GitHub account

Build a static interface

1. Open a terminal window and change into the directory holding your patternplate project.

2. Execute the following command to produce a static build of your component librarie's interface

   yarn patternplate build --out='docs/patterns' --base='/patterns/'
   

   

3. patternplate creates a bunch of files in docs/patterns for you

tree docs/patterns/
docs/patterns/
├── api
│   ├── demo
│   │   ├── button.html
│   │   └── hello-world.html
│   ├── patternplate.web.components.js
│   ├── patternplate.web.cover-client.js
│   ├── patternplate.web.demo.js
│   ├── patternplate.web.mount.js
│   ├── patternplate.web.probe.js
│   └── state.json
├── doc
│   └── README
│       └── index.html
├── index.html
├── pattern
│   ├── button
│   │   └── index.html
│   └── hello-world
│       └── index.html
└── static
    ├── client.js
    └── vendors.js

8 directories, 14 files

4. Start a static webserver on /docs and open /

npx serve docs/ --open

5. Click on the patterns folder that shows up in your browser

6. You should see a fully functioning patternplate interface on the patterns/ path 🎉. Let's bring this beauty online!

Deploy to GitHub Pages

Replace [username] with your GitHub username in all commands of this section.

1. Create a new repository on GitHub, name it e.g. my-patternplate

2. Rerun our build to match its deployment target:

   yarn patternplate build --out docs --base=/my-patternplate/
   

3. In your local repository, commit your changes

   git add docs
   git commit -m "docs: deploy static interface"
   

4. Set the remote of your local repository to your new remote repository on GitHub and push to it

   git remote add origin git@github.com:[username]/my-patternplate.git
   git push -u origin master
   

5. Open your repository settings at https://github.com/[username]/my-patternplate/settings and scroll down to the GitHub Pages section.

6. Click on the dropdown under Source and select master branch docs folder. Make sure to hit the save button next to the dropdown.

7. Navigate your browser to https://[username].github.com/my-patternplate/. You should see the very same interface you created locally earlier.

Take aways

• patternplate build creates a static build of your component library
• The --base flag must match the url pathname the interface will be available at
• The output of patternplate build is well-suited for deployment to GitHub Pages, but works for every static web sever

Related topics

• CLI