@platform/npm.express

Express middleware for working with NPM.

Continuous deployment via NPM.
Run as middleware or use Docker container directly (recommended).

Example

Run the example directly in node:

yarn example

or run the example within docker:

yarn dbuild
cd examples
docker-compose up

see the /examples/docker-compose.yml file for example configuration and command-line arguments to pass to the container.

Middleware

To use the express middleware directly

import * as express from 'express';
import { router } from '@platform/npm.express';

const getContext = async () => {
  return {
    name: 'my-module',                // Name of the NPM module being managed.
    downloadDir: '/download/folder',  // Directory where latest NPM version is downloaded to.
  };
};

const routes = router.create({ getContext });
const server = express().use(routes);
server.listen(1234);

Routes

GET   /status
POST  /update
POST  /start
POST  /stop

Query-string parameters for /status:

{
  versions?=<number>    // Include version history. If number (n) provided returns only the latest (n) versions.
  size?=<boolean>       // Include size of the download folder.
}

Body parameters for /update:

{ 
  restart?: boolean;                        // Restart the service once updated (default: true)
  version?: string | 'latest';              // Specific version to install (default: 'latest')
  prerelease?: boolean | 'alpha' | 'beta',  // Install pre-release version, eg 1.2.0-beta.0 (default: false)
  reset?: boolean,                          // Delete existing download before installing (default: false)
  dryRun?: boolean,                         // Perform all checks, but don't actually change anything.
}

Body parameters for /start:

{ restart?: boolean }

Command-Line Arguments

To configure the module when working with it as Docker container pass the following command-line arguments:

    --npm-module='<string>'             # (required) The name of the NPM module being managed.
    --dir='<string>'                    # (required) Path to the download directory.
    --port='<number>'                   # (optional) Port to run the management server on.
    --prerelease='<boolean|alpha|beta>' # (optional) Whether pre-release versions should be used (default:false).
    --url-prefix='<string>'             # (optional) Prefix to prepend URL's with, eg /foo => GET /foo/status
    --update                            # (optional) Flag indicating if update performed at startup (default:false).
    --npm-token                         # (optional) An NPM authorization token if working with private modules.

see the /examples/docker-compose.yml file for example configuration.

.env

These same arguments can alternatively be specified as environment variables, see /example/env/main.env and the env_file reference in docker-compose.yml for example.

NPM_MODULE=           --npm-module
NPM_DIR=              --dir
NPM_PORT=             --port
NPM_PRERELEASE=       --prerelease
NPM_URL_PREFIX=       --url-prefix
NPM_UPDATE=           --update
NPM_TOKEN=            --npm-token

Any values passed explicitly to the command will override the environment variables.

Private NPM Packages

Follow the instructions on NPM "Using private packages in a CI/CD workflow" to create a token to access your private modules:

npm token create --read-only

Alternatively tokens can be created within the npmjs.com adminitration UI.
Pass the token as either a command-line argument or an environment variable at startup.