asset-builder-core

Used in asset-builder and dredition-cli to build general browser assets in a common manner. Initially created for LP/PA, and gradually being used elsewhere as well.

Usage

The library exports a single function which takes a path on disk, an asset revision string, and a config object. Commonly, the revision string is set to the current git hash. The config object will default to the assetBuilderConfig-value in config.json, if it exists.

const build = require('@aptoma/asset-builder-core');
const assets = await build(process.cwd(), 'foo', config);

The build function expects the path argument to point to a folder with the following structure:

├── config.json
├── files
│   ├── bar.xml
├── snippets
│   ├── snip-1.html
│   └── snip-2.html
├── static
│   ├── OpenSans-Regular.ttf
├── stylesheets
│   ├── _fonts.scss
│   ├── _include.scss
│   └── styles.scss
└── templates
    ├── tmpl-1.html
    ├── tmpl-2.html

These files and folders are handled in the following manner:

• config.json
  • Validated to be proper JSON and included as-is.
• stylesheets/*
  • All root-level files that do not start with underscores are treated as entrypoints and are rendered with SASS. Include-files may be provided in subdirectories.
• snippets/**/* and templates/**/*
  • Collected as strings, ran through a HTML minifier/sanitizer, and included in snippets.json and templates.json, respectively. These JSON files each contain an object with filenames as keys and file contents as strings.
• static/**/* and files/**/*
  • Collected as-is, and included in the output as static and files, respectively, with file names as keys and file contents as Buffers.

Here's an abridged example of what this library will output after a build:

{
  stylesheets: {
    'styles.css': '*{font-size:16px}'
  },
  files: {
    'bar.xml': <Buffer>
  },
  static: {
    'OpenSans-Regular.ttf': <Buffer>
  },
  'templates.json': {
    'tmpl-1.html': '<div id="1"></div>\n',
    'tmpl-2.html': '<div id="2"></div>\n'
  },
  'snippets.json': {
    'snip-1.html': '<div id="1"></div>\n',
    'snip-2.html': '<div id="2"></div>\n'
  },
  'config.json': {
    assetBuilderConfig: {
      skipLocalFonts: false
    }
  }
}

When assets are built in the asset-builder service, these files are uploaded to ASS, and are available in the API. The structure of the response is the same as the above example, except each key contains an ASS-URL instead of the actual file content.

The URLs utilize the revision-parameter as part of the URL, for all output files except those placed in static/.

Configuration

You can pass configuration to the build either via the config-parameter to build, or via setting values in the assetBuilderConfig-object in config.json.

• skipLocalFonts
  • By default, @font-face-declarations will be post-processed to contain several local()-clauses, in an attempt to maximise the likelihood of using a locally cached font. If this is not desirable, you can set this value to true.