One of the biggest complaints developers have about WordPress is that it isn’t modern. WordPress is a product of another time, with some antiquated coding practices from WordPress’ origins persisting into today. WordPress has some bad habits, like encouraging developers to place all of their code inside of functions.php and mixing PHP code with HTML and CSS.
Luckily, the folks over at Roots have a pretty awesome solution to make developing in WordPress more modern and less painful. They offer many products to make working with WordPress is 2024 much easier, but the main ones I’m going to focus on today are Bedrock and Sage.
Want to skip the introduction and jump straight to the installation tutorial? Click here.
Bedrock: A solid foundation
Bedrock is a modern boilerplate environment for WordPress. It provides a cleaner, more modular file structure for WordPress. Bedrock also provides enhanced security for WordPress by changing the default password hashing algorithm of WordPress to BCrypt instead of the old, antequated MD5 hashing algorithm.
Bedrock also allows you to manage plugin updates, as well as WordPress core updates using Composer, a package manager for PHP. This allows you to easily keep local, staging and live environments in sync with the same plugin versions. Speaking of different environments, Bedrock also supports separate environments, including config variables, for your local, development and live environments. No more keeping everything in one messy config.php file.
Sage: A modern starter theme for WordPress
Sage 10 is a modern starter theme for WordPress that helps you keep your data and back end logic separate from your front end presentation data. Whereas in standard WordPress, you might have PHP template files that contain the loop and any back end logic or queries plus your front end logic, with Sage 10 your back end logic and database queries are kept separate from your front end HTML. This is done through the use of Composers.
Don’t let the name fool you, Sage 10 Composers are different from the Composer package library in PHP. Why the name Composer was chosen for this crucial piece of the Sage 10 ecosystem was chosen I don’t know, but what’s important to remember is that Sage 10 Composers are a place to put all of your back end logic. When your website loads, Sage 10 looks to see if there is a Composer associated with the Blade View for the current page. If there is, the Composer can pre-fetch any data your Blade View will need and returns that data and makes it available to your Blade View.
So, what’s a Blade View? Well, in regular WordPress you might have a a template like “index.php” or “front-page.php”, but Sage uses the Laravel Blade templating language. Sage 10 replaces standard PHP templates with Blade PHP templates and gives the files an extension of .blade.php. So, index.php becomes blade.index.php and front-page.php becomes front-page.blade.php, and so on for the rest of your WordPress templates.
What this also does is enable you to use Blade Partials inside of your templates. A partial is what it sounds like, a partial template. So, you might have your front-page.blade.php file and then have a different partial for each piece of your front page, such as hero.blade.php and recent-posts.blade.php. Partials can be re-used in multiple places on your site and with Composers you can pass data directly to a specific partial. Instead of having to get the recent posts for the front page, the recent posts page and the archive page, just get the data one time, in the recent posts Controller and pass that to the recent-posts.blade.php partial.
For the following tutorial we’ll be using Lando, a local development environment for Windows, Mac and Linux. You can still follow along with the tutorial if you’re using a different local development environment, but some steps will be different and you may need to install some additional software on your local machine.
How to install Bedrock and Sage 10:
We’re going to be installing Bedrock and Sage 10 by using the Lando local development environment. You might see some commands prefixed with a “lando” prefix. If you’re not using Lando, go ahead and omit that prefix when running commands.
If you’re using Lando, you can use the following Lando file to set up your local environment so you don’t need to install any software. Create a new folder and then create a new file named .lando.yml inside of the folder. If you’re on Windows, you may need to show hidden files and ensure that file extensions are being shown.
Inside of your Lando file, you can add the following code:
name: bedrock-sage
recipe: wordpress
config:
webroot: web
php: '8.3'
composer_version: '2.7.6'
services:
node:
type: node:20
env_file:
- .env
This file will configure a local development environment with all of the required software packages required to run WordPress, Bedrock and Sage 10, including Composer and Node.
Once you have this file inside of an empty folder, you can run lando start from a terminal to spin up your local development environment. In a few minutes, you’ll have a blank development environment we can use to install Bedrock and Sage.
Installing Bedrock and WordPress:
You’ll want to instruct Lando to install Bedrock using Composer. To do this, from your terminal run:
lando composer create-project roots/bedrock
If this command was successful, you should now see a “bedrock” folder that contains a bunch of files. While you can leave your code inside of a sub-folder, I like to move everything from the bedrock folder back to the parent folder that contains the .lando.yml file. You can do that with the following commands:
shopt -s dotglob nullglob;
mv bedrock/* ./;
rmdir bedrock;
Configuring our Environment File:
Bedrock ships with an example environment configuration file, which you can see in your project is named .env.example. Create a new file named .env and copy the contents of this example file into your new blank .env file.
At the bottom of the file, you should see some keys and salts. Go to the Roots Salts Generator and copy the generated ENV Format salts into your .env file in place of the placeholder data. These salts should be unique for each site you create as they are responsible for encrypting your database credentials such as user account passwords.
In the file, find the WP_HOME parameter and replace this with the URL you will use for local development. If you’re using the .lando.yml file from earlier, you’ll want to use a value of: https://bedrock-sage.lndo.site
Update your database credentials in the .env file to match those of your local database. If you’re using Lando, you can use these credentials:
- DB_NAME = wordpress
- DB_USER = wordpress
- DB_PASS = wordpress
You’ll also need to uncomment the DB_HOST parameter and set that equal to a value of database. When you’re done, your file should look something like this:
DB_NAME='wordpress'
DB_USER='wordpress'
DB_PASSWORD='wordpress'
# Optionally, you can use a data source name (DSN)
# When using a DSN, you can remove the DB_NAME, DB_USER, DB_PASSWORD, and DB_HOST variables
# DATABASE_URL='mysql://database_user:database_password@database_host:database_port/database_name'
# Optional database variables
DB_HOST='database'
# DB_PREFIX='wp_'
WP_ENV='development'
WP_HOME='https://bedrock-sage.lndo.site'
WP_SITEURL="${WP_HOME}/wp"
# Specify optional debug.log path
# WP_DEBUG_LOG='/path/to/debug.log'
# Generate your keys here: https://roots.io/salts.html
# Your keys should be pasted here
The WP_ENV parameter should be set differently depending on whether you’re working with a development or live environment. For live environments you would set this to a value of production, for everything else a value of development is fine.
If you’re using Lando, do a rebuild of your configuration by running this command:
lando rebuild -y
Lando is now going to rebuild its configuration and get you to a point where you can install WordPress. If everything is correct, you should get a green URL inside of your terminal.
Installing Acorn:
Sage 10 Requires the Acorn package to function properly. Since we’re using Bedrock, we can install Acorn at the root of our project using the following command:
lando composer require roots/acorn
Installing WordPress:
Go to the URL you specified for your local site in your config and run through the standard WordPress installer. If you’re using Lando, the URL should be:
https://bedrock-sage.lndo.site/
Installing Sage 10:
Now that you have WordPress installed by using Bedrock, we can install Sage 10. In your terminal, change directory over to your WordPress themes directory and install Sage 10. Replace “demo-theme” in the command with the name of the folder you wish to use for your theme.
Here’s the full commands to run on Lando, assuming you’re in the root directory of your project:
cd web/app/themes/
lando composer create-project roots/sage demo-theme
Building Theme Assets:
We now need to build the assets for the theme. We need to get to a terminal where we can run yarn. Using Lando, you can get to this point by running:
cd ./demo-theme
lando ssh -s node
yarn
Now, update the bud.config.js file inside of your theme’s directory with the URL of your local site.
Replace:
.setProxyUrl('http://example.test')
With:
.setProxyUrl('https://bedrock-sage.lndo.site')
Then from your terminal, run:
yarn build
If everything has been done correctly up until this point, all of the CSS and JS assets for your theme should now be compiled and ready to go.
Activating the Theme:
Inside of WordPress, go to Appearance > Themes and activate the Sage Starter Theme. Your site should now be using the Sage 10 theme, although the stock version of Sage 10 without any modifications is very ugly.
Let’s start off by doing some testing though. Go ahead and make a new page for your homepage, add some content and then set it as your front page by going to Settings > Reading and setting that page as your homepage. If everything is working great, you should see your new page when you go to your site’s homepage.
It’s going to look ugly though, because Sage 10 is a very bare-bones starter theme as far as styling. It’s a blank canvas for you to start developing a highly-custom WordPress site.
What’s next?
You’ve reached the end of this tutorial. I realize that we’ve only begun to scratch the surface of Sage 10, so I’m going to be writing more tutorials about building sites with Sage 10 in the future. If you want to see more content like this, please leave a comment on this article as your comments will encourage me to keep writing.
As far as where you can go next with your Sage 10 theme, here are some suggestions:
- Commit what you have to a git repository so you don’t have to do all of these setup steps again if you make a new site
- Replace Tailwind with Bootstrap in Sage 10, or if you’re weird like me and don’t like CSS frameworks, remove Tailwind and stop after Step 1 of the “Adding Bootstrap” section of that guide to have a site using SCSS with vanilla CSS
- If you’re old-skool, add jQuery into your Sage 10 theme
- Read up more on theme templates and Blade templates
- Read our tutorial on configuring WordPress Multisite with Sage 10
- Check out the Roots Community Forums
Getting Additional Help:
If you would like personal, 1 on 1 help using Sage, Bedrock or just WordPress in general, I’m available for paid mentorship sessions. You can contact me for more information or schedule a free consultation with me to learn more and discuss your personal learning plan with me.