forage

Introducing Forage, my new hybrid starter theme joining Roots Sage and FootMATE. This is a project of love, giving me an opportunity to learn new technologies and simplify the WordPress theme I was using. While this might not technically be the last theme I apply to my personal site, WordPress is moving into a new direction of lots of Javascript to drive a WordPress block theme.

Why Forage?

I think the mushroom kingdom that we live among is quite interesting, and the act of foraging mushrooms feels like what I do when I’m writing code: I’m always looking for something to consume and use.

Features

Forage is a starter theme. This means that when you install it, no styling or interactive behavior is added to the front-end. This gives you complete flexibility to create the theme you want with minimal opinionated code.

  • Laravel Blade as a templating engine
  • Vite for compiling assets, concatenating, and minifying files
  • Biome for linting and formatting both CSS and JS
  • Modern CSS & JavaScript – No preprocessors, libraries, or frameworks
  • DocHooks provide new functionality of class method DocBlock as hooks into WordPress API
  • IndieWeb out of the box

Laravel Blade

Sage was my real introduction to Laravel, back in the days when PHP just landed in the version 7 era, so I was mostly used to older PHP 5.2-5.4. While I tend toward wanting pure forms of HTML, CSS, and JS, I found Laravel Blade to be an interesting abstraction of PHP. In the last few years, PHP has come of age in so many great ways. PHP 7 and PHP 8, and all point releases, added superpowers for functional programming and types, among many other features. Modern PHP and TypeScript, less so even modern Javascript, have a lot in common today. In many ways, it’s impressive where PHP is today.

Laravel Blade is a modern approach to templating PHP. In a similar way that TypeScript is also Javascript, all blade files are PHP files as well which makes it convenient to get started. The main benefits of using a blade file is the cleaner looking syntax and custom components. Not  Here’s a great overview of all the strengths of Blade.

Vite

I first used Vite via Astro, and as a build tool, it felt so easy and simple. I’ve used many other build tools over the years, from grunt and gulp to webpack. I tried others here and there, but nothing stuck. Vite, however, makes a lot of sense for WordPress classic theme development.

The instance of Vite used for this theme is so lightly integrated that you wonder how it’s really doing all that magic so easily. The biggest difference? I don’t need to have two environments to see live reloads anymore. If I’m using https://example.local/ to work on WordPress locally on my computer, Vite will use the same environment for live reloading. No need to switch to a different URL like https://localhost:3000! Truly, I’ve been annoyed by this for more than a decade about Webpack! No more!

Biome

This project feels like a game changer for linting. We’ve seen several come and go, with the most popular ones being ESLint, Prettify, and Stylelint in 2024. However, Biome is positioning itself to be one tool to lint it all.

The background is interesting and having won a contest set up by the Prettier folks, Biome has a strong position going forward. I expect some breaking features as it continues to mature, but it’s also stable enough for a large majority of linting rules that I already don’t miss ESLint. As of June 2024, the CSS linting is in its first public beta release, so it’ll be some time before that’s mature enough to replace Stylelint, but I fully intend to migrate over when it’s stable.

Vite and Biome Node Packages

The most exciting thing about both Vite and Biome is reduced complexity. Just by replacing Webpack and ESLint with Vite and Biome, respectively, /node_modules/ was reduced by more than 50%. In fact, I think even more packages were removed from the project overall. This is a big win.

Once CSS linting is stable, this is what devDependencies looks like in package.json:

  "devDependencies": {
    "@biomejs/biome": "^1.8.0",
    "glob": "^10.4.1",
    "vite": "^5.2.12"
  }

That’s refreshing!

Modern CSS & JavaScript

I have purposely included no libraries, frameworks, or packages to abstract CSS or Javascript. This might be considered silly or naive, but if you review both CSS and JS in 2024, the languages are powerful enough that the need for additional state management or other helpers and shortcuts is far less than before. I expect sometime in 2025 that so much will be supported across all browsers that we’re going to see some significant paradigm shifts in the need to use large frameworks or libraries.

In fact, for my own site, I’ve removed Sass completely. Because nesting is widely supported in modern browsers, all I did was convert Sass variables to native CSS Custom Properties and everything just worked. Having reviewed the site in non-supporting browsers that don’t have modern CSS syntax features, progressive enhancement is the winner because all content and functionality is still available even if it doesn’t look as pretty.

Regardless, it’s quite easy to just yarn add svelte or any other library if you need it.

DocHooks

From the FootMATE creator, DocHooks are an interesting syntactic sugar for functions and methods to the WordPress APIs using DocBlocks.

    /**
     * Loads default theme supports
     * @action after_setup_theme
     */
    public function addThemeSupport()
    {
        /* add logic here */
    }

The part that says @action after_setup_theme is the same as writing add_action( 'after_setup_theme', 'addThemeSupport, 10, 3 );. It’s a big cleaner and easier to parse the functions this way.

Currently, DocHooks only support adding to the API. If you need to remove, you still have to write remove_action('after_setup_theme', 'addThemeSupport');

IndieWeb

I’ve added as much Microformats2 syntax to the markup as I could so that you add a few plugins and it’ll be indieweb compatible almost immediately after setting up the pieces. We should own as much of our own content as we can.

Background

The Roots Sage project provided an excellent philosophy and approaches for a progressively developed WordPress theme, but after version 9, Sage had too many interconnected pieces, new dependencies, and legacy to keep up with. Additionally, having focused on so many other  returning to an old version of Sage left much to be desired, as well as plenty of broken services or packages.

I found FootMATE in spring of 2024 looking for an alternative. Strangely, it follows enough of a paradigm similar to Sage that it feels like a younger cousin. Also, the author decided to integrate Vite instead of Webpack, and that’s a huge win for productivity and DX.

The combination of the two themes satisfies my desire for good file architecture and modern tooling without much bloat or dependencies. It just works.

WordPress’ direction towards full-site editing and Gutenberg leaves much to be desired for developers working on WordPress. This theme, while starting from a basis of the classic theme structure, has a lot of flexibility between the two worlds of classic and modern WordPress theme development.

The Future

I’m going to continue development on this theme indefinitely, as both FootMATE and Sage deliver new updates that make sense for this theme. Additionally, I already have a number of Github issues that I hope to resolve or bring into the theme.

Ultimately, I’ll probably slow down on development for this theme soon and maintain things as time goes on. Who knows, I might support this for several years to come. I don’t have all the experience or expertise for some of the integrations I am questioning or interested in, so community help will be desired where possible. That said, I’ll keep an open mind about how to continue on with this starter theme.

I’m eager to hear any feedback or comments on the direction this theme is going and how to make it better. It solves my personal needs here on asuh.com but it’ll be interesting to see what appeal it has outside of what I needed.

Thanks for your support and eyeballs on this post!