Hatchet: A WP theme for small agencies Oct 30, 2022

Hatchet is a new WordPress theme designed to meet the specific needs of small agencies and WordPress shops. A major challenge facing small agencies building on WordPress is how to build those themes.

Hatchet is a new WordPress theme designed to meet the specific needs of small agencies and WordPress shops.

A major challenge facing small agencies building on WordPress is how to build those themes. Most end up in one of two camps; build bleeding edge and go headless, or build with something like Elementor. Both approaches are fraught for a small agency.

Let's examine the two and for example's sake, let's take a small agency of 8, with 2 developers. This is a fairly common dev/team ratio.

The bleeding edge of WP

Imagine you (or if you're nontechnical your devs) decided to go Headless with Vue. There are some really great things about it, like

  • Modern development toolchain
  • Practically instant page loads
  • Very robust
  • Light-weight

You'll notice that none of these items benefit the agency's client in a meaningful way outside of page load times. There are however a number of downsides including

  • Significantly increased dev time
  • WordPress updates are more fragile
  • Duplicate hosting requirements
  • Plugins no longer 'just work' and require custom development

These downsides in contrast to the upsides do directly impact an agency and its clients in the form of costs and usage difficulty. This more specialized development approach is affected by one other major concern and that is hiring.

Skilled WordPress developers are reasonably common, and Vue developers while far fewer are not difficult to hire. However, a WordPress developer skilled in Vue? That's a rare beast indeed. And rare is expensive.

The WP Theme Builders

Your shop has made the choice to dive straight into Elementor, and man there are some really great upsides.

  • rapid development time
  • lots of starter themes
  • low costs
  • elementor developers are everywhere
  • uncomplicated tooling (because there is none)

Those are some great reasons to go with elementor. Inexpensive labor is readily available, your dev times are short, and your project costs are slashed. But it comes at a cost

  • markup is slow and unweidly
  • you're begging for an ADA lawsuit
  • clients can edit, but it's complicated for them
  • limited flexibility in design
  • code output is garbage

Those are the kind of downsides that should give every agency pause.

The choices are, simplistically, to build glorious and expensive or build cheap garbage.

And those are not the kind of choices an agency trying to serve small and medium-sized businesses needs to make. That's where Hatchet comes in.

Hatchet is a base theme and development paradigm that results in easy-to-maintain themes that are just as easily managed by the end user. It leverages ACF and no other plugins to achieve that.

It's built around the concept of fully block-scoped CSS and compartmentalized blocks. A black should contain all its own styles and markup, and should exist almost entirely apart from all other blocks.

Hatchet is on Github, you should check it out. If you have a small agency, and want to build real, custom WordPress-powered sites without losing your ability to hire and get really awesome work out the door at a reasonable rate, then Hatchet is the place to look.

The below is an excerpt from the project readme.


You'll find that Hatchet

  • ships as a functional blank slate
  • contains all necessary theme files and templates to run out of the box
  • is framework agnostic
  • is opinionated about structure
  • easily maintained

Requirements

  • requires Node (or something like preprocess but that is untested)
  • requires ACF (pro) *note that fields are created not from the UI but within the theme for obvious reasons.

Getting Started

Clone or download this repo in your /wp-content/themes/ folder. Rename or not, as you choose. Rename .envsample to .env.

From the theme's directory run npm install to install the required dependencies.

Theme Organization

/assets/ the folder contains all the compiled and minified assets for the site. The content of the folder should not be committed to git, nor manually deployed to a server. The build pipeline will generate and deploy all necessary files.

/src/this folder and it's subfolders contain the source files and images that are compiled and dumped into /assets/. Everything within this /src/ folder should be committed to git. /src/js/ contains less.js which compiles the JS directly in browser when in dev mode. The images within /src/img/ are also compressed and delivered to /assets/.

/blocks/ contains all the blocks we use within the editor, and are typically editable directly within the Gutenberg editor within WordPress.

/ contains the gulp and pkg files necessary to compile using gulp or the build pipeline. gulpfile.js, less.js, package-lock.json, and package.json should be committed to git.

The remaining files & folders are not unique to Hatchet, and behave as you would expect.

Usage

Hatchet expects you to structure the majority of your code into blocks, and you want the content of those blocks to be easily managed from within the WP Editor. To realize these assumptions, each block is a folder within blocks/ containing a setup.php file and a render.php file, and a matching less file in the less source.

An example

Have look at an example of a small component.

render.php

<section class="section announcement">
	<div class="inner">
		<h3>Hello there!</h3>
		<p><strong>Announcement Title Here</strong>Curabitur blandit tempus porttitor. Etiam porta sem <a href="#">malesuada magna mollis</a> euismod. Maecenas sed diam eget. </p>
		<a href="https://txnhog.co" class="button">Learn More</a>
	</div>
</section>

_announcement.less

.announcement{
	.inner{
		position: realtive;
	}
	
	h3{
		font-size: 1.3rem;
	}

	p{
		font-size: 1.2rem;
	}

	strong{
		font-weight: normal;
		font-style: italic;
	}

	a{
		text-decoration: underline;

		&.button{
			background: #333;
		}
	}
}

In this short example, you would create a folder inside blocks/ named announcement, and inside it you would create the setup.phpand render.php files. The setup.php file is automatically loaded by WordPress from the block's folder.

Within render.php would be the html and function calls to ACF for display, setup.php would contain the setup of those ACF fields and their options, allowing the custom blocks to display within the Gutenberg editor when editing a Page.

Finally, you would create the associated less file inside ./src/less/components/blocks/ as _announcement.less, and then link it inside ./src/less/style.less like so: @import 'components/blocks/_announcement.less';

Regarding styling, .section would be generic and provide defaults that apply to most sections of this type. .announcement would match the component name components/blocks/_announcement.less, and be used as the parent for the specific styles of this component. If this component differed from the generic, and had a background image that would be styled on .announcement. If the h3 tag differed from the generic that would be styled as .announcement h3.

This gives us a significant level of control while maintaining flexibility. It also makes the blocks we create for one site easily portable to another site or theme. This approach to scoping also lends itself to predictable rendering within the editor.

All JS placed within /src/js/ will be compiled into /assets/scripts.js. jQuery is enqueued from CDN by default.

Gulp Usage

Gulp is used to compile and minify either the LESS or less (as you prefer), as well as the JS in the project. It also compresses and moves images from the /src/img/ folder to /assets/.

The gulp commands available to you are as follows: gulp - the default gulp command will watch & compile your JS and LESS.

  • gulp watchAllLess - will watch & compile your JS, LESS, and minify your images.
  • gulp watchLess - will watch & compile your LESS.
  • gulp watchJs - will watch & compile your JS.
  • gulp watchImg - will watch & minify your images.
  • gulp lessTask - will compress your LESS and quit.
  • gulp jsTask - will compress your JS and quit.
  • gulp imgTask - will minify your images and quit.

Using Less

LESS can be used in compiled mode or in live reload mode. When in live reload, changes made to your LESS files will be reflected on the current page immediately (ish) when the LESS is saved. You can activate or deactive live mode as shown below.

Your .env

The env supports the MODE flag with 3 different settings, mvp, dev, and production.

  • mvp When set to mvp, the compiled CSS will load after the inclusion of Andy Brewer's excellent https://andybrewer.github.io/mvp/. MVP CSS will give you a set of base styles if you're throwing something up quickly, or even for a lean production site - see it in use on https://imgy.dev.
  • dev When set to dev the compiled css is not loaded, and instead the LESS is loaded and compiled directly in the browser through the inclusion of the LESS.js file, with styles reloaded automatically. Make sure you have the developer console open in your browser.
  • production compiled CSS is loaded from assets.