@vamship/grunt-utils

Library of modules that are designed to construct an opinionated dev/build toolchain for Javascript and Typescript projects.

This library was originally intended for internal consumption, though the functionality provided by this library is fairly generic.

API Documentation

API documentation can be found here.

Motivation

In addition to writing code (and tests!), every project brings with it a common set of tasks that comprise a development workflow for the project. This workflow includes common activities such as linting, formatting files, testing, building, packaging, etc.

Having consistent way of performing these tasks makes it easier to switch from one project to another, because all common tasks will be identical for a given class of project (nodejs library, API server, etc.).

In order to ensure this consistency, a common task automation framework (Gulp) is used, combined with a consistent configuration and development tool set for that framework.

This library exports modules and classes that enable the creation of Gulpfiles, ensuring that they can be ported from project to project with no changes.

All project specific parameters can be declared within a buildMetdata property in package.json.

Installation

This library can be installed using npm:

npm install @vamship/build-utils

Usage

This library is intended to be used with a Gulpfile that imports the necessary tasks for the build system. The examples directory has a sample Gulpfile that can be used for any project.

Environment Variables

Setting certain environment variables can alter the behavior of different build tasks. The environment variables and their effects are listed below:

BUILD_EXPORT_DOCKER_IMAGE: When set to true, packaging a docker enabled project will result in the creation of a tar file called image-<key>.tar (using docker save ...) under the dist directory.

BUILD_DOCKER_REPO: This environment variable can be used to override the docker repository name during package/publish operations.

Configuring package.json

The build system derives its configuration from buildMetadata that is explicitly passed to the the project object via the Gulpfile, or by configuring settings in the package.json file. We strongly recommend the use of package.json to configure the build system.

Build metadata is identified in package.json via a property named buildMetadata, which is an object that supports the following fields:

{
  "projectType": "lib|cli|api|aws-microservice|container",
  "language": "ts|js",
  "requiredEnv": [ "...", "..." ],
  "aws": {
    "stacks" {
      "stack-key": "stack-name",
      ...
    }
  },
  "docker": {
    "x86": {
      "repo": "...",
      "buildFile": "Dockerfile"
      "buildArgs": {
        "arg-name": "__ENV__|<value>"
      },
      "isDefault": true,
    },
    "arm64": {
      "repo": "...",
      "buildFile": "Dockerfile.arm64"
      "buildArgs": {
        "arg-name": "__ENV__|<value>"
      }
    }
  }
}

Note that all properties are not required for all types of projects. Refer to the package.json files in the examples directory to get an idea of typical configuration for different project types.

Upgrading to v0.3x

Starting from version 0.3, the docker build configuration supports multiple targets, meaning that the application may be used to generate different docker images, typically intended for different processor architectures. While the changes are backwards compatible with 0.2.x, a deprecation warning will be posted if the old style configuration is specified.

In order to upgrade to v 0.3 and above, the docker section should be updated from

  "docker": {
    "repo": "...",
    "registry": "Dockerfile"
    "buildArgs": {
      "arg-name": "__ENV__|<value>"
    },
  }

to:

  "docker": {
    "default": {
      "repo": "...",
      "buildFile": "Dockerfile"
      "buildArgs": {
        "arg-name": "__ENV__|<value>"
      }
    }
  }

The basic change is that the build configuration is specified as the value of a build target key.

Note that the docker.registry parameter is no longer supported in the new configuration format.

Properties:

projectType: Identifies the project type, which in turn determines the build tasks generated by the system.

language: The project language - javascript or typescript.

requiredEnv: A list of environment variables that must be defined prior to some tasks, such as publishing AWS projects, packaging docker images, publishing private npm repositories, etc. The build system only checks for the existinence of these variables, but does not care about their values.

aws: This object must be specified for aws microservice projects. aws.stacks: This sub object defines a list of cloud formation stacks published by the project. The keys represent the names that will be used for the gulp tasks, and the values are the names of the cloud formation stacks.

docker: This object must be sepcified for projects that result in docker images. This could apply to multiple project types including cli, api and container. The docker configuration can specify multiple targets with different docker files and build arguments. Each target has a name and a corresponding set of configuration options. The name of the target can be any string, except that a target named "default" is treated as the default packaging target.

Each target can have the following properties:

[target].repo: A fully qualified repo name to be used to publish docker images. [target].buildFile: The name of the docker file to use for the build. If omitted, will default to "Dockerfile" [target].buildArgs: This is a map of build arguments that will be passed to docker at build time. The keys are the build argument names, and the values are the argument values. A special value __ENV__ indicates that the actual value of the build argument must be extracted from the environment.