Best WordPress Theme Development Workflow

Best WordPress Theme Development Workflow

 

So everyone is clear, this is MY best WordPress theme development workflow. This is not the be all, end all of WordPress workflows and you may absolutely hate it. That’s fine. I would encourage you to do whatever you are most comfortable with. If you want to write how much you hate it in the comments, that’s fine too. Just be prepared for a witty reply.

But, in all honesty, you wouldn’t be reading this if you weren’t trying to improve some part of your theme development process. So, even if you only grab one thing to incorporate into your existing development workflow, then you have taken a step forward in improving your efficiency as a developer.

Personally, I do all my development on a Mac, so this is geared more towards Mac users, but there are workarounds for Windows users available if you want to get frisky.

Also, this involves a fair amount of using the terminal/command line, which I highly suggest you get familiar with if you aren’t already.

Tools/Software/Knowledge Needed for this Include:

  • FoundationPress or Understrap (Depends on your preference of Foundation or Bootstrap)
  • Knowledge of Terminal
  • Gulp
  • Bower
  • Node.js & NPM
  • NVM (Mac only) – Windows alternative would be nvm-windows
  • Mac users – Homebrew (Not completely necessary but HIGHLY suggested because Homebrew rocks)
  • MAMP (Mamp Pro not necessary)
  • Wget
  • Sublime Text
  • GCC
  • Basic understanding of Sass
  • A somewhat optimistic outlook on life and the ability to not get pissed off when you get errors

 

Step 1

First and foremost, you need to get a few things downloaded onto your machine.

  • Homebrew – (Mac only)
  • Node.js and NPM – Windows people got to the website to download. Mac people go to the terminal and type brew install node
  • NVM – (Mac only). Windows people you can try nvm-windows which I linked to above.
  • Download both FoundationPress and Understrap and unzip them
  • Wget – allows you to download the latest WordPress install from the command line
  • MAMP – Sets up a local server for you to develop on (You should always be developing locally)

 

Homebrew:

To install Homebrew type:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Node.js

You must install Node before doing the rest of these installations below.
brew install node

Windows: go to Nodejs.org and download/install it.

NVM:

To install NVM on your Mac simply type:
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.8/install.sh | bash

The next script will clone the nvm repository to ~/.nvm and adds the source line to your profile (~/.bash_profile~/.zshrc~/.profile, or ~/.bashrc):

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

This allows you to use the nvm keyword in the terminal to issue commands, such as to switch your node version, like nvm download 4.8.4 which will automatically download version 4.8.4.

Gulp:

Install gulp real quick with: npm install --global gulp-cli

The global flag makes gulp available in all project files.

Wget:

brew install wget

Windows: http://www.gnu.org/software/wget/

MAMP:

MAMP has both a Windows and Mac version. No need to pay for the pro version to do any of this. Just download it and get it installed. You can also go ahead and open it as we will be using it in a few minutes.

Sublime Text 3:

There’s a good chance you already have this installed, but if not, you can get it here. In addition to installing Sublime Text 3, we also need to add it to your path so you can quickly open up a project from the terminal in Sublime Text. In your terminal, type the following and press enter: ln -s /Applications/Sublime\ Text.app/Contents/SharedSupport/bin/subl /usr/local/bin/subl This allows you to type subl . in the root of a folder and open the entire folder in Sublime Text automagically.

 GCC:

If you have Xcode command line tools already installed on Mac, then you are good to go. If not then either install those as shown here, or you can use Homebrew

brew install gcc

Windows users can check out http://www.mingw.org/

Step 2

Create two blank text files in textEdit or Notepad or whatever called new-foundation.txt and new-understrap.txt You need to paste in this automation script I wrote.

 

new-foundation.txt

#!/bin/bash

#
# Setup WP install with base theme into provided folder
# Expects 1 parameter: client folder name
#

echo "==================================================="
echo " Initializing Directory and downloading WordPress"
echo "==================================================="


