cloudpack init

cloudpack init validates your app's compatibility with Cloudpack and generates configuration overrides (cloudpack.generated.json) to handle edge cases. The generated configuration should be checked in.

If the current folder has a cloudpack.config.json, init will run against only that folder. Otherwise, it will run against all folders with a cloudpack.config.json (or only the ones matching --app).

Options

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

(You can configure package-specific behavior in cloudpack.config.json.)

Option	Value type	Description
--reset	n/a	Ignore the previous generated config.
--check	n/a	Fail if updates to the generated config are required.
--match	string...	Only evaluate specific package(s), optionally with a version: e.g. --match foo --match '@foo/*' --match foo@1.2.3
--app	string	Run Cloudpack targeting a specific app name.
--no-cache	n/a	Rebuild all packages, rather than using cached assets.
--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

# Initial setup
cloudpack init

# Verify no changes needed (CI)
cloudpack init --check

# Re-evaluate everything
cloudpack init --reset

How it works

Since Cloudpack bundles packages in library mode, it creates a separate bundle for each entry point file in a package. If a new entry point is discovered during cloudpack start (when requested by the browser), it has to resolve that entry point and re-bundle the package. It's easy to determine and resolve the entry points for packages with exports maps, but not for packages using arbitrary deep imports. There can also be issues if a package imports a dependency it didn't declare, or imports a name that isn't exported from a dependency.

Although cloudpack start can handle some of these issues on the fly, cloudpack init does a much more comprehensive analysis of the app code to detect and resolve package entry points that will be used at runtime, as well as detecting and working around missing dependencies and other issues:

1. Scans the dependency graph - Starting from your app, traverses all dependencies.

2. Evaluates each package - Checks for compatibility issues:

   • Missing exports map entries (deep imports not declared)
   • Implicit dependencies (using packages not in dependencies)
   • CommonJS export detection issues
   • Missing export names imported by other packages

3. Generates overrides - Creates or updates cloudpack.generated.json with:

   • Additional exports map entries for deep imports
   • Excluded dependencies for implicit deps
   • Package-specific settings

   This file should be checked in so that other developers can benefit from the updates.

When to run

• During first-time setup - Run before cloudpack start on a new app.
• During PR validation - Run cloudpack init --check in your PR build to verify that the generated configuration is up-to-date.
• On import or dependency changes - If you modify imports and/or dependencies and it breaks cloudpack start, running cloudpack init may fix issues with implicit dependencies or missing exports map paths.

Troubleshooting

So cloudpack init has failed at some point, and you're trying to find out why. This section provides a set of troubleshooting tips to help you diagnose the problem.

You might also want to check out the repo guidance for best practices that can help avoid issues.

cloudpack init --check failed

If you run cloudpack init --check and it fails, it is probably due to one of two reasons:

1. Outdated generated config: There are updates to the generated config that need to be applied. You can run cloudpack init to apply the changes. If this doesn't work, you can also try running cloudpack init --reset to generate a fresh config.

2. Bundling errors: The package is not able to bundle correctly. You can try to fix the issues by following the steps below.

General troubleshooting steps

When a particular package fails to build, there are some common things which can cause this. First, we'll go through some common steps and then delve into specifics.

Run cloudpack init with --log-resolve-map

The job of init is to ensure every package in the graph bundles, and if it doesn't, to provides package overrides in cloudpack.generated.json.

To see what packages it found, you can run cloudpack init --log-resolve-map. This emits a resolve-map.json which tells you where every single package is resolved from, who depends on it, and what it depends on. It can also tell you if multiple versions are found.

Check that the package bundles in isolation

Find the package failing and run cloudpack bundle in its folder. This will tell you if the package can bundle in isolation.

You can inspect the output folder logged by the command for results. You can also run with --log-bundle-info to check the {bundler}-input.json and {bundler}-output.json log files for inspecting inputs and outputs.

Try another bundler

Sometimes packages don't work with the default bundler. You can try another bundler for the specific package as follows:

# General syntax:
cloudpack bundle --match <package-name@version> --bundler <bundler>

# Bundle foo@1.2.3 with rspack:
cloudpack bundle --match foo@1.2.3 --bundler rspack

If another bundler works but the original does not, you can force that bundler for that particular package:

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

Specific issues

Inlining package content that can't be imported through ESM

Cloudpack tries to bundle packages in isolation, resolving them in the browser. However, this isn't always possible. For example, a SASS @import statement can't be resolved in the browser. Packages that export const enums can't provide those const enums in the browser, as they compile out.

To resolve these cross package dependencies that can only be resolved at build time, Cloudpack offers a way to describe a dependency to be included in package bundle output, rather than externalized:

// cloudpack.config.json
{
  "packageSettings": [
    {
      "match": "package-name",
      "inlineDependencies": ["dependency-name"],
    },
  ],
}

Include a missing dependency

Sometimes app code will mistakenly require devDependencies. By default, Cloudpack ignores the devDependencies, assuming that all applications will list actual dependencies. To work around this, packageSettings can be provided to allow some devDependencies to be included in the importMap resolution:

// cloudpack.config.json
{
  "packageSettings": [
    {
      "match": "package-name",
      "includedDependencies": ["dependency-name"],
    },
  ],
}

Verify exports errors

verifyExports is a feature that verifies the exports of packages during init, specifically that consumed named imports exist as an export in the target package. It generates errors when a package imports something that isn't exported by the consumed package. These errors look like the following:

foo@1.0.0 - /monorepo/packages/foo
✗ 1 error
  ✗ [verify exports]
      A bundle imported names from another bundle which were not exported:
        • Importing bundle: /user/.cloudpack/foo-1.0.0-hash/lib/index.js
        • Importing source: /monorepo/packages/foo/src/index.ts
        • Exporting package: bar@1.0.0
        • Exporting bundle: /user/.cloudpack/bar-1.0.0-hash/lib/index.js
        • Exporting source: /monorepo/node_modules/bar/lib/index.js
        • Missing export(s): { baz }

