WordPress Development with Roots (Bedrock, Sage, and Trellis)

I got a WordPress project recently and that was the right moment to try Roots (Bedrock, Sage, and Trellis). They are tools to modernize WordPress development. Bedrock is a boilerplate to organize the WordPress project, it has a better structure to manage files. Sage is a framework to develop a theme. Trellis is a development and production environment. Let me show you how I did full-stack development using these tools.

Trellis

Trellis is a WordPress development stack, and it is easy to deploy your site just with a single command. Make sure Git, Composer, VirtualBox, and Vagrant have been installed before you get started.

I was using LAMP (Linux, Apache, MySQL, and PHP) while working on the project. But it's okay to try Trellis. So, you don't need to set up any local environment such as MAMP, WAMP, etc.

I suggest you install Trellis CLI. It can create a project with a single command, trellis new example.com, trellis up to turn on the Vagrant, and trellis down to turn off. Remember to configure your website for any environment in wordpress_sites.yml located in the trellis/group_vars folder. Feel free to explore the documentation of Trellis. We just focus on development with Bedrock and Sage here.

Bedrock

I suggest you install WP CLI. So you can install plugins, themes, and updates easily on the command line. Even with Bedrock, you can install plugins, which is require Composer, but using WP CLI is the best one.

Bedrock is pre-installed if you are using Trellis. If you don't use Trellis, you can install it using Composer, composer create-project roots/bedrock site.

The most important parts of Bedrock are the .env file and its file structure. You need to config the .env file. Copy the .env.example then rename to .env. Make sure you set the database, environment, site URL, debug log path, and keys correctly. To set keys, you can visit https://roots.io/salts.html, or you can generate them using WP CLI Dotenv Command. If you don't use Trellis, make sure you point the domain to the web folder, refer to this documentation.

Bedrock has a specific configuration for every environment such as development, staging, and production. Plugins, themes, and uploaded files are located on the web/app folder. You can install plugins, themes, and updates using WP CLI, and of course, it is working on Bedrock.

Sage

Go to the web/app/themes folder, then run this command, composer create-project roots/sage your-theme-name. Make sure NodeJS and Yarn are installed before we start to develop the theme. I suggest you install version 10 for NodeJS. I tried many versions with NVM (Node Version Manager) and it worked fine on version 10 at that moment.

Bootstrap can be pre-installed with Sage. Other frameworks available are Bulma, Foundation, Tachyons, and Tailwind. Don't forget to run yarn command, then yarn start to develop the theme, or yarn build to compile them. To compile them for production I suggest you run yarn build:production.

Sage is using Blade Templates. You need to create a controller to pass some variables then you can print them on views or Blade templates. Controllers are located on your-theme-name/app/Controllers. There is App.php for global, FrontPage.php for the front page, Single.php for the single, Category.php for the category, etc. There are admin.php, filters.php, and setup.php, they are just like functions.php on the pure WordPress theme, but you better not to add some code on functions.php directly. There is helpers.php if you need to pass some functions on views.

There are 3 config files; assets.php, theme.php, and view.php. It is okay to leave it default. You can put fonts and images on fonts and images folders on resources/assets. You can add external plugins using yarn add <plugin> then import them on main.js and main.scss, refer to this documentation.

Put your custom scripts on JS files from resources/assets/scripts/routes. common.js for all routes, home.js for the front page, about.js for the about page. You can create contact.js for the contact page. Remember, they match your routes. So, make sure they are not mismatched.

Styling SASS on Sage is a little bit complicated because there is a SASS lint turned on. You can turn it off on resources/assets/build/webpack.config.js by disabling the StyleLintPlugin on line 180, but I don't recommend this way because it will affect the production result if I not mistake. So, it's better to follow the rule, make your code clean.

Production

As I said, it is easy to deploy if you are using Trellis. If not, make sure the .env file on Bedrock is on the production environment, and the compilation of Sage is on yarn build:production.