Skip to content

Configuration

Jump to bottom
Kaspars Zuks edited this page Jun 20, 2022 · 15 revisions
Table of Contents

Configuration file
Disabling tasks
Development / production specific configuration
Default configuration

Plugins

Configuration file

By default builder will look for configuration file in config/config.js.

Configuration config.js path can be changed by:

  • setting BUILDER_CONFIG_FILE environmental variable, it's relative to the project folder or
  • passing builder --config=config/config.js argument, it's relative to the project folder.

Disabling tasks

Each task can be disabled by setting its configuration to false

// Disable whole html task
exports.html = false;

Some tasks has specific settings which can be disabled too

// Disable html minification
exports.html = { htmlmin: false };

Development / production specific configuration

Configuration for development and production builds may need to be different, eg. disabling a task or changing task configuration. To allow this, configuration object can have production or development properties, which are merged recursively into the main configuration. These properties can appear at any level

javascripts configuration

exports.javascripts = {
  webpack: {
    output: {
      // Default, in this example it's useless because either development or production will overwrite it
      filename: './[name].js',

      development: {
         // Overwrites filename in development mode
         filename: './[name].js',
      },
      production: {
         // Overwrites filename in production mode
         filename: './[name].js',
      },
    }
  },
  development: {
    webpack { /*... */ }
  },
  production: {
    webpack { /*... */ }
  }
};

Default configuration

global

Global source file and destination folders where to compile / copy source into

exports.paths = {
    src: './src',
    dest: './public',
};

browserSync

exports.browserSync = {
  // See https://www.browsersync.io/docs/options for options
};

exports.paths = {
    browserSync: {
        // Server root directory, relative to the project
        // If not set then global dest folder
        'dest': null,
    }
};

clean

Clean tasks removes files from previous builds

exports.clean = {
  // Patterns, relative to the destination folder
  // see https://gulpjs.com/docs/en/getting-started/explaining-globs/
  patterns: ['assets/**', 'temp-folder']
};

data

Data task loads JS and JSON files to be used in the TWIG templates

exports.data = {
    extensions: [
        // File extensions from which to load data
        'js',
        'json'
    ],

    loaders: {
        // Data loaders for extensions, allows to add custom loaders
        js: require('@videinfra/static-website-builder/tasks/data/data-loader-js'),
        json: require('@videinfra/static-website-builder/tasks/data/data-loader-json'),
    },

    // Group data by filename (without extension + cammelCase)
    // eg, person-names.js -> {'personNames': ...}
    groupByFileName: false,
};

exports.paths = {
    data: {
        'src': 'html/data',
    }
};

By default all data from all files will be merged ignoring the filename. By settings groupByFileName: true filename will be used to group data, eg.

person.json

{
  "name": "John"
}

will create an object and in templates which allows to use

{{ person.name }}

fonts

Fonts task copies font files from source into destination folder

exports.fonts = {
  // Glob list of files, which to ignore, relative to the font source folder
  // see https://gulpjs.com/docs/en/getting-started/explaining-globs/
  ignore: [],

  // Font file extensions
  extensions: ['woff2', 'woff', 'eot', 'ttf', 'svg', 'otf'],
};

exports.paths = {
    fonts: {
        'src': 'fonts',
        'dest': 'assets/fonts',
    }
};

html

HTML task copies html files from source into destination folder and minifies them.

To enable Twig rendering include Twig plugin in the plugin list

exports.html= {
  // Filename extensions, TWIG plugin adds 'twig' extension
  extensions: ['html'],
  
  // Glob list of files, which to ignore, relative to the html source folder
  // see https://gulpjs.com/docs/en/getting-started/explaining-globs/
  // TWIG plugin adds folders, 'macros', 'layouts', 'partials', 'shared' to the list
  ignore: [
  ],
  
  // Production only settings, overwrites default settings
  production: {
    // Enable HTML minification
    htmlmin: {}
  },
  
  // Development only settings, overwrites default settings
  development: {
    // Disable HTML minification
    htmlmin: false
  },
};

exports.paths = {
    html: {
        'src': 'html',
        'dest': '',
    }
};

icons

Icons task takes individual SVG icons and creates an SVG sprite icons.svg

exports.icons = {
  // Glob list of files, which to ignore, relative to the icon source folder
  // see https://gulpjs.com/docs/en/getting-started/explaining-globs/
  ignore: [],

  // Filename extensions
  extensions: ['svg'],

  // SVG store configuration
  // see https://github.com/w0rm/gulp-svgstore
  svgstore: {},

  // SVG min configuration
  // see https://github.com/ben-eb/gulp-svgmin#plugins
  svgmin: [],
};

exports.paths = {
    icons: {
        'src': 'icons',
        'dest': 'assets/images',
    }
};

images

Images task copies all files from image source folder into destination folder

exports.images= {
  // Glob list of files, which to ignore, relative to the image source folder
  // see https://gulpjs.com/docs/en/getting-started/explaining-globs/
  ignore: [],
};

exports.paths = {
    images: {
        'src': 'images',
        'dest': 'assets/images',
    }
};

javascripts

Javascript task transpiles and bundles JS using Webpack and Babel

exports.javascripts = {
    // Glob list of files, which to ignore, relative to the javascript source folder
    // see https://gulpjs.com/docs/en/getting-started/explaining-globs/
    ignore: [],

    // JS file extensions
    extensions: ['js', 'json'],

    // Instead of 'entry' we provide filename which list all entries
    entryList: '_entries.js',

    // Webpack configuration
    // see https://webpack.js.org/configuration/
    webpack: { /* ... */ },
};

exports.paths = {
    javascripts: {
        'src': 'javascripts',
        'dest': 'assets/javascripts',
    }
};

sizereport

Size report task generates file size report after production build

exports.sizereport = {
  // see https://www.npmjs.com/package/gulp-sizereport#options
};

static

Static task copies all files from static source folder into static destination folder

exports.static = {
  // Glob list of files, which to ignore, relative to the static source path
  // see https://gulpjs.com/docs/en/getting-started/explaining-globs/
  ignore: [],
};

exports.paths = {
    static: {
        'src': 'static',
        'dest': '',
    }
};

stylesheets

Stylesheets task copies CSS files and runs them though postcss with autoprefixing and minification

To enable SASS/SCSS compiling include SASS plugin in the plugin list

exports.stylesheets = {
  // Glob list of files, which to ignore, relative to the stylesheet source folder
  // see https://gulpjs.com/docs/en/getting-started/explaining-globs/
  ignore: [],

  // File extensions
  // SASS plugin adds 'scss'
  extensions: ['css'],

  // Auto prefixer options, set to `false` to disabled
  // see https://github.com/postcss/autoprefixer#options
  autoprefixer: {},

  // CSS nano, set to `false` to disabled
  // see https://cssnano.co/guides/optimisations
  cssnano: {},

  // PostCSS plugins and options, set to `false` to disabled
  // see https://github.com/postcss/postcss
  postcss: {
    plugins: [],
    options: {},
  },

  // Sourcemaps, set to `false` to disabled
  // see https://www.npmjs.com/package/gulp-sourcemaps
  sourcemaps: {
    init: {},
    write: {}
  },
};

exports.paths = {
    stylesheets: {
        'src': 'stylesheets',
        'dest': 'assets/stylesheets',
    }
};

Plugins

SASS plugin

Add SASS and SCSS file compilation

exports.plugins = [
  require('@videinfra/static-website-builder/plugins/sass')
];
exports.stylesheets= {
  // SASS options
  // see https://github.com/sass/node-sass#options
  sass: {
    includePaths: ['./node_modules'],
  },

  // Use legacy `node-sass` instead of modern `sass`
  legacy: true,
};

Using Dart SASS

exports.stylesheets = {
    sass: {
        legacy: false,
    }
};

TWIG plugin

TWIG support to render .twig templates into html

exports.plugins = [
  require('@videinfra/static-website-builder/plugins/twig')
];
exports.html = {
  // see https://github.com/twigjs/twig.js/
  twig: {},
};

TWIG symfony plugin

Additional TWIG filters to mimic symfony:

  • humanize - makes a technical name human readable
  • cdnify - adds a CDN path to the url
  • version - adds a random version string to the url

Additional TWIG functions to mimic symfony:

  • asset() - adds a CDN and version string to the url
exports.plugins = [
  require('@videinfra/static-website-builder/plugins/twig/symfony-filters'),
  require('@videinfra/static-website-builder/plugins/twig/symfony-functions')
];
exports.html = {
  // List of CDNs when using symphony filters / funtions
  cdns: [],

  // Add file version number when using symphony filters / funtions
  version: false,
};

TWIG lodash plugin

Additional TWIG filters from lodash:

exports.plugins = [
  require('@videinfra/static-website-builder/plugins/twig/lodash-filters'),
];
Clone this wiki locally