Admin, installation, and OAuth performance
These guidelines apply to apps in the Shopify admin only.
Improve your app's loading performance
Anchor link to section titled "Improve your app's loading performance"Loading performance is an important part of the user experience when using apps in the Shopify admin. When your app is slow to load, it dissuades users from adopting it, increases bounce rates, and decreases overall usage.
You can also improve your app's loading experience by minimizing visual noise, such as layout shifts, and clearly indicating loading progress. As a result, users will perceive your app as faster and more responsive, even if the loading time doesn't change. Refer to the Polaris best practices for loading for a complete guide on designing a high-quality experience.
Measure your app's loading performance
Anchor link to section titled "Measure your app's loading performance"Shopify uses Web Vitals to measure your app's performance in the Shopify admin. Each time a user loads your app, we gather and save the Web Vitals metrics in order to better understand the user experience. To learn more about Web Vitals, you can refer to the introduction on web.dev
Shopify's Web Vitals package measures your app's performance each time a merchant launches your app through any route. Although Shopify doesn't modify scores provided by Web Vitals, there are some differences in how they're recorded in embedded apps compared to standard web development:
- Embedded apps run in iFrames, so tools like Lighthouse might not accurately capture performance.
- To normalize collecting metrics across different application stacks, Shopify records Web Vitals events in a separate runtime from your application.
To help you use performance data and ensure your app is performing optimally, Shopify provides the following key features:
- The ability to monitor Web Vitals in real-time
- Tools for debugging
The following sections describe how you can use these features to enhance your app's performance.
Monitor Web Vitals
Anchor link to section titled "Monitor Web Vitals"The Web Vitals API allows you to access performance metrics directly in your app, giving you real-time insights into your app's performance. You can implement it using the following code:
The callback is called with Web Vitals data, allowing you to send it to your own server for analysis. By monitoring these metrics, you can identify performance issues as they occur and make necessary optimizations.
Debugging Web Vitals
Anchor link to section titled "Debugging Web Vitals"While monitoring provides ongoing insights, sometimes you need to dig deeper to understand specific performance issues. To help with this, Shopify provides a debugging tool for Web Vitals.
To enable detailed logging of Web Vitals as they're recorded and saved, add the shopify-debug
meta flag to your application's head:
The debug flag enables two sets of console logs that provide valuable information about your app's performance:
- Real-time logs directly from Web Vitals, including attribution data for slow-loading elements or inefficient routines
- Send-time logs showing the final values recorded by Shopify
Built for Shopify performance criteria
Anchor link to section titled "Built for Shopify performance criteria"Apps which meet the mandatory criteria on this page, and meet other applicable criteria, are eligible for Built for Shopify status in the Shopify App Store.
Largest Contentful Paint
Anchor link to section titled "Largest Contentful Paint"Largest Contentful Paint (LCP) measures the time from when a user begins loading your page to when the largest image or block of text is displayed. It tracks how quickly your app can display its main content to users.
Cumulative Layout Shift
Anchor link to section titled "Cumulative Layout Shift"Cumulative Layout Shift (CLS) measures your app's visual stability. Unstable user interfaces can be frustrating for users, especially when an element, such as a button, that they're trying to interact with moves suddenly. Cumulative Layout Shift quantifies these kinds of disruptive experiences so you can identify and remove them.
Interaction to Next Paint
Anchor link to section titled "Interaction to Next Paint"Interaction to Next Paint measures a page’s overall responsiveness to user interactions by observing the latency of all click, tap and keyboard interactions that occur throughout the lifespan of a user’s visit to a page. A low INP score means your app is able to quickly respond to all, or the vast majority, of user interactions. Interaction to Next Paint is only collected for apps using the latest version of App Bridge.
Optimize your OAuth flow
Anchor link to section titled "Optimize your OAuth flow"Because authorization is the first interaction that users have with your app UI, you should make sure that it's a positive experience. Follow these best practices for optimizing your OAuth performance to make your app authorization process smoother, faster, and more polished.
Shopify strongly recommends you use the Remix app template, which already has OAuth implemented, and API libraries that include methods that simplify the implementation process. Using the Remix app template helps to ensure that your implementation is complete, and that your app follows our OAuth best practices that are outlined here. You can build an app using the Remix app template by initializing an app using Shopify CLI. Learn more.
If you don't want to use an app template, then you can use the same API libraries that the templates use to implement OAuth in your own app, or you can implement OAuth yourself. To follow Shopify best practices, all embedded apps should use the grant type called token exchange. Token exchange is a more efficient way to authorize embedded apps, and requires only a session token to be exchanged for an access token. This eliminates the need for multiple redirects, and improves performance. To use token exchange, you need to update your app to use Shopify CLI to manage your app's configuration. Doing so will automatically enable Shopify managed installation for your app, dramatically improving the user experience for installation and scope updates and eliminating the need for your app to handle these flows.