cloudpack link / unlink

cloudpack link enables testing library changes against a consuming app without publishing. This is one of Cloudpack's most powerful features for cross-repo development: it brings the package(s) found within the current folder into a running cloudpack start session.

cloudpack unlink reverts the changes, so the app session goes back to using the installed version of the library.

link options

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

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

Option	Value type	Description
--remote	string	Link to a remote session. Specify one of the following, listed in order of preference: a WebSocket URL (e.g. wss://example.com:9890 or ws://example.com:9890) a URL (e.g. https://example.com) a hostname (e.g. example.com; attempts both wss:// and ws://) no value to use localhost (attempts both wss:// and ws://)
--ignore	string...	Ignore the given packages when linking. Can be used to ignore packages in the current repo that have issues being bundled.
--all	n/a	Link all internal packages discovered within the linked repo's graph.
--ignore-resolutions	string...?	Don't apply resolutions from the host repo's package.json to linked packages. With no value, all host resolutions are ignored; if package names are given, only those packages' resolutions are ignored.
--resolve-strategy	'dedupe' | 'duplicate'	Strategy to use when resolving linked packages: 'dedupe' (default): dedupe packages from the resolve map by removing all but the highest version that satisfies semver requirements from all parent entries. 'duplicate': allow duplicates (don't bump dependencies).
--log-resolve-map	n/a	Log the resolve map to "resolve-map.json".

unlink options

cloudpack unlink unlinks the package(s) found within the current folder from a cloudpack start session.

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

Option	Value type	Description
--log-resolve-map	n/a	Log the resolve map to "resolve-map.json" for diagnostics.

How it works

1. Start a session

In your app repo, start a Cloudpack session:

cd my-app
cloudpack start

2. Link your library

In your library repo, link to the running session:

cd my-library
cloudpack link

Cloudpack will:

• Detect running sessions on your machine and prompt you to select one
• Add your library path to the session's linked paths
• Regenerate the resolve map to use your local library
• Update the import map so requests route to your local code

3. Make changes

Edit your library code. Cloudpack will:

• Detect file changes via the file watcher
• Re-bundle the affected packages
• Refresh the browser (or use HMR if enabled)

4. Unlink when done

In your library repo:

cloudpack unlink

The app session reverts to using the installed version of the library.

Cross-machine linking

You can link to sessions running on other machines:

cloudpack link --remote http://other-machine:3100

Troubleshooting

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

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 link package settings 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.