README.md

gulp-bundle-assets

Branch	Status
master

Orchestrates JS and CSS bundle creation in an efficient and configurable manner.

Install

npm i -D  @userfrosting/gulp-bundle-assets

Usage

// gulpfile.mjs
import { BundleOrchestrator } from "@userfrosting/gulp-bundle-assets";
import Gulp from "gulp";
import cleanCss from "gulp-clean-css";
import concatCss from "gulp-concat-css";
import uglify from "gulp-uglify";
import concatJs from "gulp-concat-js";

export function bundle() {
    const config = {
        bundle: {
            example: {
                scripts: [
                    "foo.js",
                    "bar.js"
                ],
                styles: [
                    "foo.css",
                    "bar.css"
                ]
            }
        }
    };
    const joiner = {
        Scripts(bundleStream, name) {
            return bundleStream
                .pipe(concatJs(name + ".js"))// example.js
                .pipe(uglify());
        },
        Styles(bundleStream, name) {
            return bundleStream
                .pipe(concatCss(name + ".css"))// example.css
                .pipe(cleanCss());
        }
    };

    return Gulp.src("src/**")
        .pipe(new BundleOrchestrator(config, joiner))
        .pipe(Gulp.dest("public/assets/"));
}

$ gulp bundle

CJS Interoperability

This is an ES module package targeting NodeJS >=18.0.0, it can be used in CJS contexts via dynamic import. Note that ESM loaders like @babel/loader or esm likely won't work as expected.

// gulpfile.cjs

// ...

module.exports.bundle = async function bundle() {
    const { BundleOrchestrator } = await import("@userfrosting/gulp-bundle-assets");

    // ...
}

Integrating bundles into your app

A results callback can be provided as a third parameter. On completion, it will be provided with a mapping for bundles to their respective virtual file paths. Note that path transformations performed after the bundler (including dest) won't be reflected and should be accounted for.

The "DIY" approach to bundle resulting mapping is used to permit deeper integration with any system, such as generating a file in the target language to decrease integration cost.

API

See docs/api.

Origins

This plugin was originally forked from gulp-bundle-assets to fix a CSS import bug. It has since undergone numerous refactors to improve performance and flexibility.

License

MIT

Contributing

See CONTRIBUTING.md.