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
- Create distributable theme in
-
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
- Execute
-
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
- create main entry point
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
- create main entry point
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%
- all theme files and directories are copied directly into
Images
- source:
src/images/*
- target:
public/assets/images/*
- no processing
Fonts
- source:
src/fonts/*
- target:
public/assets/fonts/*
- no processing