Eightshift WordPress Boilerplate

This repository contains all the tools you need to start building a modern WordPress theme, using all the latest front end development tools.

Eightshift WordPress Boilerplate is maintained and sponsored by Eightshift and Infinum.

📚 Table of contents

🎒 Requirements
🚀 Quick start
🎓 How to develop using WP Boilerplate
🚨 Liniting Files
🏭 Going to Production
🚚 Import & Export
⁉️ Plugin
📫 Who do I talk to?
📜 License

🎒 Requirements

🚀 Quick start

Let's create a new theme!

Navigate to your WordPress install's wp-content/themes folder and run the following command:

npx create-wp-theme

Script will prompt you for theme name and local development url (used for BrowserSync) and install a new theme:

After the script is finished, you can activate the theme through WP Admin Dashboard.

To start developing navigate to your theme's folder (cd theme_name) and run:

npm start

🎓 How to develop using WP Boilerplate

Automatic building of assets

This will build production ready assets (in watch/development mode using Webpack) after each modification to your files in skin/assets (compile SCSS to CSS, transpile JS, add hashes to files for cache busting purposes, etc):

Generally speaking, you should have this script active all the time while you're developing.
```
npm start
```
You need to run this in your theme's folder.
BrowserSync

You have BrowserSync to sync assets and enable easy cross-device testing. Once BrowserSync is active you will get url in the terminal. Usualy it is localhost:3000.

What is BrowserSync?
IMPORTANT - Adding new .php classes (or renaming exsiting ones)

This theme uses OOP with namespaces and autoloader. When you add new class in your theme, be sure to run this command to rebuild the composer's autoload class map. The reason why this isn't automatic is that we are folowing modified WordPress coding standards, and not PSR standards, so this has to be done manually.

In short, run this after adding a new class:
```
composer -o dump-autoload
```

🚨 Liniting Files

Automatic

You can have editors lint your files as you type, here's how to set it up:

Visual Studio Code

Manual

Linting assets - JS and SASS using Webpack:
```
npm run lint
```
Linting PHP - We are using Infinum coding standards for WordPress to check php files. To install it, you need to install Composer from initial setup step.

Here are available scripts to run in your terminal to lint your PHP files (you need to run them from inside the theme's folder):

Checking theme for possible violations:
```
composer check-cs .
```
Autofix theme for minor violations:
```
composer fix-cs .
```

🏭 Going to Production

You can do it manualy using the command from package.json but we prefere using continious integration and we have 2 scripts to help you.

Run build script to build production version of assets and composer, run linting and tests:
```
bash bin/build.sh
```
Run build script to build production version of assets and composer. Builds production ready assets
```
bash bin/deploy.sh
```
For deployment, we are using rsync and semaphoreci in our continuous deployment setup. Whatever deployment system you are using you should never copy unnecessary data to the server. We added file ci-exclude.txt to exclude unnecessary folders and files on deployment.

🚚 Import & Export

Export

You can run this script from your theme folder which will give you a .zip of your theme you can add to any project.
```
npm run export
```
Import

After importing the theme to a different website (through WordPress admin dashboard), you need to run this script (from the theme's folder) before activating it.
```
npm run setup
```

⁉️ Plugin

When working for a client it may be easier to add every additional functionality to the theme. Since you are using namespaces, this contains all the necessary logic in the theme. You can use plugins of course, but be careful how you are adding extra functionality, so that you don't run in the dependency hell. If you need to expose certain functionality across the multisite we recommend that you create a plugin.

Plugins should be created using plugin boilerplate, with addition of namespaces and autoloader. We have that also prepared so please check our Plugin Boilerplate.

📫 Who do I talk to?

For questions talk to: