JDA-Jumpstart

Overview

This can be used as a quick start for gulp projects. Designed for use with WordPress, but should work pretty much wherever. Inspired by WPGulp by AhmadAwais.

Prerequisites

This project uses Gulp, a Node.js task runner and should already be installed as a prerequisite.

Confirm that node and npm are properly installed using the command line:

node --version
npm --version

Additionally, the Gulp command command line must be globaly installed.

npm install --global gulp-cli

You can verify that gulp-cli is installed by running

gulp --version

Finally, portions of this project are built using Composer, and npm postinstall will fail if Composer is not installed. Verify composer is properly installed with:

composer --version

Quickstart: Homebrew on macOS

On macOS, ensure command line tools are installed. If they are not, install them using

xcode-select --install

Then, install and update Homebrew. At the time of this writing, past the following into terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew doctor
brew upgrade

Next, install node, gulp-cli and:

brew install node gulp-cli composer

Installing this project

After the prerequisites have been met, navigate to your the wp-content/themes/ folder and create a new folder to house your new theme. Inside this folder, run npx jda-jumpstart

If you just need the compiler, run npx jda-jumpstart-gulp .. Please note, this will just install the package.json and gulpfile.js files for use as a standalone compiler, which will overwrite any existing version of these files.

Run the compiler with gulp.

Scaffolding Overview

1. Create a new, empty repo (ex: jda-theme).
2. Spin up a new local WordPress (Local by Flywheel, MAMP, etc.). Take note of the projects local address.
3. Clone the repo to the new site wp-content/themes/ directory.
4. Inside the new theme folder, run npx jda-jumpstart.
5. Edit package.json. At minimum, update the name, theme-name, and urls:local properties.
6. Run gulp once to ensure everything works as expected.
7. Commit the scaffolded project back to git.

git add .
git commit -m "Initial commit."
git push

8. Initialize Gitflow using Tower, or manually through the CLI.

Theme Folder Overview

/build/: This folder contains all of the files created / processed by the Gulp compiler. This folder is rewritten everytime gulp runs. DO NOT manually place files in this folder.

/inc/: This folder contains our core theme library, including our init.php file which sets our directory variabiables, handles our CSS/JS enqueues, loads our required plugins, and provides our utility functions like jump_debug().

/node_modules/: This folder should be excluded from our production server either manually or by running gulp zip.

/src/: This folder contains all of our source files for gulp.

/src/copy/: Anything in this folder will be copied to the build directory. For example, a fonts folder located at /src/copy/fonts/ will be copied, along with all of its contents, to /build/fonts/.

/src/img/: Place any images that need minified for use by the theme (not CMS) in this folder. They can be found at /build/img/.

/src/js/: This folder contains an app.js and modules folder for the admin, blocks, and frontend section of the theme.

/src/sass/: Please refer to the jda-jumpstart-sass README for correct use of these folders. Compiled files will live in /build/css/.

/src/svg/: This folder is used to create SVG sprites. The compiled file can be found at /build/svg/.

/template-parts/: This folder contains all html/php source files used in various places in the theme.

/template-parts/blocks/: This folder contains all Gutenberg blocks. We recommend using ACF blocks to simply the creation of blocks. Each block should live inside of its own, named folder (ex: /template-parts/blocks/SampleBlock/) and contain a blocks.json and a php render template (ex: /template-parts/blocks/SampleBlock/SampleBlock.php).

/template-parts/widgets/: This folder should contain all of our registered widgets.

/vendor_libraries/: This folder is automatically created by Gulp to symlink our frontend dependencies as defined in our package.json file.