Aurora Core: a clean, modern Sass and ES Next-ready project boilerplate

Now that Aurora Theme has a solid foundation built upon Underscores, it’s time to make it a React-ready project. To speed up this process, I am going to integrate Aurora Core, a project boilerplate, into Aurora Theme. Today I’ll discuss a few key features of Aurora Core, the problem it’s meant to solve, and a little about how I’ve built it. In future posts, I’ll talk about how it’ll be integrated into Aurora Theme, and the key differences between Aurora Core and Aurora Theme.

The problem

After building several dozen projects for Bov Academy, I realized most projects had a common set of requirements / tooling. Unless a project requires 200 lines of CSS or less, I always reach for Sass, and I needed a way to compile my styles.

always use JavaScript in all my Bov Academy projects, and typically, I’d have more than one file to deal with. Keeping performance and ease in mind, I needed a way to concatenate and minify to JS, too.

Additionally, I have a preferred structure for each of my projects. HTML files tend to stay at the top level, while Sass, JavaScript, images, and other assets live in an assets/ directory. Why recreate the structural wheel for each project, right?

My first attempts at rolling my Sass and JavaScript requirements together was within my Bov Web Components project. I set up my desired project structure and added a pretty sweet Gruntfile for all sorts of tasks. And it worked pretty decently. Except not all projects require accordions or tabs or [insert other component here]. And ain’t nobody go time for ripping all that junk out at the start of a project (because we all know if you wait to the end, that ish is shipping 😬). After ripping out the same components for the forth or fifth time, I decided it was time to consider building a proper boilerplate.

What makes a good project boilerplate?

The structural and Grunt task running features of Bov Web Components were infinitely useful. Other features, mainly the components themselves, were less so. I wanted to use what worked as a starting point, and expand upon that. So I created a little list of requirements for my boilerplate:

  • Sass support
    • functions
    • mixins
    • a base config file
  • JavaScript / ES Next
  • Task running
    • Sass compilation & minification
    • JavaScript concatenation & minification
    • Image processing (compression)
    • Icon concatenation & minification
  • Linting
    • Stylelint
    • ES Lint
  • Configuration
    • Editor Config
    • Prettier
    • Babel
  • Documentation
    • Sassdoc
    • JS Doc
    • KSS

Once the initial requirements were defined, I started really digging into research. Mina Markham’s Sassy Starter provided a lot of inspiration, as did fellow Bov Student Gabriele Romero’s ES6 Professional Starter Kit. Both are clean slates for a new project, and both are documentation-forward. Sassy Starter has incredibly well documented Sass functions and mixins using Sassdoc, while Gabriel’s ES6 starter kit has JavaScript documentation in mind with JS Doc integration.

I cannot express enough how important this type of documentation is. Have you ever used MDN or the jQuery API docs? Both have rich documentation available for both Sass and JavaScript was really important to me since Aurora Core is an open source project. I want anyone who comes across the boilerplate to feel confident that they can download it and get started with no problems.

To round out my research, I looked to the more popular feature-rich front end frameworks like Bootstrap and Foundation. I wanted to get a sense of what was included beyond a bunch of predefined components (i.e. were there any useful Sass functions or mixins I could replicate). I noted anything that looked interesting in Evernote, and found a few other resources along the way.

With a clear list of requirements, and a bunch of helpful notes research notes, I set to work on the boilerplate.

Laying the foundation

Bov Web Components was a great starting point for this project. In fact, I actually grabbed all the configuration files (Prettier, ESLint, Stylelint, etc.) and the Gruntfile from that project to start Aurora. Around the time I started Aurora Core, I read about Readme Driven Development (RDD). RDD claims to be a happy medium between a waterfall process, where projects are outlined in too much painstaking detail, and agile development where projects aren’t defined in enough detail. While I didn’t write my readme from the very start, I did set to work on it in the first day. Having a project charter has, indeed, been hugely beneficial to keeping my on task.

