Editor’s Note: This tutorial, which was originally written for Sage 10, has been updated to work with the latest release of Sage, which is currently Sage 11. Most of the steps are the same between Sage 10 and Sage 11, but where steps differ between the two releases that will be called out in the tutorial below.
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 11 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 11:
We’re going to be installing Bedrock and Sage 11 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 11:
Now that you have WordPress installed by using Bedrock, we can install Sage 11. In your terminal, change directory over to your WordPress themes directory and install Sage 11. Replace “demo-theme” in the command with the name of the folder you wish to use for your theme.
Note that by default the commands will install the latest version of Sage, which is currently Sage 11. If you need to install Sage 10, you’ll need to manually specify the version number of the last Sage 10 release, which is 10.8.2.
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
Sage 10 – Configure Bud:
If you’re installing Sage 10, you’ll need to update your configuration for the Bud build tool. To do this, 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')
Sage 11 – Configure Vite:
If you’re installing the latest version of Sage, which is Sage 11, the Bud build tool has been replaced with Vite. To configure Vite, locate the vite.config.js file, located in the root of the folder for your Sage 11 theme.
Find the base parameter and change it to match the name of the folder you’re using for your theme. For instance, if you were making a theme where the folder was named “demo-theme”, your base path would look like this:
base: '/app/themes/demo-theme/public/build/',
Building Your Theme’s CSS and JS:
Whether you are using Sage 11 or Sage 10, the process for building your theme’s CSS and JS is the same. In your Lando terminal, you should be at a node prompt where you can run yarn. If you are not, follow the steps above to get to a prompt where you can run yarn.
To build your assets, from your terminal run the following command:
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 11 theme, although the stock version of Sage 11 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.