Dynamic assets

As themes are getting more and more complicated, we need to way of excluding some theme files from sync. That's why in Publii v.0.39 we have added a new feature called dynamic assets.

This feature requires to work three things:

  • option files.useDynamicAssets under theme config.json must be set to true
  • theme must contain file dynamic-assets-mapping.js
  • theme should contain dynamic directory under assets directory

How to implement dynamic assets?

Let's analyze how it is implemented in our Simple theme to handle local fonts without uploading all possible font files to the server during sync.

Under theme config.json we will find these fragments:

"files": {
    "useDynamicAssets": true,

Option files.useDynamicAssets enables use of the dynamic assets at all.

Under assets directory we will find the following structure:

- dynamic
  - fonts
    - andadapro
      - OFL.txt
      - andadapro.woff2
    - antonio
      - OFL.txt
      - antonio.woff2
    - yanonekaffeesatz
      - OFL.txt
      - yanonekaffeesatz.woff2

It is almost 50 different fonts - uploading them during sync would be time-consuming.

That's why we create file dynamic-assets-mapping.js in the theme root directory, which contains a function with access to the theme configuration:

 * Generate  dynamic assets

module.exports = function (themeConfig) {
   let fontBody = themeConfig.customConfig['fontBody'];
   let fontHeadings = themeConfig.customConfig['fontHeadings'];

   return [
      '/fonts/' + fontBody + '/' + fontBody + '.woff2', 
      '/fonts/' + fontHeadings + '/' + fontHeadings + '.woff2'

Above function returns a list of files from assets/dynamic/ directory which will be deployed during sync. Other files from assets/dynamic/ directory won't be synced.