Upgrading from 3.0 to 3.1

Preparation

Version 3.1 introduces some breaking changes necessary to ensure the highest quality of our API and security. There were no changes in public APIs, so storefronts do not need any changes to be compatible.

Saleor Apps inside Dashboard

Authentication

This change improves the security of embedding Saleor Apps inside the Saleor Dashboard. They no longer share the same context and are now completely isolated.

In 3.0, we introduced the Apps tab to Dashboard, which allowed the display of a custom UI. It was meant to be used for internal Apps where you had complete control of the code.

For 3.1, apps inside Dashboard are sandboxed. They can only communicate with Dashboard via the new JS/TS package called @saleor/app-bridge, which exposes an easy-to-use, fully typed, Promise-based API that uses native Window.postMessage() under the hood. This package is required if you intend to authenticate the App based on the Dashboard user. Authentication is now handled fully on the client side, so Saleor Apps no longer need their backend - they can be SPAs (Single Page Applications) as long as your App can send all its requests from the user's browser. If your App is more complex and talks to multiple services, it might require its backend - in that case, it's your duty to pass the necessary authentication/token information from your App's frontend to the backend. For documentation on how to use @saleor/app-bridge and authenticate, see the package README section.

Manifest

There are no breaking manifest changes, but Dashboard now uses the appUrl for the default App view. The configurationUrl view can still be accessed from within Dashboard, but it's reserved for the App's configuration changes, as the name suggests.

Extending Dashboard with Apps

You can now use your Apps as extensions throughout the Dashboard. For more information and mounting points, see our documentation.