{"id":14954997,"url":"https://github.com/craigsimps/gulp-wp-toolkit","last_synced_at":"2025-10-24T07:30:38.503Z","repository":{"id":57259522,"uuid":"70905190","full_name":"craigsimps/gulp-wp-toolkit","owner":"craigsimps","description":"Re-usable Gulp Toolkit for WordPress Themes","archived":false,"fork":false,"pushed_at":"2020-05-19T13:49:20.000Z","size":432,"stargazers_count":88,"open_issues_count":24,"forks_count":10,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-01-29T08:21:51.688Z","etag":null,"topics":["gulp","toolkit","wordpress-development"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/craigsimps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-14T11:45:34.000Z","updated_at":"2023-10-28T19:47:37.000Z","dependencies_parsed_at":"2022-08-25T03:22:47.837Z","dependency_job_id":null,"html_url":"https://github.com/craigsimps/gulp-wp-toolkit","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/craigsimps%2Fgulp-wp-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/craigsimps%2Fgulp-wp-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/craigsimps%2Fgulp-wp-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/craigsimps%2Fgulp-wp-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/craigsimps","download_url":"https://codeload.github.com/craigsimps/gulp-wp-toolkit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237932057,"owners_count":19389560,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gulp","toolkit","wordpress-development"],"created_at":"2024-09-24T13:10:21.795Z","updated_at":"2025-10-24T07:30:38.169Z","avatar_url":"https://github.com/craigsimps.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gulp WP Toolkit\n\n[![Build Status](https://travis-ci.org/craigsimps/gulp-wp-toolkit.svg?branch=master)](https://travis-ci.org/craigsimps/gulp-wp-toolkit) [![Greenkeeper badge](https://badges.greenkeeper.io/craigsimps/gulp-wp-toolkit.svg)](https://greenkeeper.io/) \n\nRe-usable Gulp Toolkit for WordPress Themes.\n\nThis 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.\n\nA 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/).\n\n## Installation\n\nUsing the package is simple - within your custom theme create a `package.json` which has `gulp` and `gulp-wp-toolkit` as dependencies.\n\nMake sure to update the other parts of your `package.json` too, as these will be pulled in to form the theme stylesheet header\n\nAdd a `package.json` to your theme like so:\n\n```\n{\n  \"name\": \"craigsimpson\",\n  \"homepage\": \"https://craigsimpson.scot/\",\n  \"version\": \"1.0.0\",\n  \"author\": \"Craig Simpson \u003ccraig@craigsimpson.scot\u003e\",\n  \"description\": \"Custom WordPress theme, based on the Genesis Framework.\",\n  \"repository\": \"\",\n  \"license\": \"GPL-2.0\",\n  \"main\": \"Gulpfile.js\",\n  \"devDependencies\": {\n    \"gulp\": \"^3.9.1\",\n    \"gulp-wp-toolkit\": \"^2\"\n  }\n}\n```\n\nThen create a simple `Gulpfile.js` in your theme root, like this:\n\n```\n'use strict';\n\nvar gulp = require('gulp'),\n    pkg = require('./package.json'),\n    toolkit = require('gulp-wp-toolkit');\n\ntoolkit.extendConfig({\n    theme: {\n        name: \"WordPress Theme Name\",\n        homepage: pkg.homepage,\n        description: pkg.description,\n        author: pkg.author,\n        version: pkg.version,\n        license: pkg.license,\n        textdomain: pkg.name\n    },\n    js: {\n        'theme' : [\n             'develop/vendor/a.js',\n             'develop/js/b.js'\n         ],\n         'something-conditional' : [\n             'develop/js/standalone.js'\n         ]\n    }\n});\n\ntoolkit.extendTasks(gulp, { /* Task Overrides */ });\n```\n\nOnce 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/).\n\nSee the files in the example directory for more advanced configuration.\n\nThere are also a number of posts on my blog relating to setting up Gulp WP Toolkit, including:\n\n* [Adding Gulp WP Toolkit to an existing Genesis theme.](https://craigsimpson.scot/adding-gulp-wp-toolkit-to-an-existing-genesis-theme)\n* [Gulp WP Toolkit SCSS Configuration and Options](https://craigsimpson.scot/gulp-wp-toolkit-scss-configuration-and-options)\n* [Gulp WP Toolkit JavaScript Configuration](https://craigsimpson.scot/gulp-wp-toolkit-javascript-configuration)\n* [Bulk Import Your SCSS Partials using Gulp WP Toolkit](https://craigsimpson.scot/bulk-import-your-scss-partials-using-gulp-wp-toolkit)\n* [An Overview of the Gulp WP Toolkit Build Tasks](https://craigsimpson.scot/an-overview-of-the-gulp-wp-toolkit-build-tasks)\n\n## Tasks\n\nOnce installed, the following tasks will be available to run via `gulp \u003ctaskname\u003e`.\n\n### Build\n* `gulp build` runs the following tasks:\n    * `gulp build:css` compiles SCSS into CSS.\n    * `gulp build:js` concatenates JavaScript files defined in `config.js` and outputs into the theme `/js/` directory.\n    * `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.\n    * `gulp build:i18n` runs the following tasks:\n        * `gulp build:i18npotgen` generates a translations file at `/develop/languages/textdomain.pot`, where textdomain is the theme package name within `package.json`.\n        * `gulp build:potomo` converts and `.po` files within `/develop/languages/` into `.mo` files within `/languages/`.\n* `gulp build:styleguide` (experimental) uses the SCSS files to generate a live style guide at `/develop/styleguide/` using Cortana (some setup required).\n* `gulp build:rtl` (experimental) generates an RTL stylesheet in the theme root.\n\n### Clean\nClean 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:\n\n* `gulp clean` runs the following tasks:\n    * `gulp clean:css` will delete `.css` and `.css.map` files from the theme root.\n    * `gulp clean:js` will delete `.js` and `.min.js` files from the `/js/` output directory.\n    * `gulp clean:images` will delete all image files from the `/images/` output directory.\n    * `gulp clean:i18n` will delete the generated `.pot` file within `/develop/languages/`, and the generated `.mo` files within `/languages/`\n\n### Lint\n* `gulp lint` runs the following tasks:\n    * `gulp lint:php` runs the following tasks:\n        * `gulp lint:phpcs` check the code with PHP_CodeSniffer against the WordPress Coding Standards.\n        * `gulp lint:phpmd` check the code with PHP Mess Detector.        \n    * `gulp lint:style` runs the following tasks:\n        * `gulp lint:scss` uses `stylelint` to check SCSS files against the WordPress Coding Standards.\n        * `gulp lint:css` uses `stylelint` to check CSS files against the WordPress Coding Standards.\n        * `gulp lint:colors` checks colour usage within SCSS files using `gulp-colorguard`.\n    * `gulp lint:js` runs the following tasks:\n        * `gulp lint:json` checks that any JSON files (for ACF, etc) are valid.\n        * `gulp lint:jsvalidate` runs JSValidate on project JS files..\n        * `gulp lint:eslint` runs ESLint on project JS files.\n\n### Watch\nThe 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.\n \n### Serve\nRunning `gulp serve` will launch a new BrowserSync session, proxying the localhost URL which is defined in your theme's config under `server` -\u003e `url` key. If the key is not defined, then BrowserSync won't start.\n\nOur `gulp watch` task will also run, and your browser will live reload when any changes are detected.\n\nBrowserSync can also run independently of `gulp watch` by running `gulp browser-sync`.\n\n### Default\n\nThe default task (`gulp`) will run `gulp build` and `gulp serve`. \n\n### Bump\nEasily 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/).\n\n* `gulp bump` updates the patch version. 1.0.0 to 1.0.1\n* `gulp bump --patch` updates the patch version. 1.0.0 to 1.0.1\n* `gulp bump --minor` updates the minor version. 1.0.0 to 1.1.0\n* `gulp bump --major` updates the major version. 1.0.0 to 2.0.0\n\n\n## Default Theme Structure\n\nThe 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.\n\nA typical theme structure may look like:\n\n```\n.\n├── develop/\n│   ├── images/ (original images)\n│   ├── js/ (JavaScript module files)\n│   ├── languages/\n│       ├── theme-name.pot (generated by Gulp WP Toolkit)\n│       └── en_GB.po\n│   └── scss/\n│       ├── base/ (structure your SCSS how you want)\n│       ├── variables/ (structure your SCSS how you want)\n│       └── style.scss (reference your SCSS structure here)\n├── images/ (generated by Gulp WP Toolkit)\n├── js/ (generated by Gulp WP Toolkit)\n├── languages/ (generated by Gulp WP Toolkit)\n├── node_modules/ (generated by npm / yarn)\n├── src/ (PHP classes)\n├── templates/ (WP template files)\n├── tests/\n│   ├── Integration/\n│   └── Unit/\n├── vendor/ (generated by Composer)\n└── views/ \n\n```\n\n## Sass Bulk Import\n\nUse 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.\n\nIf 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'`.\n\n## Bower\n\nThis 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.\n\n## Overrides\n\n### Updating Config\n\nAll 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.\n\n### Adding Tasks\n\nAdditional 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).\n\n### Custom Lint Files\n\nYou 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`.\n\n## Contributing to Gulp WP Toolkit\n\nPlease see [CONTRIBUTING](.github/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcraigsimps%2Fgulp-wp-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcraigsimps%2Fgulp-wp-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcraigsimps%2Fgulp-wp-toolkit/lists"}