cloudpack start

cloudpack start starts the Cloudpack web inner loop for an app, creating a local Cloudpack session to host it. The app to start is determined as follows:

• If the --app option is specified, it will start that app (preferring a specific name match, or falling back to substrings).
• If the current package folder has a Cloudpack config, it will start that app.
• Otherwise, it will scan for packages with Cloudpack configs and show a menu in the CLI.
• If no Cloudpack configs are found, it will attempt to start the current package as an app with default settings.

Options

Common options also apply. Run yarn cloudpack start --help to see all the current options.

(You can configure server options, routing, and package-specific behavior in cloudpack.config.json.)

Option	Value type	Description
--app	string	Run Cloudpack targeting a specific app.
--open	string?	Open the browser (to the URL if provided).
--no-open	n/a	Do not open the browser.
--no-cache	n/a	Rebuild all packages, rather than using cached assets.
--mode	'library' | 'production'	Package bundling mode (default: 'library').
--show-overlay	'always' | 'errors-only' | 'never'	Override whether to show the Cloudpack overlay (status badge and dialog) in the app UI (default: 'always').
--api-server-port	string	Port for the API server (single, comma-separated, or range with dash).
--app-server-port	string	Port for the app server (as above).
--bundle-server-port	string	Port for the bundle server (as above).
--login	'interactive' | 'azure-cli' | 'device-code'	How to authenticate against the remote cache (only if starting a remote app). Default: 'azure-cli' in CI, 'device-code' in Github Codespaces, 'interactive' otherwise.
--log-resolve-map	n/a	Log the resolve map to resolve-map.json.
--log-bundle-info	n/a	Write log files in each package's output folder with bundle input, output, and info. (Requires --no-cache if bundle output already exists.)

Examples

# start app in current folder
# (or at repo root, open a menu asking which app to start)
cloudpack start

# start a specific app by name from the repo root
cloudpack start --app my-app

Starting with --define flags:

cloudpack start --define FEATURE_FLAGS.enableNewUI=true
cloudpack start --define API_URL=https://api.example.com,DEBUG=true,API_PORTS=[8000,8001]

Values without quotes will be automatically converted to appropriate types:

• true and false become boolean values
• Numbers become numeric values
• Arrays are converted to arrays
• Everything else remains as strings

These define flags will be handled the same way as those specified in the define section of the configuration file, but take precedence over values in the config file.

How it works

In brief (see request flow architecture for more details):

1. Load configuration - Read cloudpack.config.json and merge with defaults
2. Resolve dependencies - Build a dependency graph of all packages
3. Generate import map - Create the import map from package names to bundle URLs
4. Start servers - Launch the local servers
5. Open browser - Navigate to your app
6. Handle requests - When the browser imports a package, the import map converts it to a bundle URL, which is returned from the cache or bundled on demand
7. Watch for changes - When source files change, automatically re-bundle affected packages and refresh the browser (or use HMR if enabled)

Local servers

The Cloudpack session uses 2-3 servers to orchestrate bundling and serving (more details on the servers):

• App server - Serves your application's HTML and routes, and injects the import map and overlay
• Bundle server (optional) - Serves package bundles and handles on-demand bundling (combined with app server if useSingleWebServer feature is enabled)
• API server - Handles internal orchestration and communication with the browser overlay

Browser overlay

The overlay is a UI block Cloudpack injects into your running app (in the bottom-right corner) during start. It's your window into what Cloudpack is doing while you develop:

• Status badge: A small badge shows the current session status at a glance (idle, working, or error). Click to show the dialog.
• Dialog:
  • List of package bundles in progress and completed, including any errors and warnings
  • Fatal errors with bundling or resolution
  • Actions to force re-bundling one or all packages

The overlay stays in sync with the running session in real time by connecting to the API server over a WebSocket. For the technical details of how updates flow to the overlay (including how hot module replacement updates are applied), see Architecture.

You can control whether the overlay is shown with the --show-overlay CLI option or the showOverlay config setting. Use errors-only to keep it out of the way until something goes wrong, or never to hide it entirely.

Troubleshooting

Some of the troubleshooting steps for init may also apply to certain errors in cloudpack start.

Ad blockers

We've seen cases where ad-blockers prevent the cloudpack start command from working properly. If you have an ad-blocker installed, try disabling it and running the command again.

System limit of file watchers

If you see an error message like this:

Error: ENOSPC: System limit for number of file watchers reached

and you are using VS Code, you can try to free some used watchers with the following configuration in your VS Code User Settings:

  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "**/.git/subtree-cache/**": true,
    "**/node_modules/*/**": true,
    "**/.yarn/**": true
  },

If that doesn't work, you can increase the number of watchers with the following command:

echo fs.inotify.max_user_watches=131070 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

If the limit is still reached, you can increase it further by changing the number in the command above.

Missing exports

If an export path can't be resolved at runtime:

1. Try running cloudpack init first.
2. If it still doesn't work, check the package contents in node_modules and see if the file is present at some other path. If so, add a PackageSettings.exports config for that package.

"Dynamic require is not supported"

If you see an error message like this:

Uncaught Error: Dynamic require of "package" is not supported

This is likely a package that declares an ESM entry that imports a CJS file with a require() (learn more about module formats). Cloudpack uses Ori to bundle ESM packages by default, but its esbuild core doesn't support require() of other packages.

You can fix this by switching the bundler to rspack, webpack or rollup in your cloudpack.config.json:

// cloudpack.config.json
{
  "packageSettings": [
    {
      "name": "package-name",
      "bundler": "rspack",
    },
  ],
}

"TypeError: package-name is not a function/constructor/others"

If you see an error message like this:

TypeError: package-name is not a function

What's happening:

This error occurs when importing CommonJS (CJS) modules using incorrect ES module import syntax. The issue is that different import patterns access the module exports differently.

This issue is most common with older packages that weren't designed for ESM compatibility. Consider reaching out to the package maintainer to add proper ESM support.

The problem:

// This often fails with CJS modules
import * as LRUCache from 'lru-cache'
new LRUCache({ max: 100 }) // TypeError: LRUCache is not a constructor

// Because the actual constructor is nested under 'default'
console.log(LRUCache) // { default: [class LRUCache], ... }

Solutions

1. Use default import instead of namespace import

// Instead of
import * as LRUCache from 'lru-cache'

// Use
import LRUCache from 'lru-cache'
new LRUCache({ max: 100 }) // ✅ Works

2. Access the default property explicitly

If the change above causes a runtime failure in another tool, you may need to explicitly check .default on the namespace import, with the original as a fallback:

// If you must use namespace import
import * as _LRUCache from 'lru-cache'

// Fall back to namespace import if default is not available
const LRUCache = _LRUCache.default ?? _LRUCache
// If there's a TS error:
//   const LRUCache = (_LRUCache as unknown as { default?: typeof _LRUCache }).default ?? _LRUCache
// or:
//   const LRUCache = _LRUCache.default ?? (_LRUCache as unknown as typeof _LRUCache.default)

new LRUCache({ max: 100 }) // ✅ Works

3. Switch to a different bundler and inline the dependency

If import syntax changes don't work, try inlining the dependency and switching to a bundler that supports CJS better, like rspack or webpack:

// cloudpack.config.json
{
  "packageSettings": [
    {
      "match": "package-name",
      "bundler": "rspack",
      "inlinedDependencies": ["problematic-package-name"],
    },
  ],
}