Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/craigsimps/gulp-wp-toolkit
Re-usable Gulp Toolkit for WordPress Themes
https://github.com/craigsimps/gulp-wp-toolkit
gulp toolkit wordpress-development
Last synced: 3 months ago
JSON representation
Re-usable Gulp Toolkit for WordPress Themes
- Host: GitHub
- URL: https://github.com/craigsimps/gulp-wp-toolkit
- Owner: craigsimps
- License: mit
- Created: 2016-10-14T11:45:34.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2020-05-19T13:49:20.000Z (over 4 years ago)
- Last Synced: 2024-09-26T14:40:52.190Z (4 months ago)
- Topics: gulp, toolkit, wordpress-development
- Language: JavaScript
- Homepage:
- Size: 422 KB
- Stars: 88
- Watchers: 8
- Forks: 10
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Gulp WP Toolkit
[](https://travis-ci.org/craigsimps/gulp-wp-toolkit) [](https://greenkeeper.io/)
Re-usable Gulp Toolkit for WordPress Themes.
This is a Gulp package which holds all of the tasks, configuration and lint files I use when building WordPress themes. Rather than holding all of these tasks in one giant `Gulpfile.js` within each theme I build, this is a standalone package and can be pulled in independently.
A more lightweight version of this toolkit is also available for use in WordPress plugins, called [Gulp WP Plugin Toolkit](https://github.com/craigsimps/gulp-wp-plugin-toolkit/).
## Installation
Using the package is simple - within your custom theme create a `package.json` which has `gulp` and `gulp-wp-toolkit` as dependencies.
Make sure to update the other parts of your `package.json` too, as these will be pulled in to form the theme stylesheet header
Add a `package.json` to your theme like so:
```
{
"name": "craigsimpson",
"homepage": "https://craigsimpson.scot/",
"version": "1.0.0",
"author": "Craig Simpson ",
"description": "Custom WordPress theme, based on the Genesis Framework.",
"repository": "",
"license": "GPL-2.0",
"main": "Gulpfile.js",
"devDependencies": {
"gulp": "^3.9.1",
"gulp-wp-toolkit": "^2"
}
}
```
Then create a simple `Gulpfile.js` in your theme root, like this:
```
'use strict';
var gulp = require('gulp'),
pkg = require('./package.json'),
toolkit = require('gulp-wp-toolkit');
toolkit.extendConfig({
theme: {
name: "WordPress Theme Name",
homepage: pkg.homepage,
description: pkg.description,
author: pkg.author,
version: pkg.version,
license: pkg.license,
textdomain: pkg.name
},
js: {
'theme' : [
'develop/vendor/a.js',
'develop/js/b.js'
],
'something-conditional' : [
'develop/js/standalone.js'
]
}
});
toolkit.extendTasks(gulp, { /* Task Overrides */ });
```
Once your `Gulpfile.js` is in place, install all the dependencies using `yarn install`. If you're not already using Yarn, please see the [installation instructions](https://yarnpkg.com/lang/en/docs/install/).
See the files in the example directory for more advanced configuration.
There are also a number of posts on my blog relating to setting up Gulp WP Toolkit, including:
* [Adding Gulp WP Toolkit to an existing Genesis theme.](https://craigsimpson.scot/adding-gulp-wp-toolkit-to-an-existing-genesis-theme)
* [Gulp WP Toolkit SCSS Configuration and Options](https://craigsimpson.scot/gulp-wp-toolkit-scss-configuration-and-options)
* [Gulp WP Toolkit JavaScript Configuration](https://craigsimpson.scot/gulp-wp-toolkit-javascript-configuration)
* [Bulk Import Your SCSS Partials using Gulp WP Toolkit](https://craigsimpson.scot/bulk-import-your-scss-partials-using-gulp-wp-toolkit)
* [An Overview of the Gulp WP Toolkit Build Tasks](https://craigsimpson.scot/an-overview-of-the-gulp-wp-toolkit-build-tasks)
## Tasks
Once installed, the following tasks will be available to run via `gulp `.
### Build
* `gulp build` runs the following tasks:
* `gulp build:css` compiles SCSS into CSS.
* `gulp build:js` concatenates JavaScript files defined in `config.js` and outputs into the theme `/js/` directory.
* `gulp build:images` optimizes all of the images stored in `/develop/images/` to `/images/`. If present, your `screenshot.png` (or other file extension) will be automatically output in the theme root.
* `gulp build:i18n` runs the following tasks:
* `gulp build:i18npotgen` generates a translations file at `/develop/languages/textdomain.pot`, where textdomain is the theme package name within `package.json`.
* `gulp build:potomo` converts and `.po` files within `/develop/languages/` into `.mo` files within `/languages/`.
* `gulp build:styleguide` (experimental) uses the SCSS files to generate a live style guide at `/develop/styleguide/` using Cortana (some setup required).
* `gulp build:rtl` (experimental) generates an RTL stylesheet in the theme root.
### Clean
Clean tasks are included so you can quickly remove any compiled assets, for example using `gulp clean:js` will delete the concatenated `.js` and `.min.js` we have built in `js/`. Tasks available are:
* `gulp clean` runs the following tasks:
* `gulp clean:css` will delete `.css` and `.css.map` files from the theme root.
* `gulp clean:js` will delete `.js` and `.min.js` files from the `/js/` output directory.
* `gulp clean:images` will delete all image files from the `/images/` output directory.
* `gulp clean:i18n` will delete the generated `.pot` file within `/develop/languages/`, and the generated `.mo` files within `/languages/`
### Lint
* `gulp lint` runs the following tasks:
* `gulp lint:php` runs the following tasks:
* `gulp lint:phpcs` check the code with PHP_CodeSniffer against the WordPress Coding Standards.
* `gulp lint:phpmd` check the code with PHP Mess Detector.
* `gulp lint:style` runs the following tasks:
* `gulp lint:scss` uses `stylelint` to check SCSS files against the WordPress Coding Standards.
* `gulp lint:css` uses `stylelint` to check CSS files against the WordPress Coding Standards.
* `gulp lint:colors` checks colour usage within SCSS files using `gulp-colorguard`.
* `gulp lint:js` runs the following tasks:
* `gulp lint:json` checks that any JSON files (for ACF, etc) are valid.
* `gulp lint:jsvalidate` runs JSValidate on project JS files..
* `gulp lint:eslint` runs ESLint on project JS files.
### Watch
The default `gulp watch` task is available and watches the theme (PHP, SCSS, JS, images) for any file changes. On change, the associated `build` task will be run.
### Serve
Running `gulp serve` will launch a new BrowserSync session, proxying the localhost URL which is defined in your theme's config under `server` -> `url` key. If the key is not defined, then BrowserSync won't start.
Our `gulp watch` task will also run, and your browser will live reload when any changes are detected.
BrowserSync can also run independently of `gulp watch` by running `gulp browser-sync`.
### Default
The default task (`gulp`) will run `gulp build` and `gulp serve`.
### Bump
Easily bump the version number of your `package.json` and `composer.json` files (defined in config) which will in turn bump the version of your theme. Uses [Semver](http://semver.org/).
* `gulp bump` updates the patch version. 1.0.0 to 1.0.1
* `gulp bump --patch` updates the patch version. 1.0.0 to 1.0.1
* `gulp bump --minor` updates the minor version. 1.0.0 to 1.1.0
* `gulp bump --major` updates the major version. 1.0.0 to 2.0.0
## Default Theme Structure
The default configuration has all of the source files in a `develop` directory, in their respective `scss`, `js`, `images`, and `languages` subdirectories. For new themes, it is recommended to follow this structure, but these paths can be overridden in the config if you prefer or need to work with a different structure.
A typical theme structure may look like:
```
.
├── develop/
│ ├── images/ (original images)
│ ├── js/ (JavaScript module files)
│ ├── languages/
│ ├── theme-name.pot (generated by Gulp WP Toolkit)
│ └── en_GB.po
│ └── scss/
│ ├── base/ (structure your SCSS how you want)
│ ├── variables/ (structure your SCSS how you want)
│ └── style.scss (reference your SCSS structure here)
├── images/ (generated by Gulp WP Toolkit)
├── js/ (generated by Gulp WP Toolkit)
├── languages/ (generated by Gulp WP Toolkit)
├── node_modules/ (generated by npm / yarn)
├── src/ (PHP classes)
├── templates/ (WP template files)
├── tests/
│ ├── Integration/
│ └── Unit/
├── vendor/ (generated by Composer)
└── views/
```
## Sass Bulk Import
Use of `gulp-sass-bulk-import` means that whole folders of Sass partials can be easily included with `@import 'foldername/*';`. Using this method, files are loaded in alphabetical order.
If files are required to be loaded in a specific order, you can declare these immediately before the wildcard import with the normal Sass syntax `@import 'folder/file'`.
## Bower
This toolkit no longer supports Bower. Better is to add your Bower dependencies into your themes' `package.json`, and then reference the correct file (from inside your `node_modules/`) in your `style.scss`, or the the `js` config as needed.
## Overrides
### Updating Config
All of the [existing configuration](config.js) can be easily overwritten by passing your new config object into the `toolkit.extendConfig()` function. An [example from a recent project](example/Gulpfile.js) shows how easy it is to update the array of JS files to be concatenated, and change the localhost URL to point to your project, for instance.
### Adding Tasks
Additional tasks can be added by passing an object to the `toolkit.extendTasks()` function, where the key is the name of the task. [Example](example/Gulpfile.js).
### Custom Lint Files
You can override any of the lint files contained within this repository by adding a file of the same name in your theme directory. For example, if your theme directory contains a `.eslintrc` file or `phpcs.xml.dist`, then it will be automatically used instead of the file included within `gulp-wp-toolkit`.
## Contributing to Gulp WP Toolkit
Please see [CONTRIBUTING](.github/CONTRIBUTING.md).