@megabytelabs/buildr

Buildr - The Web App Meta Generator

A collection of tools used to generate the optional meta-type stuff that many web apps forget to implement. It allows you to:

• Translate JSON files to any given language using Google Translate
• Take screenshots of websites
• Sort JSON files alphabetically using jsonabc
• Generate favicons and app icons using RealFaviconGenerator's node package

Buildr allows you to pass in configurations through a JSON file and generates various files useful for web apps that do not want to miss any of the smaller parts that make a web app great. It is highly configurable without being overly complicated. You can use Buildr by generating a configuration file and using the CLI (configuration samples below) or you can interface with it using NodeJS (see the API Documentation).

Transform This

Into This

Requirements for the CLI

1. NodeJS 8.9 or higher
2. A configuration file and seed assets (detailed below)

Getting Started

1. Install Buildr by running npm install --save-dev @woogie/buildr
2. Create a configuration file using the instructions below
3. Run buildr --config ./buildr.json or replace buildr.json with whatever you named the configuration file

Configuration Examples

Take Screenshots

Buildr can take screenshots of your website or any website if you pass it a URL, the location where you want to store the screenshot, and the height/width of the screenshot. It uses puppeteer to handle this.

Configuration (buildr.json)

{
  "screenshots": [
    {
      "file": "/assets/images/screenshots/app-screenshot-1.png",
      "url": "https://videoblobs.com/welcome",
      "options": {
        "height": 1200,
        "width": 1200
      }
    }
  ]
}

Translate JSON Files

Multiple folder structures are supported. Buildr will scan files and only insert missing translations so your previous work is saved. Buildr will create missing files and populate them with the proper translations.

This method requires you to set an environment variable that specifies the location of your Google Cloud Platform service account key. You also have to enable the Cloud Translation API in Google Cloud Platform. Depending on how many translations you need, you may have to increase the translation quotas as well. By default, the Cloud Translation API has some low per minute limits. You can also just run the Buildr script every couple minutes to get around this limitation.

If you can not set an environment variable, Buildr also supports using a .env file. To use this technique, add the file to a parent directory and include the environment variable which should be named GOOGLE_APPLICATION_CREDENTIALS. If you use this method, you should end up with the .env file in a parent directory with the contents of the file looking something like this:

GOOGLE_APPLICATION_CREDENTIALS=/Users/Gracie/google-service-account-key.json

Method 1 - Single JSON File as Source**

In this scenario, you pass Buildr a source file and specify the languages you want the file translated to. The configuration below will scan en.json and then populate ./examples/i18n/fr.json and ./examples/i18n/es.json with translations retrieved from Google Translate.

Configuration (buildr.json)

{
  "translations": {
    "languages": ["fr", "es"],          // Languages you wish to translate to
    "projectId": "video-blobs",         // Your Google Translate project ID
    "source": ["./examples/i18n/en.json"] // Your i18n seed file(s)
  }
}

Method 2 - Directories with Multiple i18n Files**

Buildr can also handle directories with multiple JSON i18n files in them. The configuration below will scan all the files in ./examples/i18n/en. Then, if in that directory there are two files called homepage.json and list.json, then ./examples/i18n/fr/homepage.json, ./examples/i18n/es/homepage.json, ./examples/i18n/fr/list.json, and ./examples/i18n/es/list.json will be created and populated with translations derived from the source directory.

Configuration (buildr.json)

{
  "translations": {
    "languages": ["fr", "es"],
    "projectId": "video-blobs",
    "source": ["./examples/i18n/en"]
  }
}

You can combine multiple sources together by adding more items to the source array:

Configuration (buildr.json)

{
  "translations": {
    "languages": ["fr", "es"],
    "projectId": "video-blobs",
    "source": ["./examples/i18n/en.json", "./examples/i18n/en"]
  }
}

Sort JSON Files Alphabetically

You can sort JSON files alphabetically by passing in an array of JSON files you would like sorted.

Configuration (buildr.json)

{
  "jsonSort": ["./examples/json/sort-me.json", "./examples/json/sort-me-also.json"]
}

Browser Generated Images

If you would like to use the browser to generate image assets, you can do that. You might ask, "Why would I want to do that?" Say you have an SVG and you want to add a background color and some text below the SVG, you can load that SVG in an HTML document that applies your styling. This feature will automate the process of taking your HTML template and source asset and converting it into your desired asset. You can use this feature with a configuration that could look something like this:

{
  "images": [
    {
      "file": "/assets/icons/android-chrome-48x48.png",
      "template": "android-chrome.png.html.handlebars",
      "options": {
        "src": "/assets/images/logos/icon-color.svg",
        "height": 48,
        "width": 48,
        "compressOver": true,
        "webp": false
      }
    }
  ]
}

### Resize Images

If you need to create icons of various sizes, you can configure Buildr to resize the images for you with a configuration that might look like this:

{ "sharp": [ { "input": "/assets/images/logos/icon-color.svg", "file": "/assets/icons/favicon-48x48.png", "options": { "height": 48 } }, { "input": "../../../misc/videoblobs/logos/logo-color.svg", "file": "/assets/images/logos/videoblobs-sm.png", "options": { "height": 30 } } ] }

The snippet above would create two different resized PNG files from two different SVG input files.

### Generate Favicons

Using [RealFaviconGenerator](https://realfavicongenerator.net/), Buildr generates many of the icons necessary
to make your app icon look perfect across all devices. For this part, Buildr simply lets you pass a configuration
that you can generate on their website. You can generate the configuration by using their web app and then click
Node CLI at the end of the process.

**Configuration (buildr.json)**

{ "faviconGenerator": { "masterPicture": "TODO: Path to your master picture", "iconsPath": "/", "design": { "ios": { "pictureAspect": "noChange", "assets": { "ios6AndPriorIcons": false, "ios7AndLaterIcons": false, "precomposedIcons": false, "declareOnlyDefaultIcon": true } }, "desktopBrowser": { "design": "raw" }, "windows": { "pictureAspect": "noChange", "backgroundColor": "#da532c", "onConflict": "override", "assets": { "windows80Ie10Tile": false, "windows10Ie11EdgeTiles": { "small": false, "medium": true, "big": false, "rectangle": false } } }, "androidChrome": { "pictureAspect": "noChange", "themeColor": "#ffffff", "manifest": { "display": "standalone", "orientation": "notSet", "onConflict": "override", "declared": true }, "assets": { "legacyIcon": false, "lowResolutionIcons": false } } }, "settings": { "scalingAlgorithm": "Mitchell", "errorOnImageTooSmall": false, "readmeFile": false, "htmlCodeFile": false, "usePathAsIs": false } } }