polaris
polaris copied to clipboard
Shopify
Deprecated components `Frame`, `Loading`, `Modal`, `Navigation`, `Toast` and `ContextualSaveBar`
Issue summary
I have a project that uses shopify/polaris as the base component framework, Deprecating these components would have a huge impact on me.
So, whether there is a major release that supports these components and keeps them updated or If I want to continue using these components, What do I need to do?
+1
Missing documentation even before a major release is a problem, looking at the docs, I can't find any references, and I don't even have an idea if there are some substitute components being created for this? also some of the components like Modal will effect hugely when it comes to state management.
Looking forward to the complete release so we can be sure of what to expect from this point and what components do we need to upgrade.
If I want to continue using these components, What do I need to do?
Sorry about the abruptness of this change. These components were always meant for internal use only, and the documentation should have been removed with the inception of AppBridge.
There are components within Polaris that shouldn't be used in third party apps, like Navigation and Frame (there should only be one Navigation and Frame per page and they already exist within the admin). The other components should be accessed via AppBridge Actions, where you'll find the remaining components: Toast, Modal, Loading, and more.
The task of rewriting the Modal component to adhere to new rules will be challenging and time-consuming due to the limited functionality of the app bridge version. This change will require modifying the application's logic in multiple areas, which will add to the maintenance workload.
Additionally, a major challenge with using the app bridge is that it only works within an iframe, making it difficult to test and integrate with React projects outside of the iframe. Unfortunately, the automatic update feature of React does not function with the frame. The unavailability of app bridge components outside of the iframe is a significant limitation.
The status of "@shopify/app-bridge-react" is unclear as it has been moved to the "Previous versions" section, raising concerns about its discontinuation in the future.
It would be helpful to know if there are any alternatives that allow for the use of app bridge components outside of the iframe and what is the fate of @shopify/app-bridge-react?
I also have the same question, why was there no notice before removal and no reasonable alternative?
1/ Using Modal at @shopify/app-bridge-react, I don't see any documentation that allows adding more UI to Modal's body, Modal is simply a string message. This affects us a lot.
2/ With @shopify/app-bridge-react being included in "Previous versions", what does its future look like? Has it been eliminated? What will the future of apps built based on React be like if removed? Converting a React application to Remix is not easy.
If I want to continue using these components, What do I need to do?
Sorry about the abruptness of this change. These components were always meant for internal use only, and the documentation should have been removed with the inception of AppBridge.
There are components within Polaris that shouldn't be used in third party apps, like Navigation and Frame (there should only be one Navigation and Frame per page and they already exist within the admin). The other components should be accessed via AppBridge Actions, where you'll find the remaining components: Toast, Modal, Loading, and more.
My project doesn't exist on shopify page, so I don't use AppBridge.
Even if you want to deprecate, you can do that and we will consider upgrading with a deadline in mind, I am not sure how can you just hide a components documentation which hurts our business planning and timelines.
It would be best if you can atleast bring back the documentation for now at the deprecated section, we will upgrade definitely in the future once we have spare time to do that. @kyledurand
My project doesn't exist on shopify page
Where does your project exist @SinXie? Polaris was built explicitly for the Shopify admin and its apps
Where does your project exist @SinXie? Polaris was built explicitly for the Shopify admin and its apps
Hi, the question was not addressed to us, but I can give you our use cases:
-
A browser extension that works in the Shopify admin area, so that it matches the design of the admin area and so that you can use components from the main application, we use Polaris there. And of course, there is no way to connect an app bridge, so a lot of things will have to be rewritten when the same modal windows do not work.
-
The admin part of the application. We understand that this is not directly related to the application, but the use of Polaris in our admin allows us not to write the code twice and use many modules there.
-
Testing and development. Again, the fact that most everything could be implemented without an app bridge allowed us to quickly and efficiently develop and test applications. Now you have to tie everything to the shopify admin panel and the iframe. And of course, page loading in the admin frame is ten times slower than from a conditional localhost.
Of course, Polaris was not designed for such scenarios, but the fact that it could work without an app bridge made it more versatile and accelerated development and simplified support. Making these changes, especially the abandonment of local modal windows, will make life more difficult for developers.
Polaris was created and is generally considered to be in the direction of simplifying development, but this decision seems to go against those statements.
I am a developer at Meta, actively working on the Facebook and Instagram sales channel in Shopify Admin.
I would like to add to the conversation and express my concerns about the sudden deprecation of these components. Modals and Toasts are used extensively within the Facebook and Instagram sales channel. Now that the documentation for these components is completely gone, it makes it hard for us to determine how to transition to AppBridge modals, even if we decided to do that.
Can the documentation for Modal, Frame, Loading, Navigation and Toast be brought back on the Shopify Polaris website?
- https://polaris.shopify.com/components/deprecated/legacy-card - LegacyCard and other components are good examples. These components were deprecated, but the documentation is still available.
There are components within Polaris that shouldn't be used in third party apps, like Navigation and Frame (there should only be one Navigation and Frame per page and they already exist within the admin). The other components should be accessed via AppBridge Actions, where you'll find the remaining components: Toast, Modal, Loading, and more.
@kyledurand What about all of us that are part of the Shopify ecosystem and use these components in standalone versions of our apps? This represents a huge breaking change for many of us. We use polaris not only in our embedded apps, but also in our standalone apps. All of these apps are part of the same ecosystem and taking these components away will make it harder for us to support any of polaris.
-
If we don't have these foundational components, we have to use something other than polaris, and given the size of our team, we cannot support both an embedded polaris and non-embedded non-polaris version of our app.
-
This seems to be a sudden and major change to polaris that has had little-to-no communication
I just traced these changes to the following PR: https://github.com/Shopify/polaris/pull/11382
Am I correct in understanding that your goal is just to add friction? If so, I believe there must be better ways to do this.
I'm curious if @alex-page, @craigbrunner, or @themarkappleby chatted with anyone in the ecosystem before moving forward with this change.
My intention is only to provide the perspective of a company that is in the Shopify ecosystem:
I'm one of the cofounders of Endear, a CRM and clienteling solution for consumer brands, many of whom are Shopify merchants. We are a Shopify Plus certified app partner.
We use Polaris to build our applications which span standalone web, a mobile app, a POS embedded app, and a soon to release web embedded app.
We use Polaris across all these surfaces because we want to be good ecosystem citizens, but we are a small team, so we build and maintain a single app for all of these surfaces.
We also like Polaris because it "just works", is accessible, and covers the most important UI components that most apps need. Many of the deprecated components would fall into that category.
If you move forward with this change, we will have no choice but to migrate away from Polaris because we need to have a stable and complete UI lib to do our jobs well. It won't be a good use of our team's time to build a Polaris version of our app just to embed in Shopify if we use a different UI lib outside Shopify. This would mean that any surface embedded in Shopify that requires Polaris will have fewer features because we will now have to support embedding just to check a box for "built for Shopify" certification and similar.
If you interviewed the merchants we share (many of whom are some of your largest merchants), I guarantee you that the changes being made here would not fall into their top 10 or even top 100 list of concerns.
I completely understand that you don't want app devs using some of these components when embedded because it degrades the UX in Shopify admin, but that seems solvable with stricter guidelines for app approval and built for Shopify certification. I would suggest a separate section called "for standalone apps" or an automatic warning or error when rendering those components when they are embedded in Shopify.
I know this is a long post, but I'm hoping that it helps exemplify how important it is to us that these components are maintained. You are building, not just for Shopify and embedded apps, but also an entire ecosystem beyond that which relies on you as a platform.
Lastly, I want to request that if you are committed to supporting that ecosystem, that you consider adopting an RFC process and/or design partner program to work with different stakeholders in the ecosystem to build for everyone. I love what @ryanflorence and @mjackson have done with their open processes, and I believe Polaris would benefit from a similar approach.
I just traced these changes to the following PR: https://github.com/Shopify/polaris/pull/11382
Am I correct in understanding that your goal is just to add friction? If so, I believe there must be better ways to do this.
I'm curious if @alex-page, @craigbrunner, or @themarkappleby chatted with anyone in the ecosystem before moving forward with this change.
My intention is only to provide the perspective of a company that is in the Shopify ecosystem:
I'm one of the cofounders of Endear, a CRM and clienteling solution for consumer brands, many of whom are Shopify merchants. We are a Shopify Plus certified app partner.
We use Polaris to build our applications which span standalone web, a mobile app, a POS embedded app, and a soon to release web embedded app.
We use Polaris across all these surfaces because we want to be good ecosystem citizens, but we are a small team, so we build and maintain a single app for all of these surfaces.
We also like Polaris because it "just works", is accessible, and covers the most important UI components that most apps need. Many of the deprecated components would fall into that category.
If you move forward with this change, we will have no choice but to migrate away from Polaris because we need to have a stable and complete UI lib to do our jobs well. It won't be a good use of our team's time to build a Polaris version of our app just to embed in Shopify if we use a different UI lib outside Shopify. This would mean that any surface embedded in Shopify that requires Polaris will have fewer features because we will now have to support embedding just to check a box for "built for Shopify" certification and similar.
If you interviewed the merchants we share (many of whom are some of your largest merchants), I guarantee you that the changes being made here would not fall into their top 10 or even top 100 list of concerns.
I completely understand that you don't want app devs using some of these components when embedded because it degrades the UX in Shopify admin, but that seems solvable with stricter guidelines for app approval and built for Shopify certification. I would suggest a separate section called "for standalone apps" or an automatic warning or error when rendering those components when they are embedded in Shopify.
I know this is a long post, but I'm hoping that it helps exemplify how important it is to us that these components are maintained. You are building, not just for Shopify and embedded apps, but also an entire ecosystem beyond that which relies on you as a platform.
Lastly, I want to request that if you are committed to supporting that ecosystem, that you consider adopting an RFC process and/or design partner program to work with different stakeholders in the ecosystem to build for everyone. I love what @ryanflorence and @mjackson have done with their open processes, and I believe Polaris would benefit from a similar approach.
I agreee with what Jinesh just mentioned here. Working as a small team, it's pretty hard to use different UI libs, providing the best merchant ux is only goal all developers have and we go beyond our abilities to deliver that. Making it hard is bad, it was easy already, so why break something which was working before.
Special focus on the built for shopify thing as that's a requirement when you even consider those.
Again we understand you want them to be used in a certain way. We're more than happy to adhere them but can we please follow a better way of doing that? A warning or rejecting the app application would have been a much better way clearly, and also deprecating without any prior notice and hiding the doc altogether was another unprofessional step by the team. Atleast let the doc be there so we can work with what we have...
Hey folks thanks for the feedback. I am going to share context here on why this decision was made and I cannot promise this is a change we will undo in the future. Please continue sharing feedback it's super helpful.
I'm curious if @alex-page chatted with anyone in the ecosystem before moving forward with this change
No. For many years we have maintained AppBridge and Polaris components side by side. The confusion this has caused our developers and the poor quality experiences we have built due to this has created a need to make an intentional change. We know this would be a challenging decision and one that would be frustrating to some users. Polaris is an open source UI library used for many different purposes today. The intention of this change is to narrow the scope of Polaris to focus on helping Shopify developers build the best applications and channels possible.
One of the most common issues when building a Shopify application or channel is that developers incorrectly use the Polaris components (<Modal> <Toast>, <ContextualSaveBar>...). Using the Polaris library causes the components to render incorrectly which reduces the quality of the experience for our merchants. This happens because the App Body <iframe> limits the position components can be rendered in. To ensure that our community builds the highest quality experiences for merchants we are directing you to use AppBridge which ensures these components are rendered in the correct place.
If I want to continue using these components, What do I need to do?
If you are building a Shopify application or channel I would start by replacing the deprecated components with AppBridge. The API's are different but the user experience is the best it can be for our merchants. The App Bridge Modal API allows children to be rendered in with the src property which is a URL to a HTML page to render inside the <Modal>. This is quite different to how children can be added with JSX in Polaris today.
If you are not building a Shopify application or channel I would recommend copy pasting the component code from Polaris and adding it to your application. In the future these components will be removed and they will always be accessible in git history in the Polaris repository.
Can the documentation for Modal, Frame, Loading, Navigation and Toast be brought back on the Shopify Polaris website?
I will talk to the team this week and make a decision on what documentation could be added back to the Polaris website. To set expectations this would likely be the highly used components (my gut feeling is it would probably be <Toast> and <Modal> only).
My opinion is that we need to direct developers to AppBridge documentation. Unlike <LegacyCard> the documentation lives on a different website. Maintaining the old documentation is going to misdirect developers to build the wrong solutions. If you absolutely have to read the old documentation right now it is available in git history.
Even if you want to deprecate, you can do that and we will consider upgrading with a deadline in mind
These components can still be used today. We will update developers with a timeline for removal from the library soon. See this as the first initial nudge that these components should be replaced.
Hi @alex-page , the issue of @shopify/app-bridge-react support and its relocation to the "Previous versions" section seems to have slipped through the cracks. I would like to understand what your plans are to understand and rewrite the code of modal windows for the react version or consider another option right away? It would be nice not to rewrite the code twice.
Thanks.
@mesija sorry I should have included this in my response.
I have asked the app bridge team to clarify what is happening there. My understanding is that nobody should have to rebuild their application in Remix (even though we are big fans of the framework) and that AppBridge is a supported library. I want their team to chime around the specific reasons why it is in "Previous versions" as I don't want to respond with misinformation.
My project doesn't exist on shopify page
Where does your project exist @SinXie? Polaris was built explicitly for the Shopify admin and its apps
This project is a private app of my Shopify store, which can open a new page. I hope the interaction and ui of this page are consistent with Shopify admin.
My project doesn't exist on shopify page
Where does your project exist @SinXie? Polaris was built explicitly for the Shopify admin and its apps
This project is a private app of my Shopify store, which can open a new page. I hope the interaction and ui of this page are consistent with Shopify admin.
Then I wondered if Shopify would later have a ui library for such apps. Because the previous Polaris fits my app scenario very well.
Hi all,
Just wanted to touch on the comments about the @shopify/app-bridge-react package. It's not deprecated and we're still supporting it. We'll be releasing a new version soon which includes React wrappers for components like the new ui-modal that allows you to write custom DOM content within the Modal instead of just content strings or an iframe src. Once that's released, all of the main App Bridge docs will have the React wrappers alongside them again.
cc: @mesija @lehoangnnx
Hey folks thanks for the feedback. I am going to share context here on why this decision was made and I cannot promise this is a change we will undo in the future. Please continue sharing feedback it's super helpful.
I'm curious if @alex-page chatted with anyone in the ecosystem before moving forward with this change
No. For many years we have maintained AppBridge and Polaris components side by side. The confusion this has caused our developers and the poor quality experiences we have built due to this has created a need to make an intentional change. We know this would be a challenging decision and one that would be frustrating to some users. Polaris is an open source UI library used for many different purposes today. The intention of this change is to narrow the scope of Polaris to focus on helping Shopify developers build the best applications and channels possible.
If you don't talk to any of the developers using your library in the ecosystem, how do you know that you are actually solving their problems? We are Shopify developers. We are a Plus certified app partner and pay a lot of money to shopify for the platform capabilities they provide. Polaris falls into this bucket, and it seems unreasonable to make a major change like this & drop all the docs without talking to Shopify developers like us.
One of the most common issues when building a Shopify application or channel is that developers incorrectly use the Polaris components (
<Modal><Toast>,<ContextualSaveBar>...). Using the Polaris library causes the components to render incorrectly which reduces the quality of the experience for our merchants. This happens because the App Body<iframe>limits the position components can be rendered in. To ensure that our community builds the highest quality experiences for merchants we are directing you to useAppBridgewhich ensures these components are rendered in the correct place.
This is why I suggested the alternatives. These components could easily detect when they are rendered in Shopify admin embedded and warn or error.
If I want to continue using these components, What do I need to do?
If you are building a Shopify application or channel I would start by replacing the deprecated components with
AppBridge. The API's are different but the user experience is the best it can be for our merchants. The App Bridge Modal API allows children to be rendered in with thesrcproperty which is a URL to a HTML page to render inside the<Modal>. This is quite different to how children can be added with JSX in Polaris today.
To be clear, we are a Shopify application, we are a Shopify channel, and we are a Shopify POS application. We are literally all of these things.
If you are not building a Shopify application or channel I would recommend copy pasting the component code from Polaris and adding it to your application. In the future these components will be removed and they will always be accessible in
githistory in the Polaris repository.
This seems like a band-aid at best. Over time, you will almost definitely end up breaking compat with copy-pasted-code here.
Can the documentation for Modal, Frame, Loading, Navigation and Toast be brought back on the Shopify Polaris website?
I will talk to the team this week and make a decision on what documentation could be added back to the Polaris website. To set expectations this would likely be the highly used components (my gut feeling is it would probably be
<Toast>and<Modal>only).My opinion is that we need to direct developers to
AppBridgedocumentation. Unlike<LegacyCard>the documentation lives on a different website. Maintaining the old documentation is going to misdirect developers to build the wrong solutions. If you absolutely have to read the old documentation right now it is available in git history.Even if you want to deprecate, you can do that and we will consider upgrading with a deadline in mind
These components can still be used today. We will update developers with a timeline for removal from the library soon. See this as the first initial nudge that these components should be replaced.
I would again implore you to reconsider this decision. I don't believe the problems you are trying to solve are incompatible with keeping this library fully featured.
@alex-page @charlesdobson , thank you for your quick response.
Our team is very pleased that the bridge support for React will be relevant, we have already ordered a celebratory pizza on this occasion 🎉
Of course, we have nothing against Remix, but still, rewriting an application on a new framework is not an easy task :)
Hello! I was indeed confused by this change too. There was nothing in the changelog and now currently many components' documentation are missing and they are all marked as deprecated.
I understand that Polaris was primarily made for Shopify apps, but there are some of us who use it to create completely external apps that don't integrate with Shopify in any way, as supported by the LICENCE file:
external, stand-alone applications that do not embed directly inside Shopify, the rights granted above may only be exercised to develop and distribute applications that are dissimilar and visually distinct from Shopify products and services (including the internal administration page of a Shopify merchant store), as determined by Shopify in its sole discretion.
Now, if I understand this correctly, these components are being removed in favour of similar components already in the Shopify AppBridge library.
AppBridge seems to be a proprietary and closed-source library that only work within the Shopify Admin, as evidenced from the following text from the AppBridge website:
App Bridge components don't render as part of the app's component hierarchy. They are React-like wrappers around JavaScript messages that communicate with the Shopify admin. The Shopify admin does the UI rendering.
With this change, does that mean that open source developers that develop external websites that don't integrate with Shopify will cease to be supported? Does that mean that Polaris is now only for Shopify apps? Will the clause granting that access to external developers in the licence get removed? I'm really confused and would like to gently ask for clarification.
I came to this issue after noticing the deprecation of key components like Toast and Modal while building a new app on Shopify. My perspective on this issue is shaped by my experience with App Bridge. Initially, I felt that App Bridge started off as a utility library aimed at helping us, Shopify app developers, to integrate more seamlessly and effectively into Shopify. But somewhere along the line, it seems to have diverged from being a facilitative tool to becoming a limiting factor, especially with the recent deprecations. These changes appear to restrict the flexibility and functionality we had come to rely on, rather than enhancing our ability to develop robust Shopify applications.
No. For many years we have maintained AppBridge and Polaris components side by side. The confusion this has caused our developers and the poor quality experiences we have built due to this has created a need to make an intentional change. We know this would be a challenging decision and one that would be frustrating to some users. Polaris is an open source UI library used for many different purposes today. The intention of this change is to narrow the scope of Polaris to focus on helping Shopify developers build the best applications and channels possible.
The decision to deprecate these components, under the pretext of reducing confusion between AppBridge and Polaris components, feels like an unnecessary forceful measure against the developer community. While the intent to streamline might be well-meant, the actual execution overlooks the immediate needs and investments of developers like myself.
If you are building a Shopify application or channel I would start by replacing the deprecated components with AppBridge. The API's are different but the user experience is the best it can be for our merchants. The App Bridge Modal API allows children to be rendered in with the src property which is a URL to a HTML page to render inside the <Modal>. This is quite different to how children can be added with JSX in Polaris today.
it's important to note that this doesn't cater to the diverse use cases of the broader developer community. The limitations of the App Bridge Modal API, as opposed to the flexibility offered by JSX in Polaris, can significantly hinder developers in crafting effective and user-friendly solutions. This change, therefore, not only limits the tools available to developers but also potentially impacts the end-user experience negatively.
I am currently maintaining an existing application that uses these now-deprecated components and am developing a new app using the App Bridge. However, the alternatives provided through the App Bridge API fall short of the usability and functionality that the original Polaris components offered.
If you are not building a Shopify application or channel I would recommend copy pasting the component code from Polaris and adding it to your application. In the future these components will be removed and they will always be accessible in git history in the Polaris repository.
Furthermore, the advice to replicate Polaris component code in our applications is a short-sighted and impractical workaround. This approach fails to consider the long-term requirements of software maintenance, such as regular updates and security, which are critical aspects of using a managed library. It is a disservice to the principles of sustainable software development and does not adequately support the ongoing needs of the Shopify developer community.
Thanks for all the feedback. There is a lot here and we are working through it.
One of the biggest issues was not being able to access the deprecated component documentation. The initial change to direct application developers to App Bridge was too harsh. To address this I have added back the component documentation to all of the newly the deprecated components https://github.com/Shopify/polaris/pull/11493.
You can view the documentation for all deprecated components:
- https://polaris.shopify.com/components/deprecated/contextual-save-bar
- https://polaris.shopify.com/components/deprecated/frame
- https://polaris.shopify.com/components/deprecated/loading
- https://polaris.shopify.com/components/deprecated/modal
- https://polaris.shopify.com/components/deprecated/navigation
- https://polaris.shopify.com/components/deprecated/toast
- https://polaris.shopify.com/components/deprecated/top-bar
Thanks, @alex-page, for hearing out the community.
Hopefully, a solution that provides an alternative to App Bridge for non-Shopify websites can be discussed next.
There's currently 0 information on how to integrate React with the Webcomponents being used by Appbridge, I kinda did, but because they contain an isolated shadowRoot, you get virtually a lot less customization, you can't even get a destructive button on the new ui-modal tag
We ran into a problem while planning our migration to App Bridge Modal. Our application relies on modules that run in modal windows, such as a resource picker. This is an extended version of it that allows you to select a lot of different resources such as orders, pages, metafield definitions, etc. And it seems that this is a good practice, given the similar things in the Shopify admin panel and the App Bridge itself. But it seems that the current modal API of App Bridge is not able to meet our needs without using complex iframes and a lot of magic and crutches.
We're not sure how this aligns with your new approach to app development. If we could embed JSX content in modal elements, that might solve the problem, but we don't see a clear solution to this problem right now.
@charlesdobson mentioned React wrappers for modal elements, but there are still doubts about the effective use of JSX components. If we can't use the same Polaris components in new modalities, it won't allow us to implement our own resource picker. It seems that the only option is to create our own modal implementation, which adds complexity.
Moreover, the return to local modal versions seems inevitable, so it seems that the problem you are trying to solve with these changes may remain, because local versions of modal windows seem to be the only viable solution for this functionality.
We would be grateful for your thoughts and recommendations on this, as we want to comply with Shopify's requirements, but at the same time we can't afford to abandon our own implementations of the same resource pickers as it is an important part of the application.
Thanks ^^
Removal of those components makes studying user session recordings harder, as those App Bridge components cannot be recorded by tools like LogRocket or Hotjar. Especially Modal.
As someone who is using this for a completely unrelated project, I'm a bit concerned, because I have just enough experience with user interfaces to appreciate being able to offer my own customers a consistent user experience across all kinds of platforms throughout an entire ecosystem.
I can't possibly imagine that the only intended use case for Polaris is inside an IFrame on the Shopify website, especially since the Shopify Admin itself is literally Polaris.
I have no idea what AppBridge is and how to use it properly in a standalone application, or if that's even possible, but I'm starting to get the feeling it isn't. At the very least, a page explaining what all is going on and how to migrate for both Shopify Admin and standalone projects, or even just a link to this issue, would probably be a good idea.
Also, make sure you're importing Modal, not Model. It's still available in v12. You're welcome.
@alex-page It would be great to have a decision one way or another. We are now viewing any further investment in Polaris as a risk since we don't know if we can safely assume Polaris will be designed for anything besides the embedded use-case. I want to make sure I have clear guidance to offer my team. I understand that Shopify has its own priorities, but we just want to know where you are going to land so we don't further incur tech debt on Polaris.
I'll make my last case. You're not just here to serve what Shopify wants. All of us in the ecosystem pay Shopify one way or another for access to not just the APIs, but also this UI library. That should come with some responsibility of good stewardship on your end, and that means supporting the larger ecosystem's needs.
While most of the comments on this page have been understandably negative, I would like to appreciate @alex-page and the team for listening to us, and acting in the favour of the community so far. Thank you!