Gulp build for wordpress theme development

Opinionated build using convention over configuration. Provides pipelines for styles (scss to css) and javascript (typescript to es5) and hot reloading. Expects a specific source directory layout and provides common tasks:

• gulp wp-build
  • Create distributable theme in public folder
  • Process scss files to css
  • Process typescript files to plain js
  • Set theme version in style.css to current git hash
• gulp wp-build:watch for development
  • Execute wp-build in watch mode for live development
  • Set up browsersync for hot reloading
  • Back copy acf-json from public to src when edited in browser
• gulp wp-release
  • Prompt for semver bump (major|minor|patch)
  • Bump version in package.json
  • Create and push git tag release/

Installation

Add dependencies

Create a npm/yarn project and add the following dev dependencies:

• @mepheser/wordpress-gulp
• gulp
• typescript

Add wordpress gulp tasks to local gulp file

Create a simple gulpfile.js and add wordpress tasks by passing gulp object to init function:

var gulp = require('gulp');
var wordpressGulp = require('@mepheser/wordpress-gulp')

wordpressGulp(gulp)

After that, wp-build, wp-build:watch and wp-release are available in local build.

Directory layout and processing

All different source file types are located in subdirectories of src and are compiled/copied to public. A simple theme output folder may look like

Example

Input: separated by file type to be processed differently

src/
├── fonts
│   ├── roboto.woff
├── images
│   ├── logo.jpg
├── php
│   ├── acf-json
│   │   ├── group_5bc065b43c546.json
│   ├── templates
│   │   ├── even-more-template-files.php
│   ├── 404.php
│   ├── functions.php
│   ├── index.php
│   └── style.css
├── scripts
│   └── some-internal-component.ts
│   └── main.ts
└── styles
    ├── _colors.scss
    ├── _more-internal-partials.scss    
    └── main.scss

Output: a wordpress ready theme directory

public/
├── acf-json
│   ├── group_5bc065b43c546.json
├── assets
│   ├── fonts
│   │   ├── roboto.woff
│   ├── images
│   │   ├── logo.jpg
│   ├── scripts
│   │   └── bundle.js
│   └── styles
│       └── main.css
├── templates
│   ├── even-more-template-files.php
├── 404.php
├── functions.php
├── index.php
└── style.css

Details by file type

Stylesheets (css and scss)

• source: src/styles/main.scss and referenced files
• target: public/assets/styles/main.css
• processing
  • create main entry point src/styles/main.scss
  • split code into partials
  • include scss or css from node_modules using ~ notation (note: don't use .css suffix as this would create an url() reference)
  • processed scss will be copied to public/assets/styles/main.scss

Scripts (typescript)

• source: src/scripts/main.ts and referenced files
• target: public/assets/styles/bundle.js
• processing
  • create main entry point src/styles/main.ts
  • declare dependencies in package.json, split code into separate .ts files and import in main.ts
  • procecessed bundled.js (including all dependencies) will be copied to public/assets/scripts/bundle.js

php (wordpress theme files)

• source: src/php/* (style.css, functions.php, index.php, other templates,...)
• target: public/*
• processing
  • all theme files and directories are copied directly into public
  • style.css get's current git hash into Version: %git_hash%

Images

• source: src/images/*
• target: public/assets/images/*
• no processing

Fonts

• source: src/fonts/*

• target: public/assets/fonts/*

• no processing