After the initial project setup, I focused on creating my foundational Sass files. I made detailed lists of must-have functions, mixins, and variables, trolled through old projects for more ideas, and added ideas based on my research. Even though I adore Sass, this part was painstaking. Remember when I mentioned documentation being important? Well, it’s also a PITA to write. It’s especially painful for mixins. Feast your eyes on this as an example:

/// Generate button variations quickly and easily.
///
/// @param {Color}  $background                                    - The desired background color.
/// @param {String} $border            [0]                         - The desired border (use shorthand e.g. 1px solid aqua).
/// @param {Color}  $background-hover  [lighten($background, 10%)] - The hover background color.
/// @param {String} $border-hover      [$border]                   - The hover border (use shorthand).
/// @param {Color}  $background-active [$background-hover]         - The active background.
/// @param {String} $border-active     [$border-hover]             - The active border.
///
/// @example - scss Sample Usage
///  @include button($color__primary, $border__button, $color__accent);
///
/// @todo Determine whether color should be passed, or add way to automatically determine color to use (light or dark).
@mixin button($background, $border: 0, $background-hover: lighten($background, 10%), $border-hover: $border, $background-active: $background-hover, $border-active: $border-hover) {
  background-color: $background;
  border: $border;
  color: $text-default-dark;

  &:focus,
  &:hover {
    background-color: $background-hover;
    border: $border-hover;
    color: $text-default-dark;
  }

  &:disabled {
    background-color: tone($background, 20%);
  }

  &:active {
    background-color: $background-active;
    border: $border-active;
    color: $text-default-dark;
  }
}

There is nearly as much / more documentation for this mixin as there is code! But it sure is helpful to have documentation to which I can refer later.

A screenshot of Sassdoc documentation for a button mixin within Aurora Core.

Introducing Webpack

Grunt is great. It’s familiar, but it is also slow AF. I heard all the kids these days are using Webpack, and as soon as I had an opportunity to learn it, I wanted to integrate it into Aurora Core.

One of the most common conceptions of Webpack is that it’s difficult to learn. And it kind of is. But while it’s not as easy or familiar as Grunt or Gulp, it’s not super duper difficult either. Once you wrap your head around loaders and plugins, you’re golden. 👌

But where Webpack really shines is in it’s ability to play super nicely with not only ES6+ JavaScript, but also with front end frameworks including Vue and React. While Aurora Core’s charter is to be ES6+ ready, I also wanted to make it really easy to integrate JavaScript frameworks.

So not too long after learning Webpack, I set to work researching loaders, plugins, and doing a bunch of trial and error to see what worked, and what didn’t. I’ll readily admit I have started it over once or twice already. But I’m feeling much better about where it is currently. I still need to add a few things specifically for production builds, but once that’s done, it’ll be good to go.

This is so much already, and I haven’t even touched on how Aurora Core will be integrated into Aurora Theme. 😅  In the next post, I’ll talk about adding Aurora Core to Aurora Theme. I’ll talk about preparing the theme for React, and on the differences between how Webpack works within Core vs. the Theme. After that, I’ll talk about how I’m using Aurora Core’s Sass in the Theme. There are some rad benefits of Sass + Webpack + React that I cannot wait to share. And last in this micro series on Aurora Core, I’ll review how I am using code formatting and linting tools, and the differences in them between Core and the Theme.

Spinning up Aurora Theme using underscores.me

Building a theme vs. a decoupled front end

Today is the day we start talking about dev shit™, and start getting into the nitty gritty of building Aurora Theme. In the project plan, I laid out the benefits of using the REST API, and that one of those benefits is that we can break out of the whole theme paradigm. But, I’ve chosen not to decouple my front end and, instead, am building a React-powered theme. And you may be wondering why I’ve chosen to do this. Well, let’s remember this nugget from the project plan:

Aurora will finally make REST API-driven sites and technology more accessible to the everyday WordPress user and developer.

I strongly believe the best way to make the REST API more accessible to the everyday WordPress user is to build the front end using the current theme paradigm. Let’s face it, the current system of changing the look of one’s site is pretty damn nifty. And we can take customization further by adding options to the customizer.

