F/R/A/M/E Boilerplate

A starting point for modern WordPress sites, designed to be used in conjunction with Frame Creative's Hosting environment and deployment pipeline

Features - WordPress

• 🎉 Composer support for plugins, themes and packages
• 🎉 Autoloader support and default theme namespace autoloader via Library folder
• 🎉 MU plugins autoloader from Roots/Bedrock
• 🎉 Dot Env for environment management
• 🎉 Twig Templating
• 🎉 Basic MVC-esque theme organisation ( not true MVC, more helps with code organisation )
• 🎉 Timber library for vastly improved OOP WP experience
• 🎉 Extensible models per post type via Timber's class_map
• 🎉 Virtual page templates to use via router functions

Features - Front End

• 🎉 NPM / Yarn support (yarn preferred)
• 🎉 Browsersync & hot reloading via npm start / yarn start
• 🎉 Support for ES-6 / ES-2016 via Webpack & Babel
• 🎉 Support for ES-6 Modules & import statments
• 🎉 Support for SASS / SCSS via node-sass
• 🎉 Auto generation of source maps ( js & css )
• 🎉 Auto hard asset-reving for cache invalidation in production builds (js & css)
• 🎉 Auto removal of console.log statements in production builds
• 🎉 CSS autoprefixer and minification on production builds
• 🎉 SVG spritesheet generation, minification and lazyloading
• 🎉 Automatic modernizer builds, via scanning the css & js files to determine required tests

---

First Run

A decent amount of work has gone into first run optimisation - the project works best when using in conjunction with Laravel's Homestead virtual environment, installed globally and made available globally on the CLI via the bash alias

Naming conventions

The setup script can take care of a LOT for you if you commit to some naming convetions. It's all based around a "project name", which is ideally a single word, lowercase, no spaces.

# Example project name
mycoolwebsite

you should clone this repo into a folder of the same name

# Example git clone
git clone https://github.com/framedigital/wordpress-boilerplate.git mycoolwebsite

Enter the project name into the setup.sh script when prompted

When configuring homestead or your dev environment you should aim for the project name as the website url and db name - mycooolwebsite.dev and mycoolwebsite respectively.

If you deviate from this naming convention then please check the following files to ensure the details are correct

package.json

wp-cli.yml

.env

Pre-requisites

Homestead has everything we need to serve the site, for dev locally you will need

• php 5.6+
• composer
• node
• yarn

Laravel's valet is also a great way to get up and running, though it's a little less solid now that homebrew has changed its approach to PHP packages.

Setup / First Run helper script

#Example first run
cd ${path-to-this-project} && bash ./setup.sh

# The script will prompt you for a project name before beginning

---

Development

Installing Plugins

Plugins from the WordPress repository are available via the wpackagist-plugin vendor - eg: composer require wpackagist-plugin/placekitten

For paid 3rd party plugins avialable via Frame's hosted composer repositories please see our included list

You will need an auth.json file to access this password protected repository - Frame Creative will provide you with these credentials if necessary - please avoid checking them into any public repository

We recommend ACF Pro for custom fields / content, and Gravity Forms for form display and processing, both of which are available via frame-plugins

# Example: Install gravity forms via composer
# Run from project root (where composer.json / auth.json are)
composer require frame-plugin/gravityforms

Installing JS Dependencies

Anything you can install with Yarn / NPM is up for grabs!

Webpack will create a minified bundle for any JS file in the root scripts directory of the theme, so if you want to split your code into multiple bundles then create multiple files, only import what you need, and enqueue them in wordpress accordingly.

When enqueueing assets, be sure to use the assets helper class when enqueueing to take advantage of the hard asset-revving for cache busting.

Because this uses manifest.json and file name based versioning, it's safe to set really long expire headers on your assets, perfect if you're serving them via a CDN like cloudfront as you don't need to bother with invalidating the old file 💥

Live reload / Browsersync / General Dev kick off

Navigate to the project root in your CLI and run

yarn start

This will kick off the watch / rebuild process, and start a proxied browsersync connection to whatever url is set in package.json

Visit http://localhost:3000 to access the site and use browser sync

Renaming the theme / changing themes

Feel free to rename the theme, or swap it out for another starter, the following paths may need to be edited, or you can bail on our front-end build processes if you want - I'm not your supervisor 💁

package.json

• assetSource
• assetDest
• themeFolder

wp-config.php

• WP_DEFAULT_THEME

composer.json

• autoload config

Homestead and WP CLI

If you have homestead installed globally then you can take advantage of WP CLI's aliases in a very easy manner

Run the following command to generate a SSH config

homestead ssh-config --host homestead.dev >> ~/.ssh/config

If you have changed your Homestead install's folders property in Homestead.yaml, then please edit the @dev alias in wp-cli.yml to relect the correct path

If you have yet to install WP CLI on homestead then this will take care of it..

# One liner for global Homestead users, I gotchu fam.
homestead ssh -- -t 'curl -o wp https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar && chmod +x wp && sudo mv wp /usr/local/bin/wp'

Then you can execute WP CLI commands from your machine using the aliases

# Good test example
wp @dev plugin list

Using Typescript

If using TypeScript, rename app.js to app.ts. The TypeScript compiler (tsc) will then handle the file and then pipe through the standard js pipeline (Babel, Uglify etc).

To take advantage of TypeScript autocomplete + checking with various libraries, install the corresponding TypeScript type definition file by running one of the following:

npm install -D @types/jquery npm install -D @types/lodash npm install -D @types/underscore

Many type definitions are available. See them all at https://github.com/DefinitelyTyped/DefinitelyTyped .