Publish various front-end assets to AWS S3 before exposing them via CDN.

Usage

Expected to be used during build step of any Targetprocess service providing UI assets - JavaScript, CSS, images, fonts, etc.

Example Gitlab pipeline configuration (note that it implies configured AWS keys and secrets, please refer to Configuration section for details):

publish:
  stage: publish
  image: node:13.3-alpine
  # Run only when commit is explicitly tagged
  only:
    - tags
  variables:
    ASSETS_DIR: out
    SERVICE_NAME: your-service-name
    # Use commit tag as a published version
    SERVICE_VERSION: ${CI_COMMIT_TAG}
  script:
    - npx -p @targetprocess/publish-frontend-assets -c publish-frontend-assets

Configuration

Please refer to src/config.ts for the most recent actual list of configuration variables.

AWS_S3_ACCESS_KEY_ID and AWS_S3_ACCESS_KEY_SECRET

Required. AWS S3 credentials to upload assets. When package is used via Gitlab pipeline, it's recommended to set them as Runner Variables in your project configuration.

AWS_S3_BUCKET_NAME

Required. Name of AWS S3 bucket where assets should be uploaded to. It's expected that all UI services upload their assets to one single bucket (set as default value), but their assets are nested by %service_name%/%version% pattern.

SERVICE_NAME

Required. Name of your service, which will become a part of upload key for S3. Use simple but descriptive names with kebab-case, e.g. search-ui, rule-engine-ui, targetprocess-frontend.

SERVICE_VERSION

Required. Unique version describing this specific upload. Will become a part of upload key for S3. For example, 0.0.1, 0.0.1-rc.2.

ASSETS_DIR

Required. Path to the directory where assets which should be uploaded are located. Path is expected to be relative to the current working directory.

AWS_S3_CACHE_CONTROL

Optional. Cache-Control header which should be set for uploaded assets.

By default it is set to 1 year: public, max-age=31557600. Note the usage of public. Setting Cache-Control to private would not allow Cloudflare CDN to cache the asset.

AWS_S3_TAG

Optional. Allows to set object tags for uploaded assets.

By default sets TTL tag, which is later used by our custom S3 policies to automatically expire files.

MAX_NUMBER_OF_ASSET_FILES and MAX_TOTAL_ASSET_SIZE

Optional. To prevent accidental huge uploads due to misconfiguration (for example preventing upload of entire node_modules), this package enforces low limit of the total amount of assets and their total size (in bytes).

You can use these values to override defaults.

Dev notes

Because this package is run via npx, there's a dummy file bin/publish-frontend-assets with explicit hashbang header, which calls dist/app.js, which is build from src/app.ts.

Package version is automatically set via npm version from the current commit tag during pipeline build, so version in package.json is set to 0.0.0 in source code.

When running locally, use .env file to set AWS credentials and other env variables. Do not commit that file.