Get started

WARNING

Cloudpack is a work in progress; documentation, API surface, etc are all in pre-release state and subject to change/may be incomplete. See the status page for more details.

Setting up Cloudpack

The example commands on this page assume yarn as a package manager, but Cloudpack should work with most package managers (Yarn PnP not supported).

Most repos will add package.json scripts for common Cloudpack commands, but the examples below assume running the commands via the package manager directly (yarn in the examples, but should work with any manager).

1. Install @ms-cloudpack/cli as a dev dependency of your app.

2. If your app is simple, it might work in Cloudpack without any extra configuration. Try running yarn cloudpack start and see what happens!

3. If Cloudpack can't find your app's entry point, create a file cloudpack.config.json and configure routes. A common example is below, but see the routing docs for more possibilities. You might also need to configure server options depending on your setup.

   {
     "$schema": "https://unpkg.com/@ms-cloudpack/cli/schema/AppConfig.json",
     "routes": [
       {
         // Common setup:
         // The default route is at the server root
         "match": "/",
         // It corresponds to a TS file
         "entry": "./src/App.tsx",
         // And optionally uses an HTML file as a base.
         "serverEntry": "./public/index.html",
       },
     ],
   }

4. If there are errors about dependencies or unrecognized imports, try running yarn cloudpack init. This will be necessary in most larger apps.

If you're still having issues, check out the troubleshooting info for start or init, or feel free to ask a team member in https://aka.ms/cloudpack-help.

Linking a package to your app

If you have a package that you want to link to your app, you can use the cloudpack link command. This command will create a link between your app and the package, allowing you to develop both simultaneously and see changes in almost real-time.

1. Start your app with yarn cloudpack start. This will start a Cloudpack server for your app.
2. Once your app is running, navigate to the package folder in a separate terminal.
3. In the package folder you wish to link, run yarn cloudpack link. This will link your package to the Cloudpack start server and return to the command line the packages replaced, added, and removed from the graph.
4. You can now make changes to your package and see them reflected in your app almost immediately. If you want to stop linking, you can run yarn cloudpack unlink in the same package folder.

If you want to link all packages in the library, you can run yarn cloudpack link --all in the package folder (e.g. library/packages). This will also link transitive internal packages within the repository rather than only the matched packages. Take a look at the link command options and the link package settings in the Cloudpack config for the app to see what options are available. Make sure to unlink before linking again with different link command options from the same path to get the expected behavior. Remember that any changes to the link package settings in the cloudpack config will require you to run yarn cloudpack start again to apply the changes.

If you are having issues check out the link troubleshooting page.

Note: The link command also requires the package to be linked to follow Cloudpack's repo guidance.

Next steps

To learn more about the capabilities of Cloudpack, have a look at the design overview and client design, or check out the CLI docs.

If you have more questions or your team is interested in potentially being an early adopter of Cloudpack, please reach out! As an early adopter, your team will get to help shape the direction of the project, and we'll work together to ensure Cloudpack meets your repo's needs.