WordPressify v0.1.6

A build system designed to automate your WordPress development workflow.

http://www.wordpressify.co/

• Introduction
  • Features
• 1. Installing Node
• 2. Set Up Project
• 3. CSS, PostCSS and Sass
  • PostCSS
  • Sass
• 4. Images and Fonts
  • Images
  • Fonts
• 5. JavaScript ES6
  • Write ES6 JavaScript
• 6. External Libraries
• 7. Build Backups
• 8. Code Style Rules
  • Lint CSS
• 9. Database
  • MySQL/MariaDB Server
  • Remote Database
• 10. Deployment
  • Automated Deployments
• 11. Cleanup Default Theme
• 12. Windows Installation
• Changelog
• License

Introduction

WordPressify is a modern workflow for your WordPress development, with an integrated web server and auto-reload. CSS preprocessors and ES6 ready.

Features

• DEV SERVER A development server for PHP based in Node. Powered by BrowserSync.
• AUTO-RELOAD Watches for all your changes and reloads in real-time.
• CSS Preprocessors: PostCSS or Sass with source maps.
• JAVASCRIPT ES6 Babel compiler for writing next generation JavaScript.
• EXTERNAL LIBRARIES Easy import for external JavaScript libraries and npm scripts.
• CUSTOMIZABLE Flexible build customization, managed by gulp tasks.

1. Installing Node

WordPressify requires Node v7.5+. This is the only global dependency. You can download Node here.

Node.js is a JavaScript runtime built on Chrome’s V8 JavaScript engine. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient. Node.js’ package ecosystem, npm, is the largest ecosystem of open source libraries in the world.

2. Set Up Project

File Structure

├── build/                   # Build files
├── dist/                    # Distribution files
├── src/                     # Source files
│   ├── assets/              # Assets directory
│       ├── fonts/           # Fonts directory
│       ├── img/             # Image directory
│       ├── js/              # JavaScript files
│       ├── styles/          # CSS files
│   ├── plugins/             # WordPress plugins
│   ├── theme/               # PHP Template files
├── tools/                   # Tools and utilities
│   ├── stylelintrc.json     # Stylelint configuration file
│   ├── IntelliJ.xml         # IntelliJ code style
└── .babelrc                 # Babel configuration
└── .gitignore               # Git ignored files
└── LICENSE                  # License agreements
└── README.md                # You are reading this
└── gulpfile.js              # Gulp configuration
└── package.json             # Node packages

To install WordPressify you need to clone the repository from GitHub:

git clone https://github.com/luangjokaj/wordpressify

• This will clone the repository on your local machine. Navigate to the newly created folder and install the dependencies:

INSTALL DEPENDENCIES

npm install

CHANGE TEMPLATE NAME

• At this point WordPressify is installed and ready to be used for the first time. Before starting, open gulpfile.js and edit your template name:

/* -------------------------------------------------------------------------------------------------
Theme Name
 ------------------------------------------------------------------------------------------------- */
const themeName = 'wordpressify';
//--------------------------------------------------------------------------------------------------

INSTALL WORDPRESS

• On the first run we need to install WordPress, we do this once by running the command:

npm run install:wordpress

• It will fetch the latest WordPress version, which is the build we use for the development server.

START WORKFLOW

• We are ready to start our development server with the command:

npm run dev

• If you are running a fresh instance of WordPress, the installation wizard will set up a wp-config.php file containing database credentials, site name etc.
• You are ready to go! Happy coding!

WORDPRESS PLUGINS

• If you want to add or build WordPress plugins, you can do that from the directory:

src/plugins/

PRODUCTION TEMPLATE

• To generate your distribution files run the command:

npm run prod

• The template will be saved as a zip file in:

dist/wordpressify.zip

WINDOWS USERS

• If you are running Windows, PHP has to be installed and configured. Check the gulp-connect-php documentation.

We prepared a video screencast demonstrating the installation processs using a Windows operating system, you can find it here: How to install WordPressify on Windows? Or check out this tutorial on Medium.

3. CSS, PostCSS and Sass

PostCSS

By default WordPressify supports PostCSS, a similar preprocessor to Sass, Less and others but with more functionality. On top of that PostCSS is 3x faster than Sass and 4x faster than Less. Features come in the shape of PostCSS plugins. Think of these like using Lego, where each piece is a different feature that can transform your CSS in some way. PostCSS lets you stick these pieces together so that you can build up your own feature set, adding and removing plugins as and when you need them. postcss-preset-env is installed by default. Read more about PostCSS here.

POSTCSS PLUGINS

WordPressify has two different sets of PostCSS plugins - one for the development environment (pluginsListDev) and one for the production task (pluginsListProd).

