Local Setup

Prerequisites

Node

12 — nvm use 12

npm registry

GitHub Packages access for @payability/*

Chrome

Required by the Karma test runner

npm registry authentication

@payability/pyb-ng2-api and @payability/pyb-ngx-components are published to GitHub Packages. Create a personal access token with repo, write:packages and read:packages, then add to ~/.npmrc:

//npm.pkg.github.com/:_authToken=YOUR_TOKEN
@payability:registry=https://npm.pkg.github.com/

This goes in your home .npmrc, not the repository’s. npm install fails with a 401 on the @payability scope without it.

Install

$ nvm use {node-version}
$ npm ci

npm ci is preferred over npm install — it honours package-lock.json exactly. A postinstall hook installs the Husky git hooks.

Environment generation

src/environments/environment.ts and proxy.json are generated. Nothing runs until you generate them.

$ export ENV_NAME=dev-1
$ npm run pre-build:proxy

ENV_NAME names the backend environment; dev-[1..10] and pnega (the default) are the usual values. ENV_TYPE selects the domain and config profile:

dev (default)

<ENV_NAME>.dev.payability.com, using the dynamic profile.

prod

The prod profile against api.payability.com.

localhost

The relative profile with relative API paths against http://localhost:3000.

What pre-build does

config/pre-build.js renders two templates with EJS:

config/environment.template

→ src/environments/environment.ts

config/proxy.template.json

→ proxy.json (only with pre-build:proxy)

It also:

  • stamps version from package.json and buildTime from new Date(),

  • computes gci as the first six digits of the SHA-1 of ENV_NAME,

  • sets isProduction when ENV_NAME is prod or staging,

  • derives authTokenKey as auth-<env>-supplier4 (dev/localhost) or auth-supplier4-<timestamp hex> (prod).

Proxy mode swaps the config profile
if (proxy) {
    await prepareProxy(environmentName, config);
    await prepareEnvironmentConfig(environmentName, configs.relative);   (1)
} else {
    await prepareEnvironmentConfig(environmentName, config);
}
1 With --HAS_PROXY, the relative profile is written even though the proxy targets the named environment. The app then makes same-origin requests that the dev-server proxy forwards — which is what avoids CORS locally.

Never edit src/environments/environment.ts. It is generated by config/pre-build.js from config/environment.template and overwritten on every build. A new setting has to be added in four places: config/environment.template, every profile in config/config.js (prod, dynamic, relative), EnvironmentService, and then regenerated with npm run pre-build:proxy.

Run

$ npm start

Serves on http://localhost:4200 with --proxy-config proxy.json.

Other run targets:

npm run start:host

Exposes the server on the network (--host --disable-host-check).

npm run start:qa-test-1

Uses the checked-in proxy/proxy.qa-test-1.conf.json.

npm run start:test2

Uses proxy/proxy.test2.conf.json.

Makefile shortcuts

Makefile wraps the npm scripts and threads ENV_NAME / ENV_TYPE through.

$ make help                    # list targets and the current ENV_NAME / ENV_TYPE
$ make install
$ make prebuild                # generate environment.ts + proxy.json
$ make start                   # prebuild, then serve
$ make start ENV_NAME=dev-1
$ make dev-host                # serve on the network
$ make dev-direct              # bake the absolute API URL in, no proxy
$ make build-prod
$ make lint / lint-fix / format
$ make test / test-ci / e2e
$ make i18n                    # extract translation keys
$ make clean                   # rm -rf dist

Defaults are ENV_NAME=pnega, ENV_TYPE=dev.

Proxy routes

config/proxy.template.json forwards:

/bin

config.origin

/v1

config.origin, rewriting /v1 → ``

/actionstools

config.frontendActionsToolsApiUrl

/marketplace-web-api

config.marketplaceUrl

/b2btaskmanager-sd

config.frontendTaskManager

/b2bdocument

config.b2bDocumentUrl

All with secure: false and changeOrigin: true.

Memory settings

Every Angular CLI script in package.json runs Node with --max_old_space_size=4096. The Angular 12 build runs out of heap without it. Do not drop the flag when editing a script, and add it to any new script that invokes the CLI.

Local limitations

Amazon reconnect

AmazonConnectorCookieService writes cookies on .payability.com, so the return-detection path cannot be exercised on localhost.

Segment

loadOnInitialization is false outside production — track() calls do not reach Segment. Verify via the EventLoggerService console log.

Service worker

Registered only when environment.production is true.

storeFreeze

Active outside production, so mutations throw locally that would pass silently in prod. This is intended.

Dev-only permissions

NEW_EGG_PROVIDER is granted locally and logged to the console, but absent in production.

PayShield

The PayPal client id and plan ids are hardcoded, so a local checkout hits the real PayPal plans.

Working against local libraries

To develop @payability/pyb-ng2-api or @payability/pyb-ngx-components alongside the app, use npm link from the library directory and then link it into this repository.