@haatlabs-core/cli
haatlabs: writes a project's managed files from @haatlabs-core/templates, and makes new
projects.
Install
pnpm add @haatlabs-core/cli --save-dev
or, to make a new app: npx @haatlabs-core/cli create <name> --domain <domain>.
In a project
Each project has @haatlabs-core/cli as a devDependency, at its platform version, and a
platform.json that says what the templates need to know (name, domain, port series, apps,
CSP lists, memory limits, shared services, and the paths it keeps as its own in
unmanaged).
make sync # pnpm exec haatlabs sync
make sync-check # pnpm exec haatlabs sync --check
syncwrites every managed file and records what it wrote in.platform/managed.json. It refuses to overwrite a file edited since, naming it, and writes nothing then: change the template in the platform, or list the path inunmanaged.--forceoverwrites. It removes a file the templates no longer produce.sync --checkfails when a managed file differs from what the templates would write.pnpm-workspace.yamlis managed only between# platform:beginand# platform:end; the project's own lines go after the block.- After moving to a new platform version by hand:
pnpm install, thenmake sync. The upgrade pull requests the platform's release opens have done both.
memory in platform.json
The stack's container limits and the Node processes' memory and concurrency, all optional except as defaulted. A small host might say:
"memory": { "api": "320m", "redis": "48m", "redisMaxMemory": "32mb", "nodeHeapMb": 128, "workerConcurrency": 2 }
api(default512m) andredis(default256m): the containers' memory limits.workerMemory(default1g) is the worker's.redisMaxMemory(default128mb): Redis's own maxmemory, which must be below the redis limit (the copy Redis makes of itself while it rewrites its file needs the room). The schema only refuses a value at or above the limit; leaving real headroom for that copy is the project's job.nodeHeapMb: a Node heap cap (--max-old-space-size) for the api and the worker, so Node throws before Docker kills the container. It must be below the api limit andworkerMemory. Unset, Node keeps its own default.workerConcurrency: the worker'sWORKER_CONCURRENCY, which wins over the env file's.
Without memory, nothing changes. A refused value fails sync with the field named.
memory.cache
"memory": { …, "cache": {} }
A Redis of the environment's own for caches (maxMemory 8mb in a limit of 16m by
default): allkeys-lru, nothing on disk, never the queues' Redis. The api and worker get
CACHE_REDIS_URL=redis://cache:6379. maxMemory must be below limit.
The name
Lowercase letters and digits, single hyphens between them, starting with a letter, 2 to 31
characters (haatlabs-api). Postgres identifiers, Prometheus metrics and variable names take
it with underscores (nameSnake: haatlabs_api, HAATLABS_API_…); everything else keeps the
hyphen.
A new project
npx @haatlabs-core/cli create <name> --domain <domain> [--kind shopify|web] \
[--infra standalone|haatlabs] [--port-series <1-9>] [--into <directory>] [--no-install] [--no-git]
--kind shopify(the default): the api, worker, dashboard, the embedded Shopify app, the administrators' dashboard, billing and plans.--kind web: the same without Shopify (email sign-in, organizations, Stripe and Razorpay plans).--infra standalone(the default): the app brings its own Postgres, Redis and Caddy (HTTPS) and deploys to any Debian or Ubuntu server; it owns every file,LICENSEandNOTICE(Apache-2.0) included, and needs no token.--infra haatlabs: one of our own apps, on Haatlabs' hosts, with the managed fileshaatlabs synckeeps in step; it prints what to add to the edge, the database and GitHub.
--port-series (required with --infra haatlabs; 1 for a standalone app) picks the ports:
<series>X00 for the api and <series>X01 for the worker (X: 1 prod, 2 staging, 3 dev,
4 local); 4, 5 and 6 are taken by our own apps.
A browser extension of an app
npx @haatlabs-core/cli create <name> --kind extension --app-domain <domain> [--app-name <name>]
A side panel for Chrome and Edge on @haatlabs-core/extension-ui and
@haatlabs-core/extension-kit, signed in through the app's own connect page
(https://app.<domain>/connect/extension, which hands the key over as <app-name>.connected;
the app's name is the project's without -extension by default) and calling its API
(https://api.<domain>). make key gives its id for the app's CONNECTABLE_EXTENSION_IDS;
make extension-zip writes the Chrome Web Store (and Edge Add-ons) upload. Firefox's web pages
cannot hand a key to an extension, so this sign-in is for Chrome and Edge; an app with its own
OAuth server can sign an extension in on Firefox with the kit's startOAuthPkce.