//--------------------------------------------------------------------------------------------------
/* -------------------------------------------------------------------------------------------------
PostCSS Plugins
 ------------------------------------------------------------------------------------------------- */
const pluginsListDev = [
	partialimport,
	postCSSMixins,
	postcssPresetEnv({
		stage: 0,
		features: {
			'nesting-rules': true,
			'color-mod-function': true,
			'custom-media': true,
		},
	}),
];

const pluginsListProd = [
	partialimport,
	postCSSMixins,
	postcssPresetEnv({
		stage: 0,
		features: {
			'nesting-rules': true,
			'color-mod-function': true,
			'custom-media': true,
		},
	}),
	require('cssnano')({
		preset: ['default', {
			discardComments: false,
		}]
	}),
];
//--------------------------------------------------------------------------------------------------

WRITING CSS

The starting point for CSS is the file:

src/assets/styles/styles.css

The template definitions are located here too. It is also where all other imports are included in the stylesheets.

/*
Theme Name: WordPressify
Theme URI: https://www.wordpressify.co
Author: Luan Gjokaj
Author URI: https://www.riangle.com
Description: WordPressify official theme.
Version: 1.0
Tags: responsive, clean, minimal, modern, documentation
*/

Sass

WordPressify is super flexible. You can install Sass and use it as the main CSS preprocessor:

npm install gulp-sass --save-dev

Include Sass in gulpfile.js:

const sass = require('gulp-sass');

Change the gulp tasks stylesDev to:

function stylesDev() {
	return src('./src/assets/styles/style.scss')
		.pipe(sourcemaps.init())
		.pipe(sass().on("error", sass.logError))
		.pipe(sourcemaps.write('.'))
		.pipe(dest('./build/wordpress/wp-content/themes/' + themeName))
		.pipe(browserSync.stream({ match: '**/*.css' }));
}

Also the watch task has to be changed in order to watch for .scss filetypes:

watch('./src/assets/styles/**/*.scss', stylesDev);

Change the gulp tasks styleProd to:

function stylesProd() {
	return src('./src/assets/styles/style.scss')
		.pipe(sass().on("error", sass.logError))
		.pipe(dest('./dist/themes/' + themeName));
}

4. Images and Fonts

Images

It is recommended to store template image assets in your theme directory:

src/assets/img/

Ideally other images should be managed through the Media Library of WordPress. Try to only store SVG or minimal assets in your theme directory to keep the template as light as possible.

In the production build SVGs and other image assets will go through a minification process.

Fonts

Fonts are always special. Your fonts should be stored in:

src/assets/fonts/

Then you can include them in your CSS:

@font-face {
	font-family: 'Helvetica Neue Thin';
	src: url('./fonts/Helvetica-Neue-Thin.eot?#iefix');
	src: url('./fonts/Helvetica-Neue-Thin.eot?#iefix') format('eot'),
	url('./fonts/Helvetica-Neue-Thin.woff2') format('woff2'),
	url('./fonts/Helvetica-Neue-Thin.woff') format('woff'),
	url('./fonts/Helvetica-Neue-Thin.ttf') format('truetype'),
	url('./fonts/Helvetica-Neue-Thin.svg#e3b7d1e7c160') format('svg');
}

5. JavaScript ES6

WordPressify supports ES6 JavaScript with Babel. Babel has support for the latest version of JavaScript through syntax transformers. These plugins allow you to use new syntax, right now without waiting for browser support.

Write ES6 JavaScript

Your JavaScript code should be located in:

src/assets/js/

WordPressify will watch for changes under the js directory and bundle the code in a single file, which will be included in the footer of the page as:

footer-bundle.js

Check the gulp configuration to learn more about how JavaScript is generated.

6. External Libraries

Including external JavaScript libraries is as simple as installing the npm script and including it in the gulpfile.js

/* -------------------------------------------------------------------------------------------------
Header & Footer JavaScript Boundles
-------------------------------------------------------------------------------------------------- */
const headerJS = [
	'./node_modules/jquery/dist/jquery.js',
	'./node_modules/nprogress/nprogress.js',
	'./node_modules/aos/dist/aos.js',
	'./node_modules/isotope-layout/dist/isotope.pkgd.js'
];
const footerJS = [
	'./src/assets/js/**'
];
//--------------------------------------------------------------------------------------------------

You can include the scripts in the head of the page before the DOM is loaded by placing them in the headerJS array or in the footer of the page after the DOM is loaded in the footerJS array. Only footer scripts are processed with Babel thus supporting ES6, however you can change this in the configuration if you want to run both header and footer scripts with Babel.

A build restart is required for changes to take effect.

7. Build Backups

While coding you will find yourself uploading dummy content to the WordPress build server, e.g. images or other media stored in wp-content. WordPressify allows you to back up the current state of the build which will include all server files. To back up your build run the command:

npm run backup

Files will be compressed in a zip file and stored in the directory:

backups/

8. Code Style Rules

WordPressify comes with its own set of code style rules that can be imported into IntelliJ. The code style file can be found in the directory:

tools/IntelliJ.xml

Lint CSS

Before pushing changes make sure you have clean and consistent CSS. Run stylelint with the command:

npm run lint:css

9. Database

MySQL/MariaDB Server

After installing WordPressify you will still need a database to store WordPress content. The recommended solution is to install either MySQL (installation instructions) or MariaDB (installation instructions) on your local machine.

Remote Database

You are free to use remote databases. Please note that this will affect the speed depending on the connection.

10. Deployment

The recommended solution is to go with WP Pusher. It is easy and quick to deploy automatically from GitHub or other services. The first step is to download the WordPress plugin from: https://wppusher.com/

Then navigate to your WordPress administration on your live site and install the downloaded plugin: Plugins -> Add New -> Upload Plugin -> Install Now.

Activate the plugin and navigate to the plugin page WP Pusher. Click on the GitHub or any other tab and obtain a token by pressing the button on the page, then copy and save the token.

At this point go to your terminal, navigate to your WordPressify project and generate your distribution files with the command:

npm run prod

Navigate to your theme distribution files on:

dist/theme/<themeName>

Create a git repository and push all the files on GitHub. This repository will have only the theme distribution files.

Once the files are on GitHub you can get back to the WordPress administration on the WP Pusher plugin page and follow the Next Steps, click on Install a theme.

On Repository host we choose GitHub, then click on Pick from GitHub and choose the newly created repository with the distribution files. Then install & activate the theme.

Automated Deployments

Push-to-Deploy if you want automatic deployments to happen when you do a push to the distribution repository. In this case you have to create a Webhook from your GitHub's repository page.

First navigate to the WP Pusher plugin page and click on Themes, it will show you the list of the templates you have installed through the plugin itself. Click on Show Push-to-Deploy URL to get the Payload URL.

Now get back to GitHub and navigate to your distribution repository and click on: Settings -> Webhooks -> Add webhook. Now past the URL and click Add webhook.

This should enable automatic deployment on any push to the chosen GitHub repository.

Note: WP Pusher if free only with public repositories.

11. Cleanup Default Theme

The default theme comes as a theme sample to show how WordPressify combines everything together. If you want to remove the default theme type the command:

npm run fresh-start

This will immediately remove the default styles and leave a minimal viable theme with basic PHP WordPress loops and other useful features.

12. Windows Installation

How to install WordPressify on Windows?

Assuming that you are using the latest version of Windows, and you have activated Windows Subsystem for Linux. Follow the instructions:

Install lamp for PHP and MySQL

First refresh your package index:

sudo apt-get update

Then install the LAMP stack:

sudo apt-get install lamp-server^

For more informations check out: https://help.ubuntu.com/community/ApacheMySQLPHP

Start MySQL

sudo service mysql start

Now let's connect to the MySQL Server:

sudo mysql

Change the root password to "123456789":

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '123456789';

Reload privileges:

FLUSH PRIVILEGES;

Install Node

curl -sL https://deb.nodesource.com/setup_11.x | sudo -E bash -

sudo apt-get install -y nodejs

That's it. Now just follow the WordPressify installation instructions.

Changelog

v0.1.6

• Upgrade to Gulp 4.
• Rewrote all tasks into functions.
• Updated file structure.

v0.1.5

• Upgrade to Babel 7
• Removed deprecated postcss-cssnext in favor of postcss-preset-env.

v0.1.4

• Added cleanup command to flush the default theme and have a fresh start.

v0.1.3

• Added support for bitmap and SVG minification, in the production build.
• Added documentation for deployment process.

v0.1.2

• Converted all variables from 'var' to 'const'.
• Replaced long anonymous function with ES6 arrow syntax.
• Fixed spelling errors.

v0.1.1

• Added support for src/plugins.

v0.1.0

• Code readability.
• Removed unused packages.
• Build success and error messages.
• Tasks cleanup.

v0.0.9

• Update documentation.

v0.0.8

• Name change.

v0.0.7

• Fix placemente of DISABLE_WP_CRON.

v0.0.6

• Theme cleanup.
• Consistent code styles.

v0.0.5

• Activated DISABLE_WP_CRON to prevent Node freezing.
• Back up your build files with all wp-content uploads.

v0.0.4

• Whitelabel template.
• Renamed classes.
• Refactored CSS structure.
• Meet WordPressify.

v.0.0.3

• Simplified build logic.
• Install WordPress only once with npm run install:wordpress.
• Cleaner distribution task.

v0.0.2

• Bugfixes.
• Watch and store new content in wp-content/uploads.

License

MIT