Dn-gulp-base NPM

DN Gulp base

dn-gulp-base is a set of gulp tasks which aim to provide maximum backwards-compatibility for forward-moving webapps. It allows you to quickly get started with new projects without worrying about setting up optimized webpack-, less- or other compilation config, while offering flexibility to differentiate from the defaults where desired.

Requirements

Node 12 or greater. Node 16 is recommended.
Gulp 4.x

Project requirements

This package only provides the loaders that you need for webpack to compile your javascript or js-wrapped code. If, for example, your project uses less-css inside javascript, you will need to include the node less package in your projects devDependencies.

The same goes for linters -- if you want dn-gulp-base to properly lint your javascript or css code, you will need to ensure these tools are included with your own devDependencies. This is done so that the tooling does not dictate the exact version you use, only what major versions are supported.

Usage

Install: yarn add dn-gulp-base --dev
Add a gulpfile.js to your project with the following content:

/*
|--------------------------------------------------------------------------
| Gulpfile
|--------------------------------------------------------------------------
|
| Any automated tasks for this webapp are specified here.
|
| @copyright (c), 2020 Digital Natives
*/
require('dn-gulp-base');

You can define additional tasks or override existing ones from here.

Configuration

In your project, you can add two config files

`/tasks/config.personal.js`

This task should NOT be checked into the repository and contains personal information for your own dev environment.

`/tasks/config.project.js`

This task should be checked into the repository and contains configuration for your project.

// Just an example
module.exports = {
    notify: true,
    beep: true,

    browserSync: {
        proxy: 'https://myproject.test'
    },

    logDir: './tasks/logs'
}

Task sets

Im addition to generic configuration, you can define additional sub-applications which will be used to generate an extra set of all the default tasks supplied with this package. This package comes with a predefined task set for 'apps'.

Override the paths and components for this task set by creating your own /tasks/sets/app.js. You can also define additional sets by adding new files in this folder.

Example:

const srcBasePath = './src';
const outputBasePath = './public';

module.exports = {
    js: {
        // These context in which webpack will operate
        context:  `${srcBasePath}`,

        bundleSource: 'app.js',
        codeSplitting: false,
        transpileModules: ['vuex'], // optional, transpiles optional node module targets
        usePostCSS: false, // when enabled, inteprets any `<style lang="css">` components as postcss

        // Base name of the compiled JavaScript file
        baseName: 'app',

        outputDir: `${outputBasePath}/js`,
        publicPath: '/js/', // Path of the output-dir relative to the docroot

        // Just and example of how to pass custom options, you probably won't actually need these
        // This is also an example to output multiple entry points to multiple bundles
        customWebpackOptions: {
            optimization: {
                minimizer: [new TerserPlugin({ terserOptions: { safari10: true })],
            },
            entry: {
                home: `${srcBasePath}/home.js`,
                about: `${srcBasePath}/about.js`,
                contact: `${srcBasePath}/contact.js`
            },
            output: {
                filename: '[name].bundle.js'
            }
        },

        /*
         * OPTIONAL: setOptions callback.
         *
         * If the above way of customizing the options for webpack is not enough
         * you can use this callback to change the options completely. This callback
         * is called last just before passing the config to webpack. The first option
         * is the complete options object. Pass the modified result back after changing.
         */
        customWebpackOptionsCallback(setOptions) {
            return setOptions;
        }

    },

    less: {
        src: `${srcBasePath}/styles/app.less`,

        watch: [
            `${srcBasePath}/styles/**/*.less`,
            `${srcBasePath}/app/patterns/**/**/*.less`
        ],

        lint: [
            `${srcBasePath}/styles/**/*.less`,
            `${srcBasePath}/app/patterns/**/*.less`
        ],

        baseName: 'app',
        outputDir: `${outputBasePath}/css`,

        /*
         * OPTIONAL: processors
         *
         * Using the processors parameter you can change the processors that
         * are passed to postcss. You can pass either an array which will
         * completely override the processors or you can use a callback. The
         * first param of the callback is the current list of processors. This
         * way you can change and add to the defaults.
         */
        processors: [],
        processors(processors) {
            return processors;
        }
    },

    fonts: {
        entries: [
            `${srcBasePath}/assets/fonts/**/*`
        ],

        watch: [
            `${srcBasePath}/assets/fonts/**/*`
        ],

        outputDir: `${outputBasePath}/fonts`
    },

    videos: {
        entries: [
            `${srcBasePath}/assets/videos/**/*`
        ],

        watch: [
            `${srcBasePath}/assets/videos/**/*`
        ],

        outputDir: `${outputBasePath}/videos`
    },

    images: {
        src: `${srcBasePath}/assets/img/**/*.{png,jpg,jpeg,gif,svg}`,

        watch: [
            `${srcBasePath}/assets/img/**/*.*`
        ],

        outputDir: `${outputBasePath}/images`
    }
};

Using hashed javascript files

dn-gulp-base will produce files that contain a hash that is used for cache-busting. Using this, you can safely cache javascript files forever on production, as the hash will change when the file contents do, and these will be picked up immediately as the file-name is different.

To support this, you will of course need to include these dynamic filenames in your templates. Here are some examples using twig and blade.

Twig

If you're using Craft CMS, you should use our Craft Webpack Assets Plugin.

Refer to the README of that plugin in how to implement the assets in Craft. Below is an example of how to use the additionally required webpack-manifest-plugin with your gulp-base config.

yarn add --dev webpack-manifest-plugin

const { WebpackManifestPlugin } = require('webpack-manifest-plugin');

module.exports = {
    js: {
        ...yourConfig,
        customWebpackOptions: {
            plugins: [
                new WebpackManifestPlugin({
                    filter: (file) => {
                        // We want only JS files included
                        return !!file.name.match(/^.+(\.js)+$/);
                    }
                })
            ],
        }
    }
}

Blade

@php
    $scripts = file_get_contents('../public/js/app_scripts.html');
@endphp
{!! $scripts !!}

Customize the script tags

You can customize the way the app_scripts.html is generated by using js.customWebpackOptions (default config for reference below)

{
    plugins: [
        new HtmlWebpackPlugin({
            title: taskSet,
            filename: `${taskSet}_scripts.html`,
            prefetch: false,
            template: path.resolve(__dirname, '../resources/scripts_output.html')
        }),
    }
}

See the docs for more info: https://webpack.js.org/plugins/html-webpack-plugin/

Contributing

Please submit contributions through a merge request.

All commits on this repository MUST comply with the Conventional Commits Standard. Running yarn install on your local machine should enforce all local commits to adhere to this standard. If you're new to conventional commits you're encouraged to use Comittizen to learn the ropes.

Releasing

Only package maintainers should release new versions. A changelog is automatically maintained using standard-version. Run yarn run release to bump/tag the version, generate the changelog and immediately publish the next release

note: Don't fill out the version number in the prompt. Just immediatly press "enter". This is because yarn run release is a combination of standard-version and vanilla yarn publish, where the latter will prompt you for a new version which standard-version has already incremeted automatically.