Welcome, Wayfairians and open source enthusiasts. In this blog, I will share with you the building of our open-source hub for Wayfair, wayfair.github.io. The site is live right now, and I encourage everyone to visit. You can browse guides on getting started with OSS, read about featured projects we are watching in the Wayfair Open Source Program Office (OSPO); and find some practical tips and guidance which we hope will be of help to the entire OSS community.
This post will focus specifically on the fundamental software development choices made in creating the site. We will also dive into what is included,and some content snippets and highlights into what we like most about the final product. If you’re looking for code snippets with functional links to working deployed-in-the-wild software (well, as this post ages, I’m sure the permalinks will seem dated 😅), you came to the right place.
Starting with Starters
The creation of wayfair.github.io began with the use of some Gatsby Starters, which are open-sourced Gatsby sites that the company and its community maintain. I turned to these starters to automate some of the site’s design and setup. As a longtime Gatsby user, I’ve noticed that Gatsby’s available starters skew towards low-cost and free web applications and content management systems that can be used to update and manage the site. You can even use a Shopify starter to make a storefront that plugs and plays with an account.
Whenever I get overwhelmed with choices (which happens each time I open the starters page), I try to remain focused on what we need the site to do and if any extra bells and whistles are necessary to make this happen. For this project, the answer was a static site, which we could then extend into a docs site featuring markdown pages. Most of the available blog sites don’t double as functional sites for different page types or templates, which is why we did not begin with a blog starter. I also ruled out almost every other popular starter since I knew that Wayfair wouldn’t be happy with me using a CMS when it wasn’t needed. Based on my experience in using this tool, the best option was the default starter which comes with SEO labeling and plenty of plugins, and when necessary, installing more is just a yarn add-away.
Do it With Style
As I began this project, I had the benefit that many of these starters do not consider: a creative/design team! Wayfair Creative sent me a mockup complete with spacing, fonts, colors, and images that I could use to fill out pages that weren’t our markdown docs. This helped me build a consistent template for the pages that would be written with markdown. Without the benefit of a design team, I most likely would have selected one of the beautiful designs and starter templates available on Gatsby’s starter explorer.
Of course, building a site from the default template did present some challenges, including how to correctly import files using CSS imports. I assure you that the final product, which you can visit right now, does not indicate the blood/sweat/tears that my keyboard and I shed while writing them.
If you’ve ever seen a CSS import statement, you may notice that the way you reference a file makes sense if you’re building on a local filesystem. You may also notice that it doesn’t make sense when deploying the CSS by itself. In other words, if the CSS was not being bundled, the import would not have worked. I only learned that the CSS was being bundled this way and that this was not the preferred way to bundle when I began using Gatsby components. Ideally, each component would have its own CSS.
Normally that makes perfect sense; only load CSS when you need it. However, I wanted to split and bundle together the fonts file from the main CSS import since the entire site would need access to the font. I made this much harder than I needed to—it turns out I could have gotten away with an import ‘my-font.css’ in the `layout` template… but you live and learn.
To import the font, I needed to make use of the ` url` parameter in CSS. However, to use that effectively, I needed to serve the font files from the Gatsby server. The easiest configuration I came up with, after head-desking the issue for hours, was to use the gatsby-source-filesystem plugin, which would serve them from the root. With Gatsby, we can serve any folder from the root or from a specific route. I could have had it served as `wayfair.github.io/fonts,’ but thought the root was easy enough and would be easier for new contributors to understand. This wasn’t super intuitive to figure out. In fact, I only thought of it when I got desperate and began reading the configuration files that came with the starter.
A Strong Reaction
Now enough about my struggles. Let’s get back to some of the things I liked when writing this site. Gatsby works best with React, which I have used quite a bit when building sites and web applications. One thing I love about React is that it’s very liberating and exciting to use when creating static sites. Generally, structured web applications require a variety of libraries to fetch data, sync it into page state, and then show progress indicators and all the frameworks and packages associated with it. Using React, I didn’t need most of that for wayfair.github.io project. We just needed to build a website that would give documentation and could be easily updated for our main pages.
Maybe that good mood that resulted from using React without Redux or async fetching was why I decided to take another look at hooks, which is a new addition in React 16.8. I’ll admit that going into this effort, I was the grumpy old man (having used React for years) who felt hooks was getting “too opinionated” and “too abstract” to be used effectively. However, when I actually gave them a try, I thought they made a lot of sense.
I won’t rewrite the entire Abramov explanation included in the links, but I will say that hooks are far simpler for my lizard brain. Why? Because they require less code. Consequently, I’m far less likely to miss a detail or misunderstand a lifecycle hook. Instead of what I would have done on ComponentMount, I just wrote a function. Hooks then made the code easier to read, easier to test, and easier to work with as a whole. I give hooks are perfect score, 10 out of 10!
Markup with Markdown
When it comes to writing this site, the last and perhaps the part I’m most proud of was the ease of continuing contributions. We made a choice early on that the site would include some guides for Wayfairians. Our feeling was that many folks in the open-source community would benefit from these guides. However, we felt asking everyone to follow the same formatting, spacing, header choices, and design would be unreasonable. This is why we opted to allow most contributions to be made through markdown.
As we find topics to write about or get inspired from other open-source guides, we wanted to make it easy to write, review, and share those posts and docs with others. We chose markdown, which is a workflow and document type that can support this type of workflow. Markdown makes it easy to parse diff’s on pull requests. Using markdown, it’s also easy to make edits while one writes the site, and the styling is consistent thanks to Gatsby’s templating engine. Now, as we write more docs, we focus more on collaboration and the page content instead of the style choices or markup that we’ve written them on.
Site Has Been Sighted
Our entire team is thrilled to share the improvements we made to Wayfair’s open source activity, and we hope you find guides and docs that you like.
When I look back on the journey, I find that building the site was relatively painless. Granted, we had a design team, a great framework to depend on, experience in React, and a couple of other advantages that others might not have. That being said, I think this overview, the details on how we stepped through some of the trickier stages, and a forever-living reference point on GitHub will be a huge help to those embarking on a similar journey.
With that, we are always around and happy to answer any questions. You can email us at
opensource@wayfair.com.
