Assets

Brander's ability to generate assets is built on a task-based system which can be configured in the .branderrc file.

The tasks are executed sequentially in the order in which they are declared within the configuration file. A task can only be executed for a single input and output format combination, however, you can simply declare multiple tasks for different formats or specify a "options.groupBy" to split up tasks into multiple executions. For example, the following configuration is invalid as the "input.files" configuration contains files of mixed formats:

{
  "tasks": [
    {
      "task": "clean",
      "input": {
        "files": [
          "logo/**/*.min.svg",
          "logo/**/*.png"
        ]
      }
    }
  ]
}

But this can be easily fixed:

{
  "tasks": [
    {
      "task": "clean",
      "input": {
        "files": [
          "logo/**/*.min.svg",
          "logo/**/*.png"
        ]
      },
      "options": {
        "groupBy": "<%= file.format %>"
      }
    }
  ]
}

Tasks

Tasks are split into the following types:

• clean
• convert
• optimize
• package

The "task" configuration is used to identify one of these and the rest of the information is only needed to provide the specifics for that task. There are some variations relating to the configuration between these types that will be explained further in the sections below.

Some configurations can contain evaluated values. This means that you can interpolate data properties and execute embedded JavaScript using Lodash's template, granting more powerful and dynamic file paths and greater control. The following task configurations can contain evaluated values and have the corresponding variables available within them:

• "input.dir" and "input.name":
  • config -> The configuration instance.
• "output.dir" and "output.name":
  • config -> The configuration instance.
  • file -> The input file being processed. For package task, this will be the first input file.
• "options.groupBy":
  • config -> The configuration instance.
  • file -> The input file being grouped.

Some of the examples below include configurations with evaluated values.

Clean

clean tasks simply forcibly delete all of the input files found. These are generally declared before or after all other tasks, however, they can be declared at any point.

The "output" configuration is ignored entirely by this task type as there is no output generated as a result of its execution.

Formats

The following formats at supported by clean tasks:

Input Format	Output Format
Any	Ignored

Examples

Removes all PNG files before doing anything else:

{
  "tasks": [
    {
      "task": "clean",
      "input": {
        "files": "logo/**/*.png"
      }
    }
  ]
}

This is good practice to ensure a clean slate each time Brander is executed.

Convert

convert tasks are capable of converting files in one format into another.

The "output" configuration is required, however, the "output.dir" configuration is entirely optional and output files will be written to the same directory as the original input file, by default. As for the "output.file" and "output.format" configurations; only one is required but both can be provided for ultimate control. When the "output.file" configuration is provided and the "output.format" configuration isn't, an attempt will be made to derive the latter from "output.files" by parsing the file extension. Likewise, if the "output.format" configuration is provided and the "output.file" configuration isn't, an attempt will be made to derive the latter from "output.format" and the input file (i.e. "<%= file.base(true) %>." + outputFile.format).

All convert for image output formats support the "options.sizes" configuration can be used to control the number and size of output files generated per each individual input file.

Formats

The following formats at supported by convert tasks:

Input Format	Output Format
png	ico
svg	ico
svg	jpeg
svg	png

Currently, convert tasks that convert files to ico format only support 1:1 aspect ratios correctly.

Examples

Converts SVG files with 1:1 aspect ratio to PNG files:

{
  "tasks": [
    {
      "task": "convert",
      "input": {
        "files": "logo/**/*.svg"
      },
      "output": {
        "format": "png"
      },
      "options": {
        "sizes": [ 16, 32, 64, 128 256, 512, 1024 ]
      }
    }
  ]
}

Converts SVG files with 4:3 aspect ratio to PNG files:

{
  "tasks": [
    {
      "task": "convert",
      "input": {
        "files": "banner/**/*.svg"
      },
      "output": {
        "format": "png"
      },
      "options": {
        "sizes": [ "400x300", "1000x750" ]
      }
    }
  ]
}

Converts PNG files with 1:1 aspect ratio to ICO files:

{
  "tasks": [
    {
      "task": "convert",
      "input": {
        "files": "logo/base/my-brand-logo-@(16x16|32x32|48x48|256x256).png"
      },
      "output": {
        "format": "ico"
      }
    }
  ]
}

Optimize

optimize tasks attempt to generate optimized versions of all of the input files found. These are generally declared after all other tasks in order to avoid conflicts with other task input file patterns, however, they can be declared at any point.

The "output" configuration is entirely optional, however, the "output.dir" and "output.files" configurations can be useful to control where the optimized files are written to. By default, the optimized version of each input file is written to the same directory as that file with name derived from it (i.e. "<%= file.base(true) %>.min<%= file.extension() %>").

Formats

The following formats at supported by optimize tasks:

Input Format	Output Format
svg	Ignored

Examples

Removes all previously optimized SVG files before re-generating them:

{
  "tasks": [
    {
      "task": "clean",
      "input": {
        "files": "logo/**/*.min.svg"
      }
    },
    {
      "task": "optimize",
      "input": {
        "files": "logo/**/*.svg"
      }
    }
  ]
}

This way we can easily avoid generating optimized versions of previously optimized files.

Package

package tasks are capable of adding (and potentially converting) files in one format into a file in another format.

The "output" configuration is required, however, the "output.dir" configuration is entirely optional and output files will be written to the same directory as the original input file, by default. As for the "output.file" and "output.format" configurations; only one is required but both can be provided for ultimate control. When the "output.file" configuration is provided and the "output.format" configuration isn't, an attempt will be made to derive the latter from "output.files" by parsing the file extension. Likewise, if the "output.format" configuration is provided and the "output.file" configuration isn't, an attempt will be made to derive the latter from "output.format" and the first input file (i.e. "<%= file.base(true) %>." + outputFile.format).

All package for image output formats support the "options.sizes" configuration can be used to control the size of the images that are added to the output file. This can be used to resize a single image into multiple images of varying sizes that are added the the output file, or it can be used to resize multiple files in the same manner. If omitted, Brander will attempt to read the real sizes of the input files itself. The "options.groupBy" configuration can be useful for using a single task declaration to package files in png/svg formats to multiple files in ico format.

Formats

The following formats at supported by package tasks:

Input Format	Output Format
Any	zip
png	ico
svg	ico

Currently, package tasks that package files into ico files only support 1:1 aspect ratios correctly.

Examples

Bundles all files into a ZIP file:

{
  "tasks": [
    {
      "task": "clean",
      "input": {
        "files": "assets.zip"
      }
    },
    {
      "task": "package",
      "input": {
        "files": "**/*"
      },
      "output": {
        "dir": ".",
        "files": "assets.zip"
      }
    }
  ]
}

Creates ICO files each containing multiple PNG files:

{
  "tasks": [
    {
      "task": "package",
      "input": {
        "files": [
          "logo/**/*-16x16.png",
          "logo/**/*-32x32.png",
          "logo/**/*-64x64.png",
          "logo/**/*-128x128.png",
          "logo/**/*-256x256.png"
        ]
      },
      "output": {
        "files": "<%= file.base(true).replace(/-\\d+x\\d+$/, '') %>.ico"
      },
      "options": {
        "groupBy": "<%= file.dir %>"
      }
    }
  ]
}