delivr

Build your code and ship it to S3

This is a multi-version release and deployment system, optimized for client-side web applications.

Your builds are stored locally during development and automatically uploaded to Amazon S3 in CI. Your git branch is used to namespace each build and versioning is handled gracefully, with immutable, meaningful version numbers derived from package.json and your git repository state.

All branches are treated equally, all versions are kept around, and symlinks for the latest build of a given branch are provided. This makes both development and release extremely simple. Your app server can release a build simply by deciding which branch it wants to point to. And it can either use the latest build of that branch or a specific version. Because builds are immutable, they are cached for long periods of time, and rollbacks are easy.

Why?

• No more complicated, untested, handwritten release scripts!
• Smart versioning that works well across environments.
• Composable with other build tools.
• Easy to set up and configure.

Install

npm install delivr --save

Usage

First, delivr.prepare() makes a secure temporary directory for you to put some files in. When you are done, just call build.finalize() and the directory will be moved to build/<branch>/<version> and (if in CI) deployed to S3.

const fs = require('fs');
const util = require('util');
const delivr = require('delivr');

const writeFile = util.promisify(fs.writeFile);

const run = async () => {
    // Make a temporary directory to put files in!
    const build = await delivr.prepare();

    // Write some files to disk!
    await writeFile(path.join(build.path, 'hello.txt'), 'Hello, world!');

    // Deploy the build!
    await build.finalize();
};
run();

API

Please see Amazon's API documentation for details on authenticating with AWS.

build = await delivr.prepare(option)

Returns an object representing a newly created temporary directory.

You should write files to be included in the build by putting them inside build.path. When you are done writing files, you should call build.finalize().

option

Type: object

Settings and known build data.

cwd

Type: string
Default: process.cwd()

Parent directory of the build root. Typically, this would be the root directory of your app.

branch

Type: string
Default: git HEAD or master

A prefix used to group builds together, so that "release lines" can more easily be maintained.

The branch becomes part of the path used to store the build when the build is finalized. For example, if the branch is my-feature and the version is 1.0.0, the build will be stored in build/my-feature/1.0.0.

You probably don't need to set this option yourself! Providing a custom branch name is mostly useful to improve performance, if you happen to know the current branch name ahead of time.

version

Type: string
Default: a new build version

A version identifier used to separate this build from others on the same branch. Ideally, it should be unique, such that only builds with the same content ever have the same version (the default algorithm guarantees this).

The version becomes part of the path used to store the build when the build is finalized. For example, if the branch is master and the version is 1.2.3, the build will be stored in build/master/1.2.3.

You probably don't need to set this option yourself! Providing a custom version is mostly useful to improve performance, if you happen to have a version number you want to use ahead of time.

bucket

Type: string
Example: my-app

Name of the Amazon S3 bucket where the build files should be deployed to (if deploy is enabled).

For tips on naming your bucket, see Amazon's Rules for Bucket Naming.

deploy

Type: boolean
Default: true if running in CI

Whether to upload the build files to Amazon S3.

The path of the build on S3 will be identical to your local build. For example, if the bucket is my-app and branch is master and the version is 1.0.0, the build will be available at https://s3.amazonaws.com/my-app/master/1.0.0.

build.path

A newly created and secure temporary directory for you to write files in to be included with the build.

Example on macOS: /var/folders/gr/qfsxs2gj0fq1ypdsfd8rj8tr0000gn/T/vwjBJb

await build.finalize()

Moves the temporary directory from buiild.path to build/<version>/<branch> within the current working directory, where <version> and <branch> are decided by the version and branch options given to delivr.prepare(option).

This also sets up symlinks to the build via latest-build and build/<branch>/latest (see also buildDir.link()).

Finally, the build is uploaded to Amazon S3, based on the deploy option given to delivr.prepare(option).

Related

• scube - Manage your S3 buckets
• build-files - Read the files from your build
• build-keys - Get the paths of files from your build
• build-dir - Get a place to put your build
• build-data - Get metadata for your build
• build-path - Get a path for the given build
• build-version - Get a version for your build
• branch-name - Get the current branch name

Contributing

See our contributing guidelines for more details.

1. Fork it.
2. Make a feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request.

License

MPL-2.0 © Seth Holladay

Go make something, dang it.