mkdir ~/projects/$1
cd ~/projects/$1
wget http://wordpress.org/latest.tar.gz --no-check-certificate
tar xfz latest.tar.gz
mv wordpress/* ./
sleep 1
rmdir ./wordpress/
rm -f latest.tar.gz

echo " "
echo "==================================================="
echo " Configuring wp-config.php"
echo "==================================================="
echo " "

sleep 2

mv wp-config-sample.php wp-config.php
sed -i.bak s/database_name_here/$1/g ~/projects/$1/wp-config.php
sed -i.bak s/username_here/root/g ~/projects/$1/wp-config.php
sed -i.bak s/password_here/root/g ~/projects/$1/wp-config.php

echo " "
echo "==================================================="
echo " Creating theme folder with FoundationPress"
echo "==================================================="
echo " "

sleep 2

mkdir ~/projects/$1/wp-content/themes/$1
cp -R ~/foundationpress-starter-theme-master/* ~/projects/$1/wp-content/themes/$1

echo "==================================================="
echo " Project $1 created!"
echo "==================================================="
echo " "

sleep 2

echo "==================================================="
echo " Step 1: Create database named $1 in PHPMyAdmin\n Step 2: Browse to http://localhost:8888 to complete setup"
echo "==================================================="
echo " "

sleep 2

echo "==================================================="
echo " Preparing to install node modules"
echo "==================================================="
echo " "

sleep 2

cd ~/projects/$1/wp-content/themes/$1
npm install
subl .

 

So, maybe you are asking what the hell is all this? Well, it is a shell script that creates a project folder for you, installs WordPress in it, configures your wp-config file, creates theme folder and installs FoundationPress and node modules, then opens sublime. Takes 1 parameter of client name or whatever you want your theme folder to be called.

I also have one here for Understrap if you prefer Bootstrap over Foundation. That’s a whole different topic altogether, but having used both extensively, I like Foundation better.

Here is the code you should paste into new-understrap.txt. It is very similar to the foundation script:

#!/bin/bash

#
# Setup WP install with base theme into provided folder
# Expects 1 parameter: client folder name
#

echo "==================================================="
echo " Initializing Directory and downloading WordPress"
echo "==================================================="

mkdir ~/projects/$1
cd ~/projects/$1
wget http://wordpress.org/latest.tar.gz --no-check-certificate
tar xfz latest.tar.gz
mv wordpress/* ./
sleep 1
rmdir ./wordpress/
rm -f latest.tar.gz

echo " "
echo "==================================================="
echo " Configuring wp-config.php"
echo "==================================================="
echo " "

sleep 2

mv wp-config-sample.php wp-config.php
sed -i.bak s/database_name_here/$1/g ~/projects/$1/wp-config.php
sed -i.bak s/username_here/root/g ~/projects/$1/wp-config.php
sed -i.bak s/password_here/root/g ~/projects/$1/wp-config.php

echo " "
echo "==================================================="
echo " Creating theme folder with Understrap"
echo "==================================================="
echo " "

sleep 2

mkdir ~/projects/$1/wp-content/themes/$1
cp -R ~/understrap-0.3.8/* ~/projects/$1/wp-content/themes/$1

echo "==================================================="
echo " Project $1 ready!"
echo "==================================================="
echo " "

sleep 2

echo "==================================================="
echo " Step1: Create database named $1 in PHPMyAdmin\n Step 2: Browse to http://localhost:8888 to complete setup"
echo "==================================================="
echo " "

sleep 2

echo "==================================================="
echo " Preparing to install node modules"
echo "==================================================="
echo " "

sleep 2

cd ~/projects/$1/wp-content/themes/$1
npm install
subl .

Step 4

Now before we run these scripts, we need to move a couple folders to a different spot and do a bit more prep work. These scripts are set to run on the root and expect the other files to be on the root as well. You are welcome to modify the paths in these shell scripts if you want it somewhere else. But, for the sake of this tutorial, we are doing it my way.

By root, I mean this folder as shown here on my Mac Finder. I am putting in the nbeers directory, which is located at ~/. If you simply right-click on the top of the finder window where it shows your folder, it will bring up these folders so you can easily navigate to it.

 

 

Step 5

Next, we need to go down to a lower version of Node. FoundationPress is not set up to work with the latest and greatest version of Node.js, which really is no big deal when you have NVM. When you installed Node.js, it installed the most recent stable version, which is version 8.9.1 at the time of this writing. Assuming you installed NVM earlier, we can use that to install a lower version very quickly.

In your terminal type nvm install 4.8.4

After it is installed type nvm use 4.8.4

Step 6

Now, we should be ready to run the script and watch the magic happen inside your terminal, assuming I didn’t screw this up and forget a step. If you are getting errors after running the script, I urge you to Google them and/or write them in the comments and I will be happy to try to help or add something that I possibly left out of this tutorial. It is very possible you have different system configurations that are causing an error with Gulp or Bower

To run the script for a FoundationPress project, go back to your terminal and type: sh ~/new-foundation.txt client_name

To run the script for a Understrap project, go back to your terminal and type: sh ~/new-understrap.txt client_name

client_name is whatever you want the project folder/theme folder to be called. I am typically developing for clients, so I always use their name as the folder name to differentiate between them.

At this point, your terminal should be running like crazy, showing you several messages and installing a ton of node modules. The node module installation of this may take up to 3 minutes.

Step 7

While that is running, go ahead and open up MAMP if you didn’t earlier. MAMP should look something like this:

 

mamp

 

Click on Preferences and then click Web Server on the tabs. Click the little folder icon with the three dots and find the project folder that was just created by the script. It should be in ~/projects/client_name.  Select the folder and then hit OK. Now click Start Servers (you may have to enter your password here) and then click Open WebStart Page.

It should bring you to a page looking like this:

 

ideal wordpress development workflow

 

Step 8

Next, click the phpMyAdmin link that you see on the left side in this image. Then click the Databases tab on the next screen.

 

wordpress set up phpmyadmin

 

Enter the exact client name you put before as the database name, leave the dropdown as Collation and click Create.

Next, remove /MAMP/index.php?page=phpmyadmin&language=English from your current url leaving only localhost:8888 and press enter. This should bring you to the WordPress installation screen where you can create your user and install WordPress.

Hopefully, your terminal is done running and Sublime Text has opened up your project. If it hasn’t finished running just give it a second and it will be done.

Step 9A – If you installed FoundationPress…

Now, it is time to take a quick look at the file structure of FoundationPress

 

foundationpress file structure

 

I have personally removed a few folders and files that I know I don’t need for a typical WordPress theme. If you expand the assets folder, you will see the areas where you can write your Sass and JavaScript. Note: jQuery is also readily available here. No need to include it anywhere.

If you decide to create your own Sass partials somewhere in the components folder or anywhere else in the Sass directory, make sure to @import them into foundation.scss, like so:

 

Sass import foundation

 

In that same foundation.scss file, you can switch from using the Foundation float grid or flex grid, on lines 56 and 57.

Simply comment one out and leave the other uncommented:

 

 

You can also remove several parts of Foundation’s functionality by simply uncommenting various lines and have your own customized foundation install.

For the gulpfile.js file, you will want to fill in the url variable on Line 17. This will allow you to use BrowserSync. What BrowserSync does is refresh the browser anytime you save one of your files so you don’t have to manually do it to see your code update on the page. This is not 100% necessary, but just another option to knock off a few seconds here and there, which can add up over an entire day’s work.

I encourage you to check out the FoundationPress GitHub page for every possible option and configuration. I am merely laying out the way I use it, but there are even more options that I have not listed here.

Once you are ready to begin developing, you can type npm run watch in your terminal. If BrowserSync is working properly, it should open up a browser tab at localhost:3000. Basically, it is redirecting your localhost:8888 to localhost:3000 and that is the tab that will auto-refresh.

If you want to package everything up as a theme and maybe upload via FTP to a dev server or live server, you can type gulp package or gulp package --production. The production flag will make sure everything is minified for you. Then go in and remove the packaged folder if it is there and remove the bower_components folder before uploading, or it will take forever to upload. You will see a node_modules folder also, but it should be empty.

Step 9B – If you installed Understrap…

A quick look at the file structure of Understrap:

 

understrap file structure

 

If you want to write extra Sass, of course, do it in the Sass folder and write @import statements in /sass/theme/_theme.scss to include them. You could create a folder called partials so /sass/partials and then within /sass/theme/_theme.scss, you would just include it with an @import statement.

If you want BrowserSync to auto-refresh your browser every time you save, then go to gulpfile.js and look for this:


var browserSyncOptions = {
  proxy: "localhost/theme_test", // <----- CHANGE HERE to localhost:8888
  notify: false
};

Then you can run gulp watch-bs and begin coding.

I encourage you to check out the Understrap GitHub page for every possible option. There are even more tips and tricks to use Understrap there that I have not listed here.

At this point, you are pretty much ready to begin coding your theme. Everything within FoundationPress/Understrap is set up as a WordPress theme should be. There may be some extra fluff that you don’t need, which you are more than welcome to delete. The more you streamline it for yourself, the better.

Conclusion

If I had to choose one of these that I liked better, it would be FoundationPress. They both absolutely get the job done, but I like the way FoundationPress’s Sass file structure is setup and the whole setup in general. I learned development using Bootstrap four years ago and used it ever since, but after using Foundation for about 6 months now, I definitely prefer it over Bootstrap in general. With the Zurb team behind Foundation, development progress is achieved much faster than with the Bootstrap team and they seem to be pushing the limits more.

Also, as I said before, if you have anything you think is worth adding here, I invite you to leave it in the comments or in an email.