If you're getting verify exports errors, you can try to fix them by:

• Verifying that the package actually exports the missing name.
  • To see which exports Cloudpack detected that the package produces and consumes, look at the bundle-info.json in the corresponding bundle cache folder. (One way to find this folder is by bundling the specific package, which will print the output folder path: yarn cloudpack bundle --match bar@1.0.0)
  • You can also look at the original package source to see if it actually produces an export name that Cloudpack isn't detecting. (If you find a case like this, please file an issue.)
• Verifying that the installed version of the dependency matches the requested range from the consuming package. In some cases, yarn resolutions are used to force a dependency version which violates semver, which can create problems if there have been breaking API changes between the requested and installed versions.

If the above steps don't resolve the issue, you can use ignoreMissingExports to ignore the verify exports errors for specific packages (and for specific exports):

// cloudpack.config.json
{
  "packageSettings": [
    {
      "match": "package-name",
      "ignoreMissingExports": true,
    },
  ],
}

Ori bundling timeout

If you're using ori as a bundler (default bundler on ESM packages), you may encounter a timeout error when bundling such as this:

✗ 1 error
  ✗ [ori]
      Exception while bundling: Error: Received no notification within the timeout window of 10000ms

Ori is set up with a default timeout of 10 seconds. If bundling a package times out, it will retry with a 20 second timeout.

If you're encountering this error repeatedly on specific packages, you can increase the timeout by adding a package setting:

// cloudpack.config.json
{
  "packageSettings": [
    {
      "match": "package-name",
      "bundler": "ori",
      "bundlerOptions": {
        "buildAcknowledgeTimeoutMs": 30000,
      },
    },
  ],
}

You can also try to individually bundle the package with the command cloudpack bundle --bundler ori --match package-name to try to figure out why it is slow.

Could not resolve file with web extensions

If you encounter resolution errors for files that exist with .web.ts, .web.js, or similar web-specific extensions, this indicates that the bundler is not configured to recognize these extensions.

Could not resolve "./file"

What's happening

This error occurs when your code imports a file without an extension, but the actual file has a web-specific extension like .web.ts or .web.js. The bundler cannot resolve the import because it's not configured to check for web-specific file extensions.

Solution

Enable the resolve-web-extensions bundler capability in your cloudpack.config.json:

// cloudpack.config.json
{
  "packageSettings": [
    {
      "match": "package-name",
      "bundlerCapabilities": {
        "resolve-web-extensions": true,
      },
    },
  ],
}

This capability enables React Native-style resolution where bundlers will automatically look for .web.ts, .web.js, .web.tsx, and .web.jsx extensions when resolving imports without explicit extensions.

Note: This setting should be applied to the specific package that contains the web-specific files as it affects performance.

File appears to be an ES module that was loaded with require

This should no longer happen with Node 22. If it still happens, expand to read more.

Expand for details

What's happening

This error occurs when a CommonJS (CJS) package tries to require() an ES module. This is a fundamental limitation (removed in Node 22) - since require() is synchronous, it cannot load ES modules which are inherently asynchronous. See this post to learn more.

This issue typically appears when Cloudpack tries to run a CJS package in a worker process to analyze its exports for generating an ESM stub.

TIP

The package source code might be valid TypeScript ESM, but if the package is published as CJS with no ESM entries, it will be treated as such. Learn more about module formats

Solution options

1. Use a library with proper ESM support

The ideal solution is to use a library that also distributes ESM code with an exports map or a module field in package.json.

If you encounter a library without ESM support:

• Check for library updates: It might be fixed in a newer version.
• Consider reaching out to the library maintainers: Many maintainers are responsive to ESM distribution requests as browser-compatibility becomes increasingly important.
• Open an issue: Politely explain that you're using their library in a browser context with Cloudpack and would benefit from ESM distribution.

While waiting for ESM support, see the alternative solutions below.

2. Bundle the dependency inline (recommended for limited usage)

If the problematic library is only used by a few packages, you can inline the dependency using webpack or rspack as they can handle this situation better. You can do this by adding a package setting in your cloudpack.config.json:

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

This approach embeds the dependency directly into your package's bundle rather than trying to load it separately, skipping the need for an ESM stub.

WARNING

When inlining dependencies, the package will be duplicated if any other package also uses it. This usually doesn't cause issues for utility libraries, but can create problems if the inlined package defines a React context, maintains global state, or uses any other mechanism that needs to be shared across your application. In such cases, consider option #3 instead.

3. Manually specify exports (for widely used dependencies)

If option 2 isn't feasible because the dependency is widely used, you can use the unsafeCjsExportNames package setting to skip the ESM stub generation.

Option 3a: Manually specify export names

If you know exactly what the package exports, you can manually specify them:

// cloudpack.config.json
{
  "packageSettings": [
    {
      "match": "problematic-dependency-name",
      "unsafeCjsExportNames": {
        "./index.js": ["exportName1", "exportName2"],
        "./other-entry.js": ["otherExport1", "otherExport2"],
      },
    },
  ],
}

Option 3b: Auto-generate from TypeScript definitions

If the package has TypeScript declaration files (.d.ts), you can automatically extract exports from the type definitions:

// cloudpack.config.json
{
  "packageSettings": [
    {
      "match": "problematic-dependency-name",
      "unsafeCjsExportNames": "types",
    },
  ],
}

This approach:

• Parses the package's .d.ts files to find all exported names
• Automatically includes exports from re-exported files within the same package
• Saves you from manually listing exports, especially for packages with many exports or exports that change frequently