Library API Reference

An API reference for working with libraries

A library is essentially a javascript module that exports a function, Frontal calls this function and passes it two arguments opts and lib, in this guide we will outline the methods available for the lib argument, for when working with a library or a component config.

lib.path

lib.path(file: string): string

The path method takes in a relative path within the library directory and the method will return a string, that is, the absolute path within the library.

Example
const fPath = lib.path('assets/file.js')
/* fPath = /path/to/library/assets/file.js */

lib.js.import

lib.js.import(...rule: Array<String|Object>): void

Define javascript import rules for the library, the import method accepts import rules the same way assets are defined within the bundles in your frontal.config.js.

// library/library.config.js
module.exports = (opts, lib) => {
    // import files within the library directory using the @library alias
    lib.js.import('@library/assets/file.js', '@library/assets/file2.js')

    // import a file and define order of import. order = 1 ensures that chart.js is loaded at the end
    lib.js.import({path: 'chart.js', order: 1});

    // import a node module and make it globally available with '$' and 'jQuery'
    lib.js.import({path: 'jquery', provideAs: ['$', 'jQuery']});
}

lib.style.global

lib.style.global(...rule: Array<String>): void

Global styles should only import scss or less files, these files should only include variables, mixins or functions, because the nature of the globals is that they will be loaded multiple times within each imported style file.

// library/library.config.js
module.exports = (opts, lib) => {
    // Preload variables and mixins for each imported file using `lib.style.import`
    lib.style.global(
        '@library/style/variables.scss',
        '@library/style/mixins.scss'
    )
}

lib.style.import

lib.style.import(...rule: Array<String|Object>): void

Define style import rules for the library, each of the imported style files will have all the global imports prepended to it.

// library/library.config.js
module.exports = (opts, lib) => {
    lib.style.import('@library/style/theme.scss')

    // using order ensures that CSS utilities are loaded at the end
    lib.style.import({path: '@library/style/utilities.scss', order: 10});
}

lib.components.add

lib.components.add(name: String, setup: Function): void

Registers a new component with the given name. The setup parameter should be a function that accepts two parameters lib and an optional opts object. The same methods used with the library's lib parameter can be used with the setup function as well, its the same interface.

// library/library.config.js
module.exports = (opts, lib) => {
    // register a datatable component
    lib.components.add('datatable', (lib, opts) => {
        lib.js.import('datatable.js');
        lib.js.import('@library/components/datatable/init.js');
        lib.style.import('@library/components/datatable/style.scss');
    });
}

lib.components.register

lib.components.register(file: String): void

Register a component via a component's config file, that config file should export a function that returns an object, the object should define two properties name and setup.

The file path defined within the register method should be an absolute path.
Example
// library/library.config.js
module.exports = (opts, lib) => {
    lib.components.register(
        lib.path('./components/datatable.config.js')
    );
}
// library/components/datatable.config.js
module.exports = () => {
    name: 'datatable',
    setup(lib, opts) => {
        lib.js.import('datatable.js');
        lib.js.import('@library/components/datatable/init.js');
        lib.style.import('@library/components/datatable/style.scss');
    }
}

lib.components.autoRegister

lib.components.autoRegister(glob: String): void

When your library has too many components, the autoRegister method helps you define a glob filter of all your components' config files, as Frontal will auto register all of them automatically.

The glob filter defined within the autoRegister method should be an absolute path.
Example
// library/library.config.js
module.exports = (opts, lib) => {
    lib.components.autoRegister(
        lib.path('components/**/*.config.js')
    );
}

With the previous glob filter the following configs matches:

  • components/alert/alert.config.js
  • components/modal/modal.config.js
  • components/dir1/comp1/comp1.config.js
Would You Like To KnowAbout Our Next Products & Free Tools?