Shopify embed previews
Shopify apps usually render inside an iframe within the Shopify Admin, which is annoying for development and performance profiling. Gadget offers a way to preview your embedded Shopify app outside the Shopify Admin, within either a dedicated browser tab or within the Gadget editor.
To view your Shopify application in preview mode, you must be using the @shopify/app-bridge-react package version 4 or above, and have
your app installed on at least one Shopify store. Read more about the App Bridge V4 script in the Shopify frontend
docs.
Shopify apps built with Gadget can always be previewed in Development within the Shopify Admin once installed on a store:
Gadget's embed preview supports viewing the same application outside the Shopify Admin in a dedicated browser tab:
Or within the Gadget editor:
Viewing an embed preview
You can preview your app in the Gadget editor using the Preview section of the editor. If you want to pop out the preview into a new browser tab, click the URL bar in the mini-browser to open a new, full-page browser tab of the preview.
Previewing your app runs it in a realistic way:
- your app still makes real API calls to Gadget to retrieve data, so you can query data synced from Shopify or data in your own Gadget models
- API calls are still access controlled, so your filters and permissions apply
- if in the Development environment, hot-module reloading and other Gadget development features remain active
- if in the Production environment, minified and bundled production code is used for realistic real-world performance metrics
Embed preview URLs are sensitive as they allow authenticated access to your app's data, which includes any data you have synced from Shopify. This is necessary to support LCP profiling. Do not share these URLs with anyone you don't trust to have access to the application.
Embed preview supported features
The embed preview for Shopify apps works by mocking out the implementation details of the Shopify App Bridge, allowing the app to function as if it were installed in the Shopify Admin. Gadget's mock responds to App Bridge API calls your app makes in the same way Shopify does where possible, but not all functionality is supported.
| Feature | Supported in in-editor preview | Supported in full-page preview | Supported within Shopify Admin |
|---|---|---|---|
| Session token authentication | ✅ Supported | ✅ Supported | ✅ Supported by Shopify |
| Toast | ✅ Supported | ✅ Supported | ✅ Supported by Shopify |
| NavMenu | ✅ Supported | ❌ Not supported | ✅ Supported by Shopify |
| Modal | ✅ Supported | ❌ Not supported | ✅ Supported by Shopify |
| SaveBar | ✅ Supported | ✅ Supported | ✅ Supported by Shopify |
| TitleBar | ✅ Supported | ✅ Supported | ✅ Supported by Shopify |
Unlisted features are currently not supported in the embed preview, but you can always test them out using your Development environment within the real Shopify Admin.
Using the embed preview for performance profiling
The full-page embed preview is useful for profiling the performance of your Shopify app using traditional web performance tools like PageSpeed Insights or webpagetest.org. A URL produced by Gadget for a full page embed preview includes all the information necessary to render the client side application, so you can paste these generated URLs into your performance profiling tool of choice. Critically, a full-page embed preview does not include any of the Shopify admin assets or any iframes, so any gathered performance metrics measure your application's performance, not Shopify's.
Only use the Production environment for profiling your application's LCP or other web vitals. Development environments are not optimized for performance, and will not represent real-world metrics.
The app-bridge-cdn-mock.min.js script file
Gadget's embed preview uses a different <script/> tag than the standard Shopify https://cdn.shopify.com/shopifycloud/app-bridge.js script tag called app-bridge-cdn-mock.min.js. When viewing an embed preview, Gadget will include this script in your application's <head/> tag automatically:
html<head> <!-- injected automatically by Gadget --> <script src="https://assets.gadget.dev/assets/app-bridge-cdn-mock.min.js" data-api-key="<some-api-key>"></script> </head>
This script implements the same functionality as the Shopify CDN script, but includes modifications to allow running in this embed preview mode. It is required for the embed preview to function properly. This script file is only used for the embed preview mode, and won't ever be included in your application for real production users.
Gadget automatically injects the app-bridge-cdn-mock.min.js script file when viewing an embed preview, and uses the standard Shopify https://cdn.shopify.com/shopifycloud/app-bridge.js script tag when viewing your app in the Shopify Admin.
Performance impact of the app-bridge-cdn-mock.min.js script
When performance profiling using the full-page embed preview, you may see the app-bridge-cdn-mock.min.js script in your request waterfalls. This script's performance will not impact your production application's performance, as it is only used for the embed preview mode.
However, the standard Shopify https://cdn.shopify.com/shopifycloud/app-bridge.js script will be included in your production application instead, and it will impact your performance metrics. Shopify requires this script to be present, and fully controls the content and performance of it, so Gadget app developers aren't able to change much about its performance impact.
The app-bridge-cdn-mock.min.js script is significantly larger than the Shopify CDN script to power the mock functionality, so you will likely see a performance improvement in the real world use of your app within the Shopify Admin.