A full featured configurable gulp asset pipeline and static site builder
Gulp Starter is a delicious blend of tasks and build tools poured into Gulp to form a full-featured modern asset pipeline. It can be used as-is as a static site builder, or can be configured and integrated into your own development environment and site or app structure. The extras folder contains configuration details for Rails and Craft, with more to follow. Check out the compiled demo and play with the source files!
git clone MyAppcd MyAppnpm installnpm start
|CSS||Sass (Libsass via node-sass), Autoprefixer, CSSNano, Source Maps|
|HTML||Nunjucks, gulp-data, or bring your own|
|Images||Compression with imagemin|
|Icons||Auto-generated SVG Sprites and/or Icon Fonts|
|Live Updating||BrowserSync, Webpack Dev Middleware, Webpack Hot Middleware|
|Production Builds||JS and CSS are uglified and minified, filename md5 hashing (reving), file size reporting, local production Express server for testing builds.|
|JS Testing||Karma, Mocha, Chai, and Sinon, Example Travis CI integration|
Make sure Node installed. I recommend using NVM to manage versions.
This currently tested against Node
6.3.0, and should work on newer versions as well. File an issue if it doesn't! If you need
git checkout 3520e67 or earlier.
npm run gulp,
npm run development
This is where the magic happens. The perfect front-end workflow. This runs the default gulp task, which starts compiling, watching, and live updating all our files as we change them. BrowserSync will start a server on port 3000, or do whatever you've configured it to do. You'll be able to see live changes in all connected browsers. Don't forget about the additional BrowserSync tools available on port 3001!
Why run this as an npm script? NPM scripts add ./node_modules/bin to the path when run, using the packages version installed with this project, rather than a globally installed ones. Never
npm install -g and get into mis-matched version issues again. These scripts are defined in the
scripts property of
npm run test:watch
npm run test
npm run production
By default, the files in
src are pretty minimal. If you're just exploring and would like to play with the demo files, the files available in
extras/demo. Just replace
config.json with the ones in
extras/demo, or simply check out the
git checkout demonpm start
If you plan on using this to start a new project, be sure and clear out the
git data start a fresh history:
rm -rf .git && git initgit commit -m "Initialized with Gulp Starter"
Directory and top level settings are convienently exposed in
gulpfile.js/config.json. Use this file to update paths to match the directory structure of your project, and to adjust task options.
All task configuration objects have
dest directories specfied. These are relative to
root.dest respectively. Each configuration also has an extensions array. This is used for file watching, and file deleting/replacing.
If there is a feature you do not wish to use on your project, simply delete the configuration, and the task will be skipped.
Not all configuration is exposed here. For advanced task configuration, you can always edit the tasks themselves in
cleanFirstTells gulp to clean target directory before task is running.
reportSizesSet to true if you want to see a size report when running the "production" or "build" task.
watchIn "development" and "production" task the watcher will be disabled if you set this to "false".
watchProductionEnables the watcher in "production" task if you set this to "true".
npm run gulp
npm run development)
./node_modules/bin, using the version installed with this project, rather than a globally installed instance. All commands in the package.json
scripts work this way. The
gulp command runs the
default task, defined in
All files will compile in development mode (uncompressed with source maps). BrowserSync will serve up files to
localhost:3000 and will stream live changes to the code and assets to all connected browsers. Don't forget about the additional BrowserSync tools available on
localhost:3001! You can also pass any supported option from browserSync into config (e.g. browser: false). If you don't want to start a server, simply remove the key "server" from your browserSync options.
To run any other existing task, simply add the task name after the
gulp command. Example:
npm run gulp production
README.md with details about each asset task are available in their respective folders in the
npm run production
This will compile revisioned and compressed files to
./public. To build production files and preview them locally, run
revIf you want to revise your asset files in the resulting html code (append hash) you'll have to specify the source (src) and target (dest) directory where your html files are written to.
npm run demo
This will start a static server that serves your production files to http://localhost:5000. This is primarily meant as a way to preview your production build locally, not necessarily for use as a live production server.
npm run test
Test files located in
__tests__ folders are picked up and run using
Karma, Mocha, Chai, and Sinon. The test script right now first compiles a production build, and then, if successful runs Karma. This is nice when using something like Travis CI in that if an error occurs during the build step, Travis alerts me that it failed. To pass, the files have to compile properly AND pass the JS tests.
npm run deploy
This task compiles production code and then uses gulp-gh-pages to push the contents of your
dest.root to a
gh-pages (or other specified) branch, viewable at http://[your-username].github.io/[your-repo-name]. Be sure to update the
homepage property in your
GitHub Pages isn't the most robust of hosting solutions (you'll eventually run into relative path issues), but it's a great place to quickly share in-progress work, and you get it for free.
Surge.sh might be a good alternative for production-ready static hosting to check out, and is just as easy to deploy to. Where ever you're deploying to, all you need to do is
npm run gulp production and transfer the contents of the
public folder to your server however you see fit.
For non-static sites (Rails, Craft, etc.), make sure the
production task runs as part of your deploy process.
gulpfile.jsis now a directory
htmltask w/ Nunjucks templating/compiling
servertask to test production files locally
deploytask to deploy the public directory to gh-pages
revtask that revisions filenames and compress css and js
gulp.watch(correctly handles new files)
productiontask runs tests, compression + filename revisioning
Original Blog Post: https://www.viget.com/articles/gulp-browserify-starter-faq