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 gulpYou may also need to install it globally:
npm install -g gulpInstall loewy-assets as a development dependency:
npm install --save-dev loewy-assetsCreate 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:
gulpHere 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 styles 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 styles and js task can generate sourcemaps for you using gulp-sourcemaps.
See the css and js portions of the configuration object in config.js. We highly recommend using deep-extend to extend the configuration variable within your gulpfile.js.
Sourcemaps will not be generated while NODE_ENV is not set, or is set to production. On Windows, please run SET NODE_ENV=development in the console, and try again.
The watch command will automatically set the config.env variable to development, as it is assumed you are not in production mode.
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 or gulp 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 images
Copy files from source directory to public directory.
gulp fonts
Copy files from source directory to public directory.
gulp clean-[css/js/sprites/svg-sprites/images/fonts/all]
Cleans corresponding public directory. These commands are automatically run where appropriate, but could be triggered manually to clean up.
gulp minify-css
Minify CSS files in public directory.
gulp minify-js
Minify CSS files in public directory.
gulp minify-all
Runs minify-css and minify-js tasks.
gulp fingerprint-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 fingerprint-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.
gulp deploy-css
Runs minify-css and fingerprint-css tasks.
gulp deploy-js
Runs minify-js and fingerprint-js tasks.
gulp compile-all
Compiles all assets (Sass, JS, images, fonts, sprites, SVG sprites).
gulp build
Runs clean-all, compile-all, and minify-all tasks.
gulp deploy
Runs build, fingerprint-css, fingerprint-js tasks.
Loewy Assets assumes that you're running a directory structure like this:
Development assets, where <assets> corresponds to the assets directory that you provide:
<assets>/css<assets>/scss<assets>/js<assets>/images<assets>/fonts<assets>/sprites
<assets>/scss/partials<assets>/svg-sprites
<assets>/scss/partials<assets>/scss/partials/_svg-sprites-template.scssDistribution assets, where <public> corresponds to the public directory that you provide (the place the web server will serve the files from):
<public>/css<public>/js<public>/images<public>/fonts<public>/spritesheets<public>/svg-spritesheetsIf 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.
gulpfile.js sample files.browserslistrc sample file_sprites_extra.scss to resource folderFixed some tasks issues
Updated all dependencies
Now using Gulp 4
env (environment) variable to config objectgulp-minify-css to gulp-clean-cssjs task would never return because the done() callback was never called. (#3)assetsDir or publicDir 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:
MIT © 2019 Hedgehog Development LLC.