A front-end asset pipeline driven by gulp.js.
Loewy Assets is a front-end asset pipeline driven by gulp.js that we developed in-house for all of our projects. Note that it is not a "build your own flow" type of asset pipeline. Instead, we've taken the zero-configuration approach of "install and done" - well, if you're using Laravel. If you're using something else, you'll need to define two options: where your development assets are, and where you want your production assets to go.
We make no guarantees as to the functionality or direction of the project. Use at your own risk.
With that said, Loewy Assets should be mature enough for use in real world projects. Note that this npm package and GitHub repository are fairly new, so we're still ironing out some bugs and inconsistencies. Once we hit our first minor version, things should start to stabilize.
-
If you're not already using gulp in your project, install it now as development dependency:
npm install --save-dev gulp
You may also need to install it globally:
npm install -g gulp
-
Install
loewy-assets
as a development dependency:npm install --save-dev loewy-assets
-
Create a
gulpfile.js
for your project. Use the sample as a reference. There is also a barebones sample for quick copy-pasting. -
Run
gulp
, which will automatically watch for changes to your files and run the appropriate tasks:gulp
Here are some of the features of Loewy Assets. Further details and usage examples to come.
The sass
task automatically compiles all of your Sass files into CSS with libsass through node-sass and gulp-sass.
The css
task automatically takes care of CSS prefixes with autoprefixer through gulp-autoprefixer.
The deploy-css
and deploy-js
tasks automatically fingerprint your CSS and JS assets, respectively, by using gulp-rev. A rev-manifest.json
file is also created to define the mappings from the original filenames to the fingerprinted filenames.
The js
task automatically concatenates JS assets into user-defined modules with gulp-concat.
You can either concatenate everything into a single output file (module), or separate your logic into multiple files (modules).
The sprites
task automatically generates a fingerprinted PNG spritesheet using gulp.spritesmith.
The svg-sprites
task automatically generates a fingerprinted SVG spritesheet using svg-sprite through gulp-svg-sprite.
This is an up-to-date list of the Loewy Assets built-in tasks.
-
gulp
orgulp watch
Watches all of the source files and runs the corresponding tasks when they change.
-
gulp styles
Compiles all of the Sass files into CSS files and places them in the CSS source directory.
See the
sass
portion of the configuration object in config.js.Adds automatic prefixes to the source CSS files and moves them to the public directory (the source files themselves are not affected). No concatenation is performed, as that should be done by the CSS preprocessor.
See the
css
portion of the configuration object in config.js. -
gulp js
Concatenates JS assets into user-defined modules and places them in the public directory.
See the
js
portion of the configuration object in config.js. -
gulp sprites
Automatically generates a fingerprinted PNG spritesheet.
-
gulp svg-sprites
Automatically generates a fingerprinted SVG spritesheet.
Note that this task relies on a Sass partial template. A working example is provided here. While we continue to improve our documentation, please read up on
svg-sprite
's templates here. -
gulp clean-[css/js/sprites/svg-sprites/all]
Cleans corresponding public directory. These commands are automatically run where appropriate, but could be triggered manually to clean up.
-
gulp deploy-css
Fingerprints the CSS files in the public directory and saves a
rev-manifest.json
file with mappings from the original filenames to the fingerprinted filenames. -
gulp deploy-js
Fingerprints the JS files in the public directory and saves a
rev-manifest.json
file with mappings from the original filenames to the fingerprinted filenames.
Loewy Assets assumes that you're running a directory structure like this:
-
Development assets, where
<assets>
corresponds to the assets directory that you provide:- CSS:
<assets>/css
- Sass:
<assets>/scss
- JS:
<assets>/js
- Images:
<assets>/images
- Fonts:
<assets>/fonts
- Sprites:
<assets>/sprites
- Sass partials:
<assets>/scss/partials
- Sass partials:
- SVG sprites:
<assets>/svg-sprites
- Sass partials:
<assets>/scss/partials
- Sass partial template:
<assets>/scss/partials/_svg-sprites-template.scss
- Sass partials:
- CSS:
-
Distribution assets, where
<public>
corresponds to the public directory that you provide (the place the web server will serve the files from):- CSS:
<public>/css
- JS:
<public>/js
- Images:
<public>/images
- Fonts:
<public>/fonts
- Spritesheets:
<public>/spritesheets
- SVG spritesheets:
<public>/svg-spritesheets
- CSS:
If one or more portions of your directory structure are different, you'll need to manually specify those options in the configuration object.
A: We use Sass, so that's what we included in the pipeline. Future versions may support Less, Stylus, etc. out of the box. For now, you can easily use other preprocessors by doing something like this:
assets(assetsDir, publicDir, function() {
// don't create the default Sass task
delete this.tasks.sass;
// create our own Less task
this.tasks.less = function() {
this.gulp.task('less', function() {
return gulp.src('resources/assets/less/**/*.less')
.pipe(less())
.pipe('resources/assets/css');
});
};
}, gulp);
A: We don't use any of those (yet), so we haven't included them in the pipeline. Check the CSS preprocessors answer for an example of how you can support these tools in your project.
A: Yes! The asset pipeline is platform-/framework-/language-agnostic! With that said, we built it with the mindset of using it in Laravel projects (it can act as a drop-in replacement for Laravel's Elixir). We also use it with other PHP frameworks, including WordPress and Magento.
A: That's not a question. If you're having trouble, please troubleshoot. If you're still having trouble, feel free to open an issue on GitHub.
- Fixed bug where the
js
task would never return because thedone()
callback was never called. (#3) - Fixed bug where providing an
assetsDir
orpublicDir
without a trailing slash broke the configuration. (#1)
Loewy Assets wouldn't exist without all of the wonderful tools put out there by others. These tools include:
- gulp-autoprefixer
- gulp-clean
- gulp-concat
- gulp-if
- gulp-minify-css
- gulp-rename
- gulp-replace
- gulp-rev
- gulp-sass
- gulp-svg-sprite
- gulp-uglify
- gulp.spritesmith
- require-dir
- through2
- vinyl
MIT © 2015 Loewy Design, Inc.