npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@americanexpress/one-app-runner

v6.18.0

Published

CLI for running One App locally

Downloads

347

Readme

@americanexpress/one-app-runner

A command line interface (CLI) tool for running One App locally.

one-app-runner allows you to work locally on your Holocron Module without having to clone One App.

It works by pulling a Docker image for One App and mounting your module to it as a volume.

Note: If you are making changes to One App at the same time you are making changes to your Module(s) then you will still need to clone One App, serve your module to it, and start it yourself.

🤹‍ Usage

Note that Docker is required and must be installed before one-app-runner can be used.

Quick start

In any Holocron Module directory:

  1. Install:
npm install --save-dev @americanexpress/one-app-runner
  1. Add the one-app-runner command to your npm start script and a runner config to your module's package.json. See below for an example:
package.json
"scripts": {
  "start": "one-app-runner"
},
"one-amex": {
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
    "parrotMiddleware": "./dev.middleware.js"
  }
}

Use the runner config to tell one-app-runner what module map and One App version to use, what your root module is, where your module is (current directory in this case), and optionally where your Parrot mocks middleware file is located.

Command options reference

one-app-runner can be configured via command options or a configuration object in package.json:

docker-image [Required]

Docker image to use for One App. It allows you to specify what Docker image and tag to pull down for One App. This can be an image you have built and tagged locally but is not published to a Docker registry. Whatever value is provided is passed down to docker pull and docker run.

Sample usage:

npx @americanexpress/one-app-runner --docker-image oneamex/one-app-dev:5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex": {
  "runner": {
    "dockerImage": "oneamex/one-app-dev:5.x.x",
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json"
  }
}

module-map-url

Location of module map for One App to use to fetch modules. This option is required.

Sample usage:

npx @americanexpress/one-app-runner --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex": {
  "runner": {
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
    "rootModuleName": "frank-lloyd-root"
  }
}

root-module-name [Required]

Name of the module to use as a root module for your One App instance.

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex": {
  "runner": {
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
  }
}

modules [Optional]

This option is required if module-map-url is not provided.

Path to local module(s) to serve to One App. This can be either an absolute or a relative path to a Holocron Module's root directory. Supports serving multiple modules at the same time as well.

Sample usage:

npx @americanexpress/one-app-runner --modules ../frank-lloyd-root --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

# or to serve multiple modules
npx @americanexpress/one-app-runner --modules ../frank-lloyd-root ../cultured-frankie --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex": {
  "runner": {
    "modules": [
      ".",
      "../frank-lloyd-root"
    ],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
  }
}

parrot-middleware [Optional]

Path to parrot dev middleware file for One App to use for Parrot mocking. This option must be used in conjunction with the --module option.

For more information on setting up parrot dev middleware, check out the One App Mocking APIs recipe.

Sample usage:

npx @americanexpress/one-app-runner --parrot-middleware ../frank-lloyd-root/dev.middleware.js --module ../frank-lloyd-root --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex": {
  "runner": {
    "parrotMiddleware": "./dev.middleware.js",
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
  }
}

If middleware is defined in the package.json, you can use the --no-parrot-middleware option to temporarily disable it.

dev-endpoints [Optional]

Path to dev endpoints file for One App to use for the One App Dev Proxy set up. This option must be used in conjunction with the --module option.

For more information on setting up your dev endpoints file, check out the Configuring One App with your API URLs guide.

Sample usage:

npx @americanexpress/one-app-runner --dev-endpoints ../frank-lloyd-root/dev.endpoints.js --module ../frank-lloyd-root --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex": {
  "runner": {
    "devEndpoints": "./dev.endpoints.js",
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
  }
}

output-file [Optional]

Path to a file to which One App logs should be redirected to. Using this option will send all One App logs to given file and will result in no logs from One App being sent to your terminal.

Sample usage:

npx @americanexpress/one-app-runner --output-file ../one-app.log --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root

Or in package.json

