Design: Cloudpack CLI

WARNING

This page is a work in progress.

The Cloudpack CLI is a tool developers run to locally serve and bundle their application.

CLI verbs

See the CLI reference page for more details about each command.

Name	Description
start	Start a web inner loop for an app
init	Validate an app's compatibility with Cloudpack, and generate any necessary overrides
bundle	Bundles a package
link	Link package(s) in the current folder to an existing cloudpack start session
unlink	Unlink package(s) in the current folder from a cloudpack start session
sync	Sync packages from/to the remote cache
setup	Set up cert and hosts file settings based on server options

Workflow: start

When cloudpack start is run in a package folder, a Cloudpack session is created to host the app. To do this we need to do the following:

1. Determine all dependent packages and create an import map with supported package imports and corresponding bundle URLs
2. Start express servers for the app, bundles, and Cloudpack API
3. Open the browser to start loading the app's code
4. When the app code imports a package, the import map converts it to a Cloudpack bundle URL and requests that file
   • If the autoUpdateEntries feature is enabled (true by default) and an unrecognized path is imported, Cloudpack will attempt to find that file. If it's found, it will be added to the generated config and the import map, and the page will reload.
5. The Cloudpack bundle server handles the bundle request: either bundling it on demand, or returning the cached version
6. Repeat until the app is loaded!
7. If a change to an app file is detected, Cloudpack reloads the page and triggers re-bundling the relevant packages

Local servers

cloudpack start uses 2-3 servers to orchestrate bundling and serving the app:

• The web page is hosted from the app server.
• By default, JavaScript bundles are hosted by the bundle server.
  • If there are cross-domain issues, the app server can be configured to also handle bundles by enabling the useSingleWebServer feature.
• The API server provides a web socket for communication between the CLI and the status badge/overlay UI block Cloudpack injects onto the bottom right corner of the app page.
  • Think of the overlay as the remote control to Cloudpack: it gives access to verbs, but also a subscription API for getting notifications when things change. It shows what tasks Cloudpack is running, reports errors, refreshes the page when code changes, and allows the user to request re-bundling or other operations.

Workflow: init

It's possible that cloudpack start will "just work" with your app, but in many cases, you'll need to run cloudpack init to work around issues with missing exports maps and implicit or extraneous dependencies. init also provides some optional validation to reduce the chance of runtime errors from missing export names.

TODO: add details

Workflow: bundle

This one is pretty simple: it bundles only the current (CWD) package or specified package(s), depending on options. See the cloudpack bundle docs and examples.

Most Cloudpack commands need to resolve dependencies before running. cloudpack bundle for the current package is able to skip that step as a performance optimization.

Workflow: link/unlink

cloudpack link can be used to test library changes against an app in another repo.

TODO: add details

Workflow: sync

cloudpack sync downloads package bundles into the Cloudpack cache ahead of time. This improves start times significantly as it greatly reduces the number of packages that must be bundled locally while starting the inner loop.

The sync process has two major components:

• Upload bundles to the remote cache (cloudpack sync --upload), usually during a CI build.
• Download bundles to the developer's machine (cloudpack sync), usually as a postinstall step.

Currently, Cloudpack only supports Azure blob storage as the remote cache storage location.

See the reference for setting up sync for more details.

Workflow: setup

cloudpack setup is used to configure certs and host file settings for cloudpack start if your server config sets https: true and/or has a custom domain. This command is intended to be used only on local developer machines and must be run with administrator/root privileges.

If the server config sets https: true, it will create and trust a self-signed certificate for the given domain (excluding IP addresses) or localhost.

If the server config sets domain (non-IP address), it will update the hosts file so that 127.0.0.1 points to that domain.