But the beauty is that Aurora Theme could just as easily be repurposed as a decoupled theme. Just take out the PHP and WordPress-specific bits, and you’re left with a decoupled app.

Determining file requirements

Even though Aurora Theme is mean to be a starter theme, it’s still going to be an attractive, functional theme. And I have every intention of submitting it to the theme repository, so it’s important to understand up front what the requirements must be met. According to the WordPress Theme Developer Handbook, themes submitted to the theme repository must contain the following files:

  • style.css
  • index.php (as a fallback if all other files fail)
  • comments.php
  • screenshot.png

Interestingly, Foxhound, which is also a React-powered theme, doesn’t have the comments.php template, but it does have the other files. So following their lead, I think I’ll include the above, minus comments.php, and add the following:

  • functions.php (for managing script & style enqueues, and some other functionality)
  • header.php (for all the stuff that lives in <head />)
  • footer.php (for all the scripts that come before the closing <body />)
  • inc/
    • customizer.php
    • rest-api.php (waffling on this, but I think I’ll need to make a few tweaks to endpoints)
    • template-tags.php (maybe?)

Building a foundation with Underscores

To give myself a head start, I’m using Underscores as the foundation for Aurora. Underscores doesn’t look like much from the start, but it’s packed with a lot of stuff, and it will save me time enqueuing things, getting the file structure set up, and getting a theme that looks like a theme.

Before: Aurora with the full set of files from Underscores
Before: Aurora with the full set of files from Underscores
Before: Aurora home page with full Underscores
Before: Aurora home page with full Underscores

But as you can see from the file structure screenshot, there are a lot of files. So first things, first, buh-bye to all the stuff we don’t need. 💣

After: Aurora with only the files we need to start.
After: Aurora with only the files we need to start.

Ah, that’s better. Less cruft to cut through to get started, and I didn’t completely break the theme.

After: Aurora after removing a bunch of files.
After: Aurora homepage after removing a bunch of files.

Clearly, obliterating the template-parts/ directory prevents any content from loading, but that’s fine. We’ll replace it with JavaScript soon enough.

Cleaning up what’s left

There is still a lot of PHP-specific theme stuff hanging out that won’t be necessary for this project. I tried to handle this in a semi-methodical way:

  1. Clean up functions.php
    • Add theme constants to save on cognitive load / extra typing
    • Add a social menu for eventually managing social media links
    • General code cleanup / rearranging
  2. Remove a bunch of unneeded functionality
    • Wipe template-tags.php completely clean (jury’s out on whether I need this file at all)
    • Clean up the customizer file
  3. Blast away a bunch of markup & templating in header.php, index.php, and footer.php 💥
    • Since this is a JS theme, we’ll let React handle the markup and templating for those sections

Since everything above left me with a literal blank canvas, I added a temporary JavaScript header. It just creates a header tag, an h1 for the title, and a p for the tagline, brings everything together, and slaps it into the DOM. I also discovered at this point that I was a little overzealous with my clean up and accidentally removed get_footer() from index.php, which is responsible for footer scripts and pulling in the admin bar. 😬

Integrating Aurora Core is next on the list. I’m really looking forward to sharing a bit about that project and wrestling Webpack to work with WordPress. 😉

Setting up project environments

I’m gonna be straight with ya. The main reason I wanted to write this post was because I successfully utilized Let’s Encrypt to add an SSL certificate to aurorathe.me. And SSHing into a remote server, and not breaking it (in fact, making at least some part of it more secure) feels like black magic. So today, let’s make this a broader discussion and talk about the project environments I set up to work on Aurora Theme.

Working Locally

Talking about local development environments sometimes feels like a contentious subject. In the WordPress space, each person seems to have rather strong opinions about why their local dev environment is best. I’m not here to tell you what to use. Hell, I don’t care. What’s important is that you have a local environment that works for you. But if your machine sounds like it’s ready for takeoff, maybe it’s time to consider an alternate option. 😉

Choosing a WordPress environment

