Libraries

Read an overview about Frontal Libraries

A library defines a set of rules, these rules tells Frontal which Style and Javascript assets to load and in which order, A library can also provide components, that can be optionally enabled for certain pages.

By activating a Library within a Frontal application, Frontal will automatically merge and load the library rules within the primary bundle of the application with no further configuration.

Creating a Library

A library can be an NPM package or simply a directory within your frontal application, a library's entry point should be a configuration file, that file should export a function which frontal uses as the setup function for the library, lets look at a minimal Library config:

// library/library.config.js
module.exports = (opts, lib) => {
    // @todo add your library assets
}

The exported function accepts two arguments:

  • opts: is an object containing configuration options that can be passed when using the Library within a Frontal application.
  • lib: is an object that contains several methods that enables the Library developer to outline which assets to import, check the API reference of the lib.
Read an in-depth guide to creating a Frontal library.

Using a Library

By default, if Frontal finds a library config file at library/library.config.js it will be enabled within the project, given the example config above, the library instructions will automatically be merged within the main bundle.

However, if your library exists within an NPM package or at a different location, the following configuration can be used to locate the library:

// frontal.config.js
module.exports = {
    library: {
        // the location property should be an absolute path to the library's config file
        location: require.resolve('../path/to/library/library.config.js')
    }
}

If a library exists within an NPM package, the package.json file of that package should have its main file pointing to a valid library config file, that said, a library can be used as follows:

// frontal.config.js
module.exports = {
    library: {
        location: require.resolve('../path/to/library')
    }
}

Or it can be an installed library package within your frontal application:

// frontal.config.js
module.exports = {
    library: {
        location: require.resolve('frontal-bootstrap-library')
    }
}

Passing configuration options to a Library

A library developer can provide options for the library user to provide, in order to change the behaviour of the library, these options can be passed as follows:

// frontal.config.js
module.exports = {
    library: {
        location: require.resolve('frontal-bootstrap-library'),
        options: {
            skin: 'dark'
        }
    }
}

Choosing which bundle the library should bind to

Usually your frontal config should have at-least one bundle, by default, Frontal will bind the library assets with a bundle named main or the first bundle within your bundles object.

However, if you are looking to change the default bundle a library should bind to, you can configure Frontal as follows:

// frontal.config.js
module.exports = {
    library: {
        location: require.resolve('frontal-bootstrap-library'),
        bundle: 'myBundle'
    },

    bundles: {
        myBundle: {
            pages: ['**/*.html']
        }
    }
}

Using a library's components

If a library provides components, these components can be picked selectively for each page or a group of pages as follows:

// frontal.config.js
module.exports = {
    library: {
        location: require.resolve('frontal-bootstrap-library'),
    },

    bundles: {
        main: {
            pages: ['**/*.html'],
            components: {
                forms: true,
            }
        },
        charts: {
            pages: ['overview.html', 'payments.html'],
            components: {
                charts: true,
                datatable: true
            }
        }
    }
}
  • For all pages the library's primary assets will be added as well as the forms component.
  • For the overview.html and payments.html pages the charts and datatable components will be used.

Frontal will automatically add the appropriate bundles to the pages per the configuration.

Would You Like To KnowAbout Our Next Products & Free Tools?