Troubleshooting cloudpack link

The link command brings dependencies from a remote project into a running Cloudpack host session. This guide provides a set of troubleshooting steps to help you diagnose issues if cloudpack link isn't working as expected.

The following describes some tools and techniques to help diagnose and solve common issues.

Run cloudpack link with --log-resolve-map

Running cloudpack link with --log-resolve-map will emit 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 scoped versions are found.

Managing resolve map resolutions

There are some options to control the resolve map resolutions available through command line flags and link package settings.

If an option is not working as expected or you need more flexibility, create an issue here.

Ignoring specific packages

If there are packages within your repository that you do not wish to link, you can ignore them using the --ignore option. This is useful for packages that are part of the current repo but have issues being bundled or are not relevant to the current development focus.

Linking all internal packages

For scenarios where you want to link all discoverable packages within the repository, use the --all option. This is particularly useful in monorepos where multiple related packages are being developed in tandem.

Resolve strategy

When linking packages, you might encounter situations where multiple versions of the same package exist. The --resolve-strategy option allows you to specify how these conflicts are resolved:

• Dedupe: This strategy attempts to reduce duplication by linking to a single version of the package.
• Duplicate: Allows multiple versions of the same package to coexist.

Ignoring resolutions

If you need to ignore the resolutions from the host repo definition to the linked packages, use the --ignore-resolutions option. This can be useful when testing changes that might conflict with the locked versions specified in the host project.

Handling singletons

Some packages are required to be singletons: only one version of that package may be present in an app. For example, React gives the following error if multiple versions are present on the page:

Invalid hook call. Hooks can only be called inside of the body of a function component. This could happen for one of the following reasons: 1. You might have mismatching versions of React and the renderer (such as React DOM) 2. You might be breaking the Rules of Hooks 3. You might have more than one copy of React in the same app.

It's important to apply the following configuration in the host repository:

{
  "packageSettings": [
    {
      "match": "react",
      "link": {
        "duplicatedDependencyBehavior": "force-host-version"
      }
    }
  ]
}

Updating export maps

It is possible that the linked repository packages have different export maps to the ones declared in the generated config (cloudpack.generated.json) or in the app config (cloudpack.config.json) which can result in files not found or missing exports.

For errors about unrecognized imports in your project, such as:

• Path "<path>" was imported from package "<package>" but was not recognized as an exported path.
• Failed to resolve module specifier "<package>"

You can update the export maps from the Cloudpack UI by adding an override when there is a missing import path, by enabling the feature autoUpdateEntries in the host repository, or by providing your own on the cloudpack configs.

No differences found in the resolve map

If you run cloudpack link and see no differences in the resolve map, it may be because the packages are already linked. You can check the resolve-map-linked.json by running the command with the flag --log-resolve-map to confirm that the packages are already linked.

If that is not the case, it might be that the packages are not set for linking. You can try running the command with the --all flag to also link transitive internal packages.

Missing exported names

If you run into the following error:

The requested module "<package>" does not provide an export named "<name>"

This means that the package is not exporting the name you are trying to import. It might be the case that the linked package removed the export in a new version, make sure to check the version for major bumps and see if the export is still available. If the export is not available, you can try modifying your app code to use a different export or check the package documentation for any changes.

If the export is available it might be the case that the package from the linked repository requires different package settings to bundle as expected. You can check any package settings in the linked repository and compare them to the ones in your app. If they are different, you can try updating the package settings in your app to match those in the linked repository.