I’ve been wavering between Local by Flywheel and VVV for the past year. Local is great because it has a simple interface, and spinning up a new site is super easy. I also really like how it comes preconfigured with MailHog (so you can check emails sent from your local domain), and accessing a site’s database is as easy as clicking a button. VVV, on the other hand, is a command line utility, and offers endless configuration options. Need to test something on an older version of WordPress? No problem. You can adjust that over the command line. Prefer interacting with things over the command line? VVV has you covered.

I swap between using my 2015 MacBook (the little 12-inch retina number) and my 2016 MacBook Pro (the 15-inch version). I mention this because it really doesn’t matter what I use on my MacBook. It has no fans so it never sounds like I’m on an airport runway. My MBP, however, does have fans, and Local + VS Code seems super problematic on that machine for one reason or another. I’m super tempted to try VVV on my MBP, and use Local on the other (which is actually the only option on that machine).

Writing code

I feel pretty strongly about VS Code. I’ve been using it for just over a year, and made the switch because Brackets just couldn’t handle an entire wp-content folder for an enterprise-level site. I shopped around for about a week trying Sublime, Atom, and PHPStorm, but VS Code stood out because it was the most Brackets-like (hello integrated version control! 👋), but also had some of the neat features I quickly got hooked on in Sublime (Cmd + P quick file browsing for the win!). Setting up all my editor tools (linting, snippets, etc.) was super quick and easy, and turned out to be the least painful of all the options. It doesn’t hurt that it already includes most of the “necessities.”

Focusing mostly on JavaScript development over the past few months has made me love VS Code even more. It has incredibly robust debugging features, and is packed with all kinds of goodies that make modern JS development a breeze. For example, recently I’ve been doing a lot more work with ES6 modules, and I love how VS Code can guess which module I’m importing as a type. HELL YEAH!

Keeping code under [version] control

Git is essential. I use it on basically every project, and Aurora Theme will be no different. I’ll be keeping two repos for this project:

  1. for the theme itself
  2. for the entire wp-content directory, which includes both the plugins and themes directories, to manage deployments

I probably could avoid managing the entire wp-content directory, but if I need to add a plugin during development, which will also need to be deployed, I don’t want to waste time on managing these things separately. Since Git lends itself nicely to a deployment discussion, let’s move along to remote environments.

Deployments & production

Aurora Theme is a journey. A terrifying journey into my development and thought process. aurorathe.me is the production site, but this is a personal project, and I want to share my journey while developing the theme. So, I am going to push everything straight to production. Clearly, if I get to a point in a few months where Aurora is stable, and I want to only focus on minor changes, I’ll revisit this approach.

The production environment

I was introduced to Webfaction during my MIGHTYminnow days, and I’ve been pretty hooked on it every since. Webfaction bills itself as “hosting for developers,” offering a lot of storage, bandwidth, and memory for $10 a month. What I ❤ about Webfaction is how easy it is to spin up a new site. Instead of wasting time manually installing something like WordPress, you add a new application to your domain, and Webfaction does the heavy lifting. And there is no shortage of configuration-free options available, so if you’ve always wanted to dabble in Django, Node, Rails, etc. it’s easy to spin up a new installation.

The one thing I did differently with aurorathe.me was set up SSL using Let’s Encrypt, which is a free SSL certificate authority. Because aurorathe.me is my production site, I wanted to make sure I had SSL up and running from the start.

Let’s Encrypt + Webfaction

At the beginning of this post, I mentioned how SSH-ing into a remote server and not breaking everything feels like sorcery. Well, that applies here. Following the chosen answer from this post on the Webfaction forums, plus a helping hand from this post on adding Socat to Webfaction got me sorted out in about 15 minutes. And now that I have both acme.sh and Socat tools set up, adding SSL certificates to new domains is as easy as:

Le_HTTPPort=77777 acme.sh --issue -d mydomain.com -d www.mydomain.com --standalone

More Magic with WP-CLI 🧙‍♀️

The super sweet thing about working with the REST API is that I only need my data in one place. Because I’m in the super-early development phase, and I don’t have any specific requirements for data, I’m using the WP-CLI + Jay Wood’s WP-CLI Random Posts package to generate data for my site (complete side note here, but Jay is amazing. If you ever have an opportunity to work with him, you are incredibly lucky. He’s so happy to share his knowledge with kindness and patience, and that, my friends, is truly amazing 💫). So a little more SSH sorcery with wp jw-random generate 25 --featured-image --img-type=business, and I’ve got myself 25 posts with featured images to work with both locally and remotely. 💥

Deployments

So, how does code get from my machine to production? Well, it’s a magical combination of Git + Github + DeployHQ = ✨.

The beauty of DeployHQ is that it can be set up to automatically deploy to the remote server every time there is a push to the master branch of my project (in this case, the repo with wp-content). There is no mucking about with an FTP client, and I don’t have to remember anything. Of course, it’s totally possible to manually deploy the project, which is what I’d generally recommend for a production site. But again, this particular project, I’ll opt for automatic deployments to keep my environments up-to-date, and let you, friend, follow along.

Project Management

I’d be remiss if I didn’t mention how I’m keeping track of project deliverables, and making sure that I keep this project moving forward. I used to use Basecamp for managing my freelance and personal projects. But paying $30+ a month for just personal projects was a bit steep. More recently, I moved over to Trello, and it’s been pretty perfect. (Want to follow along? Check out the Aurora Theme Trello board.)

Creating lists for each “project phase” is really helpful for me to plan out entire projects, and see the bigger picture. And within each list, I have a card for each “bigger” task that needs to be completed. Some cards have checklists within them, others just have general notes to remind me what I was thinking. I really like that cards can then be shuffled around to “In Progress” or “Complete” lists, and it’s easy to see that progress that’s been made. Or maybe you just want to use labels to denote what’s in progress and what’s complete instead. That’s the beauty of Trello, there are endless possibilities for organizing things.

Whew, that’s a lot, right? 😅 Being organized up-front is super important to the success of any project, but I almost think it’s more important when working on a personal project. It’s so easy to get distracted (anyone else suffer from shiny object syndrome?), and having a concrete plan, with concrete steps is important to achieving your project’s goals. This is probably the most organized I’ve been for a personal project, but I also feel like I’ve really set myself up for success.

Building a React-powered starter theme

As I near the final stretch in my Bov Academy studies, it’s time for me to choose a final project. For my final project, I have decided to capitalize on my love of JavaScript + WordPress. So, in this post, I want to introduce Aurora Theme–a React-powered starter theme for WordPress. (If you click the link shortly after this is posted, the joke’s on you. I haven’t deployed anything yet, and that is, indeed, the current default theme.)

So maybe you’re thinking, “why is she sharing something she hasn’t even started?” That’s a great question. I thought it’d be pretty neat to document the entire journey of building this thing. To many of us in the WordPress community, this whole REST API thing is still a foreign concept. Breaking our traditional PHP theme paradigm is going to take time. It’s going to take research. And it may not be pretty. I already have questions about implementation of things in the back of my mind, and I’m hoping to answer these questions as I go, and share them with the community. Of course, if you’re reading one of these posts, and you have questions, speak up and ask in the post comments, or @me on Twitter. Let’s help each other. With that, let’s get this thing started. Read on below for a detailed project plan.

Aurora Theme Project Plan

Business Justification

The WordPress REST API was merged into WordPress Core in December 2015. The REST API gives developers a modern way of interacting with WordPress using modern JavaScript techniques and technologies. By default, WordPress ships with endpoints to interact with standard post types (posts and pages), but it can be extended to create custom endpoints which may include post meta, or anything else one might need from the database.

Implementation of the REST API gives WordPress users and developers several advantages. WordPress can continue to operate as a familiar and robust backend for data storage and delivery, while making the data itself more accessible to other platforms. Decoupling data delivery from the content management system (CMS) makes WordPress more accessible to a broader audience. For example, building a frontend to consume WordPress data no longer requires knowledge of the WordPress theming system. It frees developers up to consume their data in whatever way is necessary from use in websites, to apps, and other third party services. Instead of WordPress being the solution for a website, it can be a building block in the foundation of a user’s larger application.

Even though the REST API has been part of WordPress for nearly two years, adoption of the API has been slow, and there are few themes utilizing the features of the REST API. There are even fewer “starter” themes built on the REST API. To date, most REST API-driven projects have been limited to the “high end” spectrum of client sites. But with the imminent integration of Gutenberg, JavaScript technologies are becoming an increasingly integral part of the WordPress experience.

Aurora will be a starter theme built to utilize the features of the standard endpoints in the WP REST API, and will use modern JavaScript technologies including ES Next and React. Aurora will finally make REST API-driven sites and technology more accessible to the everyday WordPress user and developer.

Requirements & Objectives

Any starter theme built for WordPress needs to give developers a leg up in the development process, but should not include so many features that it becomes burdensome to work with. To that end, it is incredibly important that Aurora remain relatively un-opinionated, yet provide the basic features one might expect of a functional WordPress theme (i.e. if you install and activate the theme, it shouldn’t look like a dumpster fire). Ideally, any opinionated elements (e.g. styling) could easily be blasted away, giving the next developer a clean slate.

To that end, Aurora will support modern JavaScript development techniques, and give developers a solid foundation for starting a REST API project. Including documentation support is especially integral to the success of Aurora. Since WordPress has long been in the PHP-based theme paradigm, it’s important to have a well-documented theme to help PHP developers transition to writing JavaScript-driven themes.

Aurora will be a clean, modern theme with the following features:

  • Sass
  • ES Next + React
  • Icon (SVG) management
  • Linting according the WordPress Coding Standards using PHPCS, ESLint, and Stylelint
  • Documentation support

Requirements

  • Support default post types (post, page, nav-menu, comments)
  • Well-documented
  • Easy to understand
  • Extensible
  • Performant
  • Accessible
  • Gutenberg-ready

Objectives

  • Adheres to WordPress Coding Standards for PHP, styling (CSS), and JavaScript.
  • Complies with Section 508 and WCAG 2.0AA accessibility standards.
  • Meets WordPress internationalization and localization guidelines.
  • Use techniques including Atomic Design to keep the theme files organized and easy to understand.

Project Scope / Deliverables

At this time, Aurora will only consist of the starter theme. Future implementations may include:

  • Extensibility via the command line–easily spin up reusable components via a command line integration (e.g. Yeoman), which will be hosted indepently from the theme (likely via a branch of Aurora Core).
  • Gutenberg components. Support for default Gutenberg components will exist, but new components are not in scope for the initial phase of the project.
  • A plugin for interacting with Custom Post Types / Custom Endpoints.

Aurora

Aurora will be a clean, elegant starter theme with simple styling, and basic components, to help developers get started on their WordPress REST API theme projects.

  • Use Aurora Core (the non-theme boilerplate) as the base setup for the theme
    • Tweak Aurora Core Webpack setup to work with WordPress (keeping in mind that hot module replacement doesn’t work in WordPress).
      • Browser Sync
  • Use Underscores for some of the base theme files
    • header.php (pulls in styles and head scripts)
    • footer.php (pulls in scripts)
    • index.php (a fall back if our JS fails)
    • 404.php?
    • functions.php
  • Theme components (React components)
    • Header
    • Navigation (this might be a challenge given that there is no clear way of interacting with menus via the default endpoints)
    • Footer
    • Archive (home, categories, tags, etc.)
    • Single post / page
    • Sidebar (I’m really curious about supporting widgets via the REST API)
    • 404
    • Search results (maybe this is the same as the archives?)
    • Social icons (menu)
    • Comments
  • How should the theme interact with the Customizer?
    • Custom logo
    • Site title
    • Site tagline
    • Site icon (favicon)
    • Sidebar (no sidebar, sidebar right, sidebar left)
    • Widget area(s) for the footer (see Alcatraz)
    • Footer copyright text
  • Testing (Mocha? Jest? other?)
  • Performance metrics
  • Type checking
    • Flow?
    • TypeScript?
  • Documentation
    • Sass documentation
    • Component documentation (KSS? Storybook?)

Resources