"one-amex": {
  "runner": {
    "outputFile": "./one-app.log",
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x"
  }
}

docker-network-to-join [Optional]

Connect the One App container to a network. The value gets passed to the docker flag --network

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root --docker-network-to-join my-network

Or in package.json

"one-amex": {
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x",
    "dockerNetworkToJoin": "my-network"
  }
}

create-docker-network [Optional]

This option requires docker-network-to-join to be used as the network name.

Creates a new docker network using the network name provided.

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root --create-docker-network --docker-network-to-join my-network

Or in package.json

"one-amex": {
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x",
    "dockerNetworkToJoin": "my-network",
    "createDockerNetwork": true
  }
}

use-host [Optional]

Use req.headers.host instead of localhost for one-app-dev-cdn

Note: This flag is required when using one-app-runner for browser tests on a CI environment so the one-app-dev-cdn can be accessed by other containers running on the same network.

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root --use-host

Or in package.json

"one-amex": {
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x",
    "useHost": true
  }
}

offline [Optional]

Bypass docker pull and run an existing image already downloaded to your machine. This is useful when working offline or you are unable to access the Docker registry.

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --docker-image oneamex/one-app-dev:5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root --offline

Or in package.json

"one-amex": {
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
    "offline": true
  }
}

container-name [Optional]

Assign a container name with the --name docker option

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.0.0 --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root --container-name one-app-at-test

Or in package.json

"one-amex": {
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x",
    "containerName": "one-app-at-test"
  }
}

envVars [Optional]

Environment variables to provide to One App instance.

Sample usage:

npx @americanexpress/one-app-runner --envVars '{ "ONE_CONFIG_ENV": "production" }' --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json
// or
npx @americanexpress/one-app-runner --envVars.ONE_CONFIG_ENV=production --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex": {
  "runner": {
    "envVars": {
      "ONE_CONFIG_ENV": "production"
    },
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x"
  }
}

If none of the two is provided, one-app-dev-cdn will only use locally served modules.

NODE_EXTRA_CA_CERTS

If NODE_EXTRA_CA_CERTS is set, either through the envVars option or as an environment variable, it will be mounted and passed to the One App docker container.

use-debug [Optional]

Attaches the debugger on port 9229, the standard port for node debugging.

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root --use-debug

Or in package.json

"one-amex": {
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x",
    "useDebug": true
  }
}

log-format [Optional]

Presentation of log entries. Valid options include friendly, verbose, and machine. The default value in a development environment is friendly.

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root --log-format machine

Or in package.json

"one-amex": {
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x",
    "logFormat": "machine"
  }
}

log-level [Optional]

Lowest level of log entries to write. Valid options include error, warn, log, info, & trace. The default value in a development environment is log.

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root --log-evel info

Or in package.json

"one-amex": {
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x",
    "logLevel": "info"
  }
}

HTTP_ONE_APP_DEBUG_PORT

If HTTP_ONE_APP_DEBUG_PORT is set, it will be used as the port for the debugger. Defaults to 9229.

Proxy Support

one-app-runner respects the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables and passes them down to the One App docker container.

Make use of these environment variables if the remote module map or modules you want One App to use are inaccessible without the use of a proxy server.

Test Environment

one-app-runner-test

Creates a new instance of one-app-runner that runs in the background detached from the parent process. This option is useful to run a test suite against the running One App container.

package.json
"scripts": {
  "start": "one-app-runner",
  "start:test": "one-app-runner-test"
},
"one-amex": {
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
    "parrotMiddleware": "./dev.middleware.js"
  }
}

create-runner-env

This command generates random ports and values for the following environment variables:

HTTP_PORT
HTTP_ONE_APP_DEV_CDN_PORT
HTTP_ONE_APP_DEV_PROXY_SERVER_PORT
HTTP_ONE_APP_DEBUG_PORT
HTTP_METRICS_PORT
NETWORK_NAME

It stores them in a .env file to be shared across the test environments and one-app-runner

This command should be executed before starting one-app-runner-test