npm package: @mepheser/wordpress-gulp
Description: Gulp build for sane wordpress theme development 
Latest version: 1.2.0

# 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/<version>   
  
## 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:
```javascript
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](https://sass-lang.com/guide#topic-4)
    * 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