Comprehensive Guide: Getting Started with Sage and DeployHQ

Introduction

This guide will walk you through setting up and using Sage, a modern WordPress starter theme, and DeployHQ, an automated deployment tool. We'll also use Volta to manage Node.js versions, ensuring consistency across development environments.

Sage: Modern WordPress Development

Sage is a WordPress starter theme that leverages modern development tools and build processes.

Prerequisites

1. Volta: For managing Node.js versions
2. Composer: PHP dependency manager
3. WordPress: A local WordPress installation

Installing Volta

Volta manages Node.js versions efficiently. Install it with:

curl https://get.volta.sh | bash

Restart your terminal after installation.

Setting Up Sage

1) Navigate to your WordPress themes directory:

cd wp-content/themes

2) Create a new Sage-based theme using Composer:

composer create-project roots/sage your-theme-name

This command creates a new directory with your theme name, installs Sage and its PHP dependencies, and sets up the initial theme structure. 3) Navigate to your new theme directory:

cd your-theme-name

4) Use Volta to set and pin the Node.js version:

volta pin node@14

5) Install JavaScript dependencies:

yarn

6) Build your theme assets:

yarn build

Activating Your Theme

1. Log in to your WordPress admin panel
2. Navigate to Appearance > Themes
3. Find your new Sage-based theme and click "Activate"

Development Workflow

Start your development server and watch for file changes:

yarn start

For production builds:

yarn build

Customizing Sage

Adding Custom Styles

In resources/styles/app.scss:

.custom-button {
  background-color: #4CAF50;
  border: none;
  color: white;
  padding: 15px 32px;
  text-align: center;
  text-decoration: none;
  display: inline-block;
  font-size: 16px;
  margin: 4px 2px;
  cursor: pointer;
}

Creating a Custom Block

In app/Blocks/ExampleBlock.php:

<?php

namespace App\Blocks;

use Log1x\AcfComposer\Block;
use StoutLogic\AcfBuilder\FieldsBuilder;

class ExampleBlock extends Block
{
    public function fields()
    {
        $exampleBlock = new FieldsBuilder('example_block');

        $exampleBlock
            ->addText('heading')
            ->addWysiwyg('content');

        return $exampleBlock->build();
    }

    public function render($block, $content = '', $preview = false, $post_id = 0)
    {
        return $this->view('blocks.example-block', [
            'heading' => get_field('heading'),
            'content' => get_field('content'),
        ]);
    }
}

Create a corresponding view in resources/views/blocks/example-block.blade.php:

<div class="example-block">
  <h2>{!! $heading !!}</h2>
  <div class="content">
    {!! $content !!}
  </div>
</div>

DeployHQ: Streamlined Deployment

DeployHQ automates the deployment process from your Git repository to your servers.

Setting Up DeployHQ

1. Sign up for a DeployHQ account
2. Create a new project and connect your Git repository
3. Add your server details (SSH access required)

Configuring Deployments

1. In the DeployHQ dashboard, go to your project settings
2. Set up build commands:

volta run yarn install
volta run yarn build

1. Set up SSH commands, for example:

wp cache flush
# Any other thing you need to run on the server, migrations perhaps?

These commands ensure dependencies are installed, assets are built, and WordPress cache is flushed on each deployment.

Automatic Deployments

1. Push changes to your Git repository
2. DeployHQ detects changes and initiates deployment
3. Monitor deployment progress in the DeployHQ dashboard

Integrating Sage and DeployHQ

1. Develop locally using Sage
2. Commit and push changes to your Git repository
3. DeployHQ automatically deploys changes to your server

This workflow allows for rapid development and consistent deployments.

Conclusion

By combining Sage, Volta, and DeployHQ, you create a powerful, modern WordPress development and deployment workflow. Sage provides a robust foundation for theme development, Volta ensures consistent Node.js versions across your team, and DeployHQ automates the deployment process, allowing you to focus on writing code and creating great WordPress sites.