Boilerplating WordPress

Dave Green

Director, Senior Developer
and Workflow Nerd at Make Do

@davetgreen

www.makedo.net

WordPress Development, Design and Support Agency

Kapow!

github.com/kapow-wp

boilerplate

boi-ler-pleyt - noun

Reusable code, structure, tooling and configuration to help you hit the ground running on new web development projects.

Why Boilerplate?

Some of the Benefits

  • Helps to reduce project set-up fatigue
  • Allows you to jump into development sooner
  • Reduces the unnecessary repetition of tasks
  • Time savings can potentially increase profitability
  • Great opportunity to introduce best practice
  • An excuse to learn about new tools and techniques

What to Boilerplate?

Start thinking about your development boilerplate as a series of modules that work together

Modular thinking prevents
Big Picture Panic ™

Skeleton

The overall structure of your boilerplate, into which all the component modules fit in.

Local Environment

Decision:
Which local development environment to use?

Suggestion:
Consider using the Vagrant virtual machine along with Varying Vagrant Vagrants (VVV) or similar.

Why Vagrant & VVV?

  • More modern, streamlined way of working
  • Consistent environment within teams
  • Useful technology stack to aid development
  • Much closer to using a hosting environment
  • Great for theme/plugin and core development
  • Widely used with considerable community backing
  • Absolutely free!

Folder Structure

Think about all the files and folders that will live in the project, and flesh out a structure to cater for them.

Focus on keeping this tidy and well organised, with as much kept out of the root of the project as you can.

assets/
  css/
  img/
  js/
  scss/
build/
  wordpress/
  wp-content/
  index.php
  ...
docs/
grunt/
provision/
reports/
static/
vendor/
...

Development Assets

Decision:
Should development versions of front-end assets live inside or outside the theme?

Suggestion:
Keep your development JS and (S)CSS files in the assets/ folder in the root of your skeleton, and compile production assets directly into the theme itself.

Configuration Files

  • Bower/Yarn & NPM for front-end dependencies
  • Composer for back-end dependencies
  • PHP Code Sniffer ruleset (phpcs.xml)
  • .gitignore file for version control management
  • Provisioning scripts for VVV etc
  • WP config and local config

Task Runner

Software that automates the execution of various mundane and repetitive tasks during development.

Which tool?

Decision:
Should I use Grunt, Gulp, Webpack? Many choices. Wow.

Suggestion:
There is no right answer; simply use the tool that works best for you. Grunt is slower than Gulp but offers easier configuration, and is currently used in WordPress core development...

But Webpack & NPM scripting is the future...

Aim to Have

  • Concatenation and Uglification of All the Things
  • Enhance your CSS by adding things such as browser specific prefixes with tools such as PostCSS
  • Use tools like Spritesmith and Grunticon for PNG image sprite and modern SVG/PNG icon techniques
  • Linting of your PHP, (S)CSS and JS code for errors
  • Tasks for copying, syncing and cleaning up files

Other Considerations

  • Generate documentation for PHP, (S)CSS and JS
  • Use Modernizr for browser feature support and media query detection to aid progressive enhancement
  • Automatically scan and check for accessibility issues in your theme or plugins
  • Analyze the performance of the site using tools such as PageSpeed Insights, WebPageTest etc
  • Build a living, modular styleguide from your (S)CSS

(S)CSS

The foundation upon which your site's overall layout, look and feel are based.

Aim to Have

  • A predictable, well organised file and folder structure
  • Plumbing for any frequently used frameworks/libraries
  • Global variables for things like spacing, typography etc
  • A toolkit of useful mixins and functions specific to you
  • Default styles for common WordPress elements like post content, inline images, galleries, comments etc
  • A modular mindset with All the Partials!
/base/
/components/
/modules/
/structures/
/templates/
/vendor/
/xconfig/ <-- X is for OCD!
  _hacks.scss
  _legacy.scss
  admin.scss
  editor.scss
  login.scss
  rtl.scss
  style.scss

Frameworks

Decision:
Which framework? Foundation, Bootstrap, Bourbon? Help!

Suggestion:
There's no right answer here. Foundation and Bootstrap offer more in the way of re-usable components. Bourbon + Neat is more a lightweight approach with less bloat.

Theme

A more enhanced starter theme than your typical boilerplate theme such as _S or Roots.

_S theme is a great blank canvas for theme shops, but needs an additional layer for bespoke work

Improvements

  • Add useful WordPress action and filter hooks to keep your templates free of bloat
  • Introduce new template parts and custom page templates for common layouts and features
  • Take a more granular approach to functional includes instead of overloading functions.php
  • Add or a remove common templates used as part of the WordPress template hierarchy

Moar Improvements

  • Register commonly used theme features, navigation menus and widget areas out of the box.
  • Define commonly used global site sittings via the Customizer API e.g. contact details.
  • Add cache-busting timestamps for scripts and stylesheets being enqueued, using the filemtime() function to get the file modified date

Your
Core Plugin

The home of custom, commonly used functions that add to or modify your theme.

Do I need this?

Decision:
Should I build a plugin or do this in the theme?

Suggestion:
If you have a number of custom functions that you use on nearly every project, put them in their own plugin: hooking in to the theme where required. This is your WordPress toolkit.

Potential Functions

  • Filter the contents of posts and pages
  • Add security features to help prevent various attacks
  • Modify the widgets that appear in the dashboard
  • Introduce extra functionality to help with SEO
  • Enhance the post editor/media manager
  • Modify roles and capabilities for users

Project
Core Plugin

Contains the business logic of the site, keeping it separate from the presentation found in the theme.

Things to Register

  • Custom post types and associated taxonomies
  • Meta boxes for post types, taxonomies and users
  • Customizer settings, panels, sections and controls
  • Project specific changes to roles and capabilities
  • Custom functionality that should act independently of the theme, should it be changed
  • Modifications to other plugins via actions and filters

If one specific feature of the site represents a sizable percentage of the code in this plugin, you should refactor the functionality into a separate, dedicated plugin.

Setup Script

A means of automatically creating and setting up a new instance of your development boilerplate.

Do I need this?

Decision:
Should I build a setup script?

Suggestion:
Aye! Especially for complex boilerplates and teams. Lots of time can saved by automating the new project setup.

It does require some knowledge of shell scripting, but that is fun to learn and great for personal development.

Potential Tasks

  • Create the new repository in GitHub/BitBucket and push
  • Fetch other repositories or files and move their contents into the right place in your boilerplate.
  • Carry out string replacements to update placeholder text e.g. to change Dummy Site to Client Name Site
  • Install all of the various dependencies e.g. npm install
  • Install WordPress and any common plugins via WP CLI
  • Provision the site if you use VVV or similar

Wee Bits of Advice

Anything repetitive is fair game for your boilerplate

Focus on minimal bloat; just don't try to add the kitchen sink!

Documentation. Documentation. Documentation.

Plan for regular updates and bug fixes as part of your monthly schedule.

Be opinionated; after all it's your boilerplate.

Listen to feedback and seek objective opinions.

Encourage others to get on board with your boilerplate project.

Treat it as a passion project and have FUN.

Treat it as a passion project and have FUN.

Your boilerplate will always be several months behind where you want it to be. Deal with it.

Thank You! Questions? :)

https://davetgreen.github.io/boilerplating-wordpress-talk/

@davetgreen

www.davetgreen.me

www.makedo.net