README

Pack

Code packing utilities

Install: @travetto/pack

npm install @travetto/pack

CLI - pack

Terminal: Pack usage

$ trv pack --help

Usage:  pack [options] [mode]

Options:
  -w, --workspace <workspace>  Working directory
  -h, --help                   display help for command

Available Pack Modes:
  * default [support/pack.config.ts]
  * rest/aws-lambda [@travetto/rest/support/pack.aws-lambda.ts]
  * rest/docker [@travetto/rest/support/pack.docker.ts]

This command line operation will compile your project, and produce a ready to use workspace as a deliverable. The pack operation is actually a wrapper around multiple sub-operations that are run in series to produce the desired final structure for deployment. The currently support operations are:

assemble
zip
docker

CLI - pack:assemble

Assemble is the operation that stages the project's code for deployment. The assembly process goes through the following operations:

Cleaning Workspace - Cleans workspace to start with an empty workspace
Copying Dependencies - Computes the prod depedencies and copies them into the new workspace
Copying App Content - Copies over application content (src/resources/support/bin)
Excluding Pre-Compile Files - Any files that should be excluded pre-compilation, are removed
Compiling - Compiles the code in the new workspace, isolating it from your local development
Excluding Post-Compile Files - Removes any files that should be excluded, post compilation
Copying Added Content - Adds in any additional content that is not in the standard locations
Removing Empty Folders - Purge all empty folders, recursively
Writng Env.js - Write out the .env.js file with computed any env vars that should be set for the deployed app
Remove Source Maps - If keep source is false, all source maps are purged from your app's code
Emptying .ts Files - If keep source is false, all .ts files are emptied, as compilation will not occur at runtime

Code: Assemble Default Config

assemble: {
    active: true,
    cacheDir: 'cache',
    keepSource: true,
    readonly: true,
    env: {
      TRV_DYNAMIC: '0'
    },
    add: [
      { [mod('@travetto/cli/bin/trv.js')]: mod('.bin/trv') },
      { [mod('lodash/lodash.min.js')]: mod('lodash/lodash.js') },
    ],
    excludeCompile: [
      mod('@travetto/*/doc/'),
      mod('@travetto/*/e2e/'),
      mod('@travetto/*/test/'),
    ],
    exclude: [
      'bower.json',
      'LICENSE',
      'LICENCE',
      '*.map',
      '*.md',
      '*.lock',
      '*.html',
      '*.mjs',
      mod('**/*.ts'),
      '*.d.ts',

Terminal: Assemble Usage

$ trv pack:assemble --help

Usage:  pack:assemble [options] [mode]

Options:
  -w, --workspace <workspace>  Working directory
  -k, --keep-source            Should source be preserved
  -r, --readonly               Build a readonly deployable
  -h, --help                   display help for command

Available Pack Modes:
  * default [support/pack.config.ts]
  * rest/aws-lambda [@travetto/rest/support/pack.aws-lambda.ts]
  * rest/docker [@travetto/rest/support/pack.docker.ts]

CLI - pack:zip

Zip is an optional step, that can run post assembly. The only configuration it currently provides is the ability to specify the output location for the zip file.

Code: Zip Default Config

zip: {
    active: false,
    output: 'output.zip'
  },

Terminal: Zip Usage

$ trv pack:zip --help

Usage:  pack:zip [options] [mode]

Options:
  -w, --workspace <workspace>  Working directory
  -o, --output <output>        Output File
  -h, --help                   display help for command

Available Pack Modes:
  * default [support/pack.config.ts]
  * rest/aws-lambda [@travetto/rest/support/pack.aws-lambda.ts]
  * rest/docker [@travetto/rest/support/pack.docker.ts]

CLI - pack:docker

Docker support is an optional step, that can run post assembly. This allows for building a docker image, and currently only supports the base images as the only configuration options.

Code: Docker Default Config

docker: {
    active: false,
    image: 'node:16-alpine'
  }

Terminal: Docker Usage

$ trv pack:docker --help

Usage:  pack:docker [options] [mode]

Options:
  -w, --workspace <workspace>  Working directory
  -i, --image <image>          Docker Image to extend
  -n, --name <name>            Image Name
  -t, --tag <tag>              Image Tag (default: [])
  -p, --port <port>            Image Port (default: [])
  -x, --push                   Push Tags
  -r, --registry <registry>    Registry
  -h, --help                   display help for command

Available Pack Modes:
  * default [support/pack.config.ts]
  * rest/aws-lambda [@travetto/rest/support/pack.aws-lambda.ts]
  * rest/docker [@travetto/rest/support/pack.docker.ts]

Modes

Various modules may provide customizations to the default pack.config.ts to allow for easy integration with the packing process. A simple example of this is via the RESTful API module, for how to publish lambda packages.

Code: Rest, pack.lambda.ts

import * as fs from 'fs';

import { PathUtil } from '@travetto/boot';
import type { AllConfigPartial } from '@travetto/pack';

export const config: AllConfigPartial = {
  name: 'rest/aws-lambda',
  assemble: {
    active: true,
    keepSource: false,
    exclude: [
      'node_modules/node-forge'
    ],
    env: {
      NO_COLOR: '1'
    },
    postProcess: [{
      ['Lambda Entrypoint']: cfg =>
        fs.promises.copyFile(
          PathUtil.resolveUnix(__dirname, 'aws-lambda.handler.js'),
          PathUtil.resolveUnix(cfg.workspace, 'index.js')
        )
    }],
  },
  zip: {
    active: true,
    output: 'dist/lambda.zip'
  }
};

Terminal: Invoking Pack with Mode

npx trv pack <mode>

Configuration

By default, the configuration consists of two components.

The default config in support/pack.config.ts and
The config selected to execute from the cli

These two configurations will be loaded and layered, with the selected config taking precedence.

Code: Example pack.config.ts

import type { AllConfigPartial } from '@travetto/pack';

export const config: AllConfigPartial = {
  workspace: 'dist/alt',
  assemble: {
    active: true,
    add: [
      { assets: 'assets' },
      { '/secret/location/key.pem': 'resources/key.pem' }
    ]
  },
  zip: {
    active: true,
    output: 'dist/build.zip'
  }
};

Environment Override

When working with sub operations, passing command-line flags is challenging. To support a more natural usage, the sub operations allow their key parameters to be overridden via environment variables.

Code: Assemble Overrides

overrides: {
    keepSource: CliUtil.toBool(process.env.PACK_ASSEMBLE_KEEP_SOURCE),
    readonly: CliUtil.toBool(process.env.PACK_ASSEMBLE_READONLY)
  },

Code: Docker Overrides

overrides: {
    image: process.env.PACK_DOCKER_IMAGE || undefined,
    name: process.env.PACK_DOCKER_NAME || undefined,
    app: process.env.PACK_DOCKER_APP || undefined,
    port: process.env.PACK_DOCKER_PORT ? [process.env.PACK_DOCKER_PORT] : undefined,
    registry: process.env.PACK_DOCKER_REGISTRY || undefined,
    push: CliUtil.toBool(process.env.PACK_DOCKER_PUSH),
    tag: process.env.PACK_DOCKER_TAG ? [process.env.PACK_DOCKER_TAG] : undefined
  },

Code: Zip Overrides

overrides: {
    output: process.env.PACK_ZIP_OUTPUT || undefined
  },

Usage no npm install needed!