Mozilla Builders

A WordPress theme for Mozilla Builders.

Table of Contents

• 🎁 What's in the Box
• 💻 System Requirements
• 🛠 Installation
• Plugins
• Command Line
  • Project scripts
  • DDEV commands
  • Using composer
  • Using WP-CLI
• Debugging
  • Twig Functions
  • Error Logs
  • Debug Bar & Timber Debug Bar Plugins
• 🚀 Deployment
• 📰 Gutenberg
• ♿ Accessibility Testing

🎁 What's in the Box

• Full Timber integration.
• Local development setup with DDEV.
• Code bundling with Webpack, including:
  • BrowserSync
  • Autoprefixer
  • CSS Extraction
  • Environment Variable Injection
• Linting and testing
  • JS, CSS, and PHP linting thanks to Prettier, ESLint, and phpcs
  • Static analysis of PHP code with PHPStan
  • Accessibility testing with pa11y
  • Bundle size limiting with bundlesize
  • Husky to automatically run these lints and tests!
• CI setup with GitHub Actions

💻 System Requirements

This project assumes that you have the following installed globally:

• NVM to manage your Node environment.

You'll also need a way to run a LAMP/LEMP (Linux, Apache/nginx, MySQL, PHP) stack on your machine. This project comes configured to run with DDEV, a docker-based development environment.

1. Install Docker Desktop for Mac: >= version 4

2. Install DDEV with Homebrew with brew install ddev/ddev/ddev. (If you don't have Homebrew, you can also use the Get Started guide on the DDEV website for alternative installation methods.)

🛠 Installation

Note that these installation steps assume that you're using the DDEV configuration.

1. Run nvm install to ensure you're using the correct version of Node.

2. Duplicate the contents of .env.sample into a new .env file.

3. Duplicate the web/auth.json.sample file and rename it to web/auth.json. Search for this project's auth.json entry in 1Password and copy its contents into your auth.json file.

4. Run the install/setup command

   npm run setup

5. Once the installation script has finished, run the start command

   npm run start

6. The site should be up and running with BrowserSync at http://localhost:3000, which proxies https://mozilla-builders-wp.ddev.site.

7. To access WP admin, visit https://mozilla-builders-wp.ddev.site/wp-admin. The default credentials are admin / password. You may need to click on an 'Update Database' button the first time you log in; the defaults are fine here.

To shut down the container and development server, run npm run stop.

Note that DDEV doesn't work very well with other similar packages, like Lando or Ups Dock. If you run into issues with the setup script around a port already being allocated, try stopping other environment tools to see if that clears up the issue.

If you'd like to stop the DDEV tool, you can use the command ddev poweroff.

Plugins

Plugins are managed with Composer. See the Wiki entry on plugins for more information on commonly used plugins, including the Upstatement Editorial plugin and ACF.

Command line

This project has a few command line scripts that can be used to perform common actions, like starting all aspects of the development server or exporting/importing the database. In addition, DDEV provides a number of commands that can be used to interact with the local environment directly.

Project scripts

The following scripts are helpers that wrap a number of commands around a common task.

Set up the environment for the first time

npm run setup

Start the environment

This command starts the containers with DDEV and starts the local development server for static assets.

npm run start

Lint

# Lint or fix JavaScript
npm run lint:js
npm run fix:js

# Lint or fix PHP
npm run lint:php
npm run fix:php

View PHP error logs

npm run phplogs

Export the database

npm run export-db

DDEV commands

The following lists our a few common DDEV commands that can be useful for developers:

SSHing into the container

ddev ssh

Using composer

PHP dependencies, including WordPress plugins available in the public plugin directory, are managed with composer. You can interact with composer via ddev:

Install from composer.json:

ddev composer install

Require a new WordPress plugin package:

ddev composer require wpackagist-plugin/wordpress-seo

Using WP-CLI

The environment comes configured with WP CLI; you can run WP CLI commands via the ddev wp command.

Make sure that your container is started with ddev start.

To update the local WordPress version:

ddev wp core update

Debugging

Follow this guide to debug Timber templates: https://timber.github.io/docs/guides/debugging/#enable-debugging

Twig Functions

In twig files, there are two common function you can use to print variables to the page: dump() and print_r.

<pre>
  {{ dump(your_variable) }}
</pre>

{{ your_variable | print_r }}

Error Logs

The gitignored logs/error.log file is a good place to look when hitting “critical error” screens during development. You can print to them using the error_log function, and can track updates to them in realtime using the following command:

./bin/logs

Debug Bar & Timber Debug Bar Plugins

For more in-depth information like showing query, cache, and other helpful debugging information, you can install and enable the Debug Bar and Timber Debug Bar plugins.

🚀 Deployment

When creating a deployment, we recommend generating a new release for your project with an appropriate version bump to the theme's version. This will help facilitate cache-busting for static assets, which receive the theme's version as a query string appended to the end of the path.

You can use the following script to bump the version numbers in this project's package.json and the theme's style.css (which is where the theme pulls the canonical version from):

./bin/versionbump [<newversionnumber> | major | minor | patch | premajor | preminor | prepatch | prerelease]

By default, running the script with no arguments will result in a patch version bump (so, from 1.0.1 to 1.0.2). The script utilizes npm-version behind the scenes to define the new version number; see those docs for more information on the available version options.

📰 Gutenberg

This theme has built-in support for building custom blocks. The wiki article on Building Blocks in the Starter Kit repo has more documentation around the different methods for creating blocks and how to build them.

♿ Accessibility Testing

Pa11y is an automated tool that audits our website's pages for accessibility issues according to WCAG 2.1 AA standards. This tool captures machine detectable errors such as missing alt text, wrong heading order, browser errors, etc. For issues such as color contrast, keyboard navigation, or VoiceOver functionality, manual testing is advised.

To run the tests, run the following command:

npm run test:a11y <url>

where <url> is a valid URL, or one of local, staging or live. Running the command without specifying the url will default to local.

Configuring pa11y

The package.json file has preset configurations for pa11y under testing.accessibility.

• paths (array): Paths appended to the specified URL.
• ignore.codes (array): WCAG codes to ignore
• ignore.selectors (array): CSS selectors to ignore