Configuration

Learn how to configure Frontal using the `frontal.config.js` file

Frontal is configured to work out of the box with no configuration, however, most of the use cases will require having a custom frontal.config.js.

The configuration file

Create a file named frontal.config.js within the root directory of your project, this file should export an object.

module.exports = {
    ...
};

Or it could export a function that returns an object:

module.exports = (env) => ({
    ...
})

Each configuration property within the returned object is explained below.

.bundles

the bundles property takes an object, whose keys are the bundle names, and the values are an object that takes the following properties:

PropertyTypeDescription
assetsAn array of strings or objectsAssets to load within the bundle, these assets can be installed modules names or files to load.
pagesAn array of stringsAn array of glob filters that indicate which pages to auto inject the bundle within.

Example 1

module.exports = {
  ...
  bundles: {
    bundle1: {
      assets: ['jquery', '@assets/app.js'],
      pages: ['**/*.html'],
    },
    bundle2: {
      assets: ['chart.js', '@assets/stats.js'],
      pages: ['overview.html', 'payments.html'],
    },
  },
  ...
};

The previous bundles configuration indicates:

  • that bundle1 will contain jquery and app.js and will be loaded for all pages, hence the pages glob filter **/*.html.
  • and bundle2 will contain chart.js and stats.js and will only be loaded for overview.html and payments.html pages.

Example 2

As mentioned above, the assets array can also take objects, that enables two important features:

  • provideAs: enables exposing the imported module within the global scope, but that module has to export those names as well.
  • order: enables modifying the order of loading assets.
module.exports = {
  ...
  bundles: {
    primary: {
      assets: [
        { path: '@assets/app.js', order: 1 }
        { path: 'jquery', provideAs: ['jQuery', '$'] },
      ],
      pages: ['**/*.html'],
    },
  },
  ...
};

The previous example indicates that the primary bundle is loaded for all pages with the following rules:

  • the jquery asset will be provided globally with $ and jQuery, giving you the ability to work with jQuery directly using script tags within your HTML pages or within your .js files without having to import jquery.
  • by default, all assets has an order of 0, that said, the app.js with order set to 1 will ensure that Frontal loads the app.js after loading the jquery asset.

.directories

The directories property enables you to customize the primary directories required for frontal to function:

PropertyTypeDescription
assetsstringThe name of the assets directory.
buildstringThe name of the build directory.
publicstringThe name of the public directory.
module.exports = {
    ...
    directories: {
        assets: 'assets',
        build: '.frontal',
        public: 'public'
    }
    ...
};

.server

The server property takes an object that enables customizing the behaviour of the Development and Production servers, below are the options available for the server property.

PropertyTypeDescription
hoststring or undefinedThe host name to bind the server to, can be set to `undefined` in order to auto bind to the machine's network address.
portIntegerThe port number to bind the server to, if the port is in use, frontal will attempt to automatically use a different port.
basestringThe base path for the server, if your website has a prefix, for example `site.com/blog` then the base url should be set to `/blog/`.
module.exports = {
  ...
  server: {
    host: 'localhost',
    port: 3000,
    base: '/',
  },
  ...
};

.pages

The `pages` property enables configuring the behaviour of working with Pages

PropertyTypeDescription
locationstringThe name of the pages directory where Frontal will lookup pages.
partialsstringThe name of the partials directory, that directory is intended to exist within the pages directory.
modulesstringThe name of the modules directory, that directory is intended to exist within the pages directory.
extensionsarrayAn array containing file extensions to lookup within the pages directory, Frontal only supports .html for now.
html.formatstring or booleanDefine how Frontal should format the HTML pages, this value can either be minify to minify the HTML output or beautify to organize the HTML output. Set to false to disable this feature.
module.exports = {
  ...
  pages: {
    location: 'pages',
    partials: '.partials',
    modules: '.modules',
    extensions: ['html'],
    html: {
      format: false,
    },
  },
  ...
};

.build

Customize the behaviour of the final build, such as where to put each type of files within the build directory or even configuring assets optimization options.

PropertyTypeDescription
assets.intostringThe name of the assets directory, which all processed assets will be moved within in the final build.
js.intostringThe name of the style directory where all assets of type .js will reside in the final build.
style.intostringThe name of the style directory where all assets of type CSS will reside in the final build.
images.intostringThe name of the images directory where all assets of type image will reside in the final build.
images.optimizeobjectAn object containing options for each optimizer, Check below for an example on how to configure this object.
videos.intostringThe name of the videos directory where all assets of type video will reside in the final build.
fonts.intostringThe name of the fonts directory where all assets of type font will reside in the final build.
module.exports = {
  ...
  build: {
    assets: {
      into: 'assets'
    },
    js: {
      into: 'js'
    },
    style: {
      into: 'style'
    },
    images: {
      into: 'images',
      optimize: {}
    },
    videos: {
      into: 'videos'
    },
    fonts: {
      into: 'fonts'
    }
  }
  ...
};

Configuring `images.optimize`

In order to disable optimization of images, you can configure it as follows:

module.exports = {
  ...
  build: {
    images: {
      optimize: {
        disable: true
      }
    }
  }
  ...
};

In order to customize the behaviour of each optimizer based on file types, configure it as follows:

module.exports = {
  ...
  build: {
    images: {
      optimize: {
        // the .jpeg optimizer. available options at https://github.com/imagemin/imagemin-mozjpeg
        mozjpeg: {},

        // the .png optimizers. available options at https://github.com/kevva/imagemin-optipng
        optipng: {},

        // available options at https://github.com/imagemin/imagemin-pngquant
        pngquant: {},

        // the .gif optimizer. available options at https://github.com/kevva/imagemin-gifsicle
        gifsicle: {},

        // the .svg optimizer. options at https://github.com/kevva/imagemin-svgo
        svgo: {}

        // the .webp option will enable WEBP optimizer
        // options at https://github.com/imagemin/imagemin-webp
        webp: {}
      }
    }
  }
  ...
};