My WordPress Stack: Sage, ACF and Trellis

February 17, 20204 min read

This article is a summary of a presentation I gave to colleagues at Infinity Works following the delivery of a small WordPress site.

My slides for this presentation—edited for the client’s privacy and security—can be found here.

These are a set of recommendations based on many years of WordPress development: I have tried a great number of frameworks, starter themes and development environments but these are the ones that have stuck with me.

All of my WordPress projects are for paying clients, have detailed designs and are expected to be in production for a number of years. For these reasons I look for three things:

  • Reliability, longevity and a strong community
  • Flexibility and the ability for me to accomplish what I need to without hacks
  • Modern tooling and best practices

A note on Gatsby

The next WordPress project I develop will most likely be based on Gatsby and the WordPress REST API. When I started my last project there were constraints that meant this was not an option.

Development-experience aside, Gatsby may prove especially useful in two specific scenarios:

  1. The project combines (or may one-day combine) data from multiple sources (WordPress, Shopify, private API’s, etc.)
  2. The project receives
  3. Security

However, it is worth considering the limitations around page previews in Gatsby.

Sage Starter Theme

The majority of off-the-shelf themes are aimed at non-developers and provide an impressive amount of customisation through their admin interface, with little-or-no coding required. This is great if you want to start with a base theme and change a few colours or fonts, but you quickly become stuck when the theme doesn’t look anything like the Sketch files you’re UX designer has just Slacked you.

Sage is a blank canvas: it gives you a set of tools but you have to build it yourself.

Modern build tools

Node, Yarn, Sass, ESLint, StyleLint, Webpack.

Blade templates

The Blade templating language, lifted from the Laravel framework, introduces the concept of layouts and partials to WordPress as well as offering a cleaner syntax to your PHP loops:

  @extends('layouts.base')

  @section('content')
    @while(have_posts())
      {!! the_post() !!}
      @include('partials/content-single')
    @endwhile
  @endsection

It is worth noting that the introduction of Blade in Sage 9 is installed with, and requires, Composer. This may cause your project to be incompatible with hosting environments in which you do not have access to SSH (such as WP Engine).

Thankfully, there is a workaround for this.

Bootstrap (or Foundation or Bulma or Tailwind or nothing)

I choose to setup Sage projects using Bootstrap Sass.

Because you don’t always have complete control over WordPress’ markup I rely on a combination of Bootstrap classnames as well as use of the @extend syntax. For example, this is how I might override the presentation of an embed object:

  .wp-block-embed {
    @extend .embed-responsive;
    @extend .embed-responsive-16by9;

    iframe {
      @extend .embed-responsive-item;
      @extend .mb-3;
    }
  }

Advanced Custom Fields

Advanced Custom Fields allows you to visually create custom page attributes and apply them to certain pages, post types and templates.

**Note: ** most of these features require the use of a Pro license.

Per-page Custom Fields

The majority of custom fields relate to specific pages or post types (pages, posts, your own custom post types, etc.).

Gutenberg Blocks

In WordPress 5, with the introduction of Gutenberg, ACF adds the ability to create custom blocks allowing you to closely mirror the public site in the WordPress editor.

Options Pages

I also use ACF to create Options pages, allowing admins to update certain attributes through the CMS: strap-line, tracking code, etc.

ACF in Production

To avoid inconsistencies in ACF setup between development, staging and production environments I recommend exporting and registering the fields as PHP. Not only does this give you the ability to version ACF changes, but it also reduces the amount of calls to the database and therefor improves performance.

Trellis

Trellis brings Infrastructure as Code to WordPress using the Ansible provisioning tool.

Trellis does two things for us:

  1. Provisions local development environments using Vagrant
  2. Handles deployment to staging and production servers