Assets

Brander's ability to generate assets is built on a task-based system which can be configured in the .branderrc file. These all follow the same general schema within the configuration:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "input": {
      "type": "object",
      "properties": {
        "dir": { "type": "string" },
        "files": {
          "anyOf": [
            { "type": "string" },
            {
              "type": "array",
              "items": { "type": "string" }
            }
          ]
        },
        "format": { "type": "string" }
      },
      "required": [ "files" ]
    },
    "options": {
      "type": "object",
      "properties": {
        "groupBy": { "type": "string" },
        "sizes": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "number",
                "exclusiveMinimum": 0
              },
              {
                "type": "string",
                "pattern": "^\\s*\\d+\\s*([xX]\\s*\\d+)?\\s*$"
              }
            ]
          }
        }
      }
    },
    "output": {
      "type": "object",
      "properties": {
        "dir": { "type": "string" },
        "files": { "type": "string" },
        "format": { "type": "string" }
      },
      "anyOf": [
        { "required": [ "files" ] },
        { "required": [ "format" ] }
      ]
    },
    "task": { "type": "string" }
  },
  "required": [
    "input",
    "task"
  ]
}

The tasks are executed 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. For example, the following configuration is invalid as the "input.files" configuration contains files of mixed formats:

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

But this could easily by fixed by splitting that task up for each unique format:

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

Tasks

Tasks are split into three types: clean, convert, and optimize. 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 with relating to the configuration between these types that will be explained further in the sections below.

TODO: Cover evaluated values (file.dir, file.name, option.groupBy)

Clean

clean tasks simply force deletes 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 and optimized SVG files before doing anything else:

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

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

Convert

TODO: Describe convert tasks

Formats

The following formats at supported by convert tasks:

Input Format | Output Format -------------+-------------- png | ico svg | png

Examples

TODO

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.