Merge pull request #994 from Shopify/update-docs

Add deprecation notice and migration guide
Shopify · Dec 4, 2024 · 2fb158f · 2fb158f
2 parents 39a39b8 + b09004a
commit 2fb158f
Show file tree

Hide file tree

Showing 65 changed files with 4,081 additions and 621 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,19 @@
 # Changelog
 
+## Deprecation notice
+
+**The JS Buy SDK is deprecated as of January, 2025.** It will no longer be updated or maintained by Shopify past that point. A final major version will be released by the end of 2024 to remove the SDK's dependency on the [deprecated Checkout APIs](https://shopify.dev/changelog/deprecation-of-checkout-apis), replacing them with [Cart APIs](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart). Updating to this new version will allow the SDK to continue to function for most use cases.
+
+If you are using the JS Buy SDK, you have two options:
+
+1. Recommended Option: switch to the [Storefront API Client](https://github.com/Shopify/shopify-app-js/tree/main/packages/api-clients/storefront-api-client#readme)
+  a. The Storefront API Client manages the API's authentication information and provides various methods that enable devs to interact with the API. This is the preferred and more future-proof solution. See this [migration guide](./migration-guide) to help you transition.
+
+2. Stopgap Option: Upgrade to JS Buy SDK V3 (coming soon)
+  a. This allows you to maintain your current setup with minimal changes for use cases that are supported by the Cart API. A migration guide with details on supported use cases will be available soon. If you choose this option, we still recommend that you switch to the Storefront API Client in the future.
+
+**Critical Deadline: July 1st, 2025.** You must implement one of these changes by this date, or customers will not be able to complete purchases. Please choose the option that best suits your needs and timelines.
+
 ### v2.22.0 (May 1, 2024)
 * Bumps the SDK to use Storefront API version `2024-04`. For more information, see the [Release Notes](https://shopify.dev/api/release-notes/2024-04).
 

diff --git a/README.md b/README.md
@@ -1,3 +1,17 @@
+# Deprecation notice
+
+**Note: The JS Buy SDK is deprecated as of January, 2025.** It will no longer be updated or maintained by Shopify past that point. A final major version will be released by the end of 2024 to remove the SDK's dependency on the [deprecated Checkout APIs](https://shopify.dev/changelog/deprecation-of-checkout-apis), replacing them with [Cart APIs](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart). Updating to this new version will allow the SDK to continue to function for most use cases.
+
+If you are using the JS Buy SDK, you have two options:
+
+1. Recommended Option: switch to the [Storefront API Client](https://github.com/Shopify/shopify-app-js/tree/main/packages/api-clients/storefront-api-client#readme)
+  a. The Storefront API Client manages the API's authentication information and provides various methods that enable devs to interact with the API. This is the preferred and more future-proof solution. See this [migration guide](./migration-guide) to help you transition.
+
+2. Stopgap Option: Upgrade to JS Buy SDK V3 (coming soon)
+  a. This allows you to maintain your current setup with minimal changes for use cases that are supported by the Cart API. A migration guide with details on supported use cases will be available soon. If you choose this option, we still recommend that you switch to the Storefront API Client in the future.
+
+**Critical Deadline: July 1st, 2025.** You must implement one of these changes by this date, or customers will not be able to complete purchases. Please choose the option that best suits your needs and timelines.
+
 # [Shopify](https://www.shopify.com) JavaScript Buy SDK
 ![Build](https://github.com/shopify/js-buy-sdk/actions/workflows/ci.yml/badge.svg)
 

diff --git a/docs/CheckoutResource.html b/docs/CheckoutResource.html
@@ -11,13 +11,39 @@
     <![endif]-->
     <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
     <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
+    <style>
+    /* Hide the deprecation notice on the home page so we don't double up  */
+    body.home blockquote:nth-of-type(1), body.home hr:nth-of-type(1) {
+      display: none;
+    }
+    /* Tidy headings */
+    section h1 {
+      margin-left: 0;
+    }
+    #deprecation-notice {
+      background-color: #fff9e3;
+      border: 1px solid #ff9900;
+      border-radius: 5px;
+      color: #333;
+      margin: 20px;
+      padding: 10px 20px;
+      font-family: Arial;
+    }
+    </style>
 </head>
 
-<body>
+<body class="class: checkoutresource">
+
+
 
 <div id="main">
+    <div id="deprecation-notice">
+      <strong>The JS Buy SDK is deprecated as of January, 2025.</strong> For more information, please see the <a href="https://github.com/Shopify/js-buy-sdk/blob/main/README.md" target="_blank">README</a>.
+    </div>
 
-    <h1 class="page-title">Class: CheckoutResource</h1>
+
+      <h1 class="page-title">Class: CheckoutResource</h1>
+
 
 
 
@@ -3026,13 +3052,13 @@ <h5>Example</h5>
 </div>
 
 <nav>
-    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="ImageHelpers.html">ImageHelpers</a></li><li><a href="ProductHelpers.html">ProductHelpers</a></li></ul><h3>Classes</h3><ul><li><a href="CheckoutResource.html">CheckoutResource</a></li><li><a href="Client.html">Client</a></li><li><a href="CollectionResource.html">CollectionResource</a></li><li><a href="Config.html">Config</a></li><li><a href="ImageResource.html">ImageResource</a></li><li><a href="ProductResource.html">ProductResource</a></li><li><a href="ShopResource.html">ShopResource</a></li></ul><h3>Tutorials</h3><ul><li><a href="tutorial-MIGRATION_GUIDE.html">MIGRATION_GUIDE</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="ImageHelpers.html">ImageHelpers</a></li><li><a href="ProductHelpers.html">ProductHelpers</a></li></ul><h3>Classes</h3><ul><li><a href="CheckoutResource.html">CheckoutResource</a></li><li><a href="Client.html">Client</a></li><li><a href="CollectionResource.html">CollectionResource</a></li><li><a href="Config.html">Config</a></li><li><a href="ImageResource.html">ImageResource</a></li><li><a href="ProductResource.html">ProductResource</a></li><li><a href="ShopResource.html">ShopResource</a></li></ul>
 </nav>
 
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Wed May 01 2024 10:19:56 GMT-0400 (Eastern Daylight Time)
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Tue Dec 03 2024 13:47:23 GMT-0500 (Eastern Standard Time)
 </footer>
 
 <script> prettyPrint(); </script>

diff --git a/docs/Client.html b/docs/Client.html
@@ -11,13 +11,39 @@
     <![endif]-->
     <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
     <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
+    <style>
+    /* Hide the deprecation notice on the home page so we don't double up  */
+    body.home blockquote:nth-of-type(1), body.home hr:nth-of-type(1) {
+      display: none;
+    }
+    /* Tidy headings */
+    section h1 {
+      margin-left: 0;
+    }
+    #deprecation-notice {
+      background-color: #fff9e3;
+      border: 1px solid #ff9900;
+      border-radius: 5px;
+      color: #333;
+      margin: 20px;
+      padding: 10px 20px;
+      font-family: Arial;
+    }
+    </style>
 </head>
 
-<body>
+<body class="class: client">
+
+
 
 <div id="main">
+    <div id="deprecation-notice">
+      <strong>The JS Buy SDK is deprecated as of January, 2025.</strong> For more information, please see the <a href="https://github.com/Shopify/js-buy-sdk/blob/main/README.md" target="_blank">README</a>.
+    </div>
 
-    <h1 class="page-title">Class: Client</h1>
+
+      <h1 class="page-title">Class: Client</h1>
+
 
 
 
@@ -621,13 +647,13 @@ <h5>Example</h5>
 </div>
 
 <nav>
-    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="ImageHelpers.html">ImageHelpers</a></li><li><a href="ProductHelpers.html">ProductHelpers</a></li></ul><h3>Classes</h3><ul><li><a href="CheckoutResource.html">CheckoutResource</a></li><li><a href="Client.html">Client</a></li><li><a href="CollectionResource.html">CollectionResource</a></li><li><a href="Config.html">Config</a></li><li><a href="ImageResource.html">ImageResource</a></li><li><a href="ProductResource.html">ProductResource</a></li><li><a href="ShopResource.html">ShopResource</a></li></ul><h3>Tutorials</h3><ul><li><a href="tutorial-MIGRATION_GUIDE.html">MIGRATION_GUIDE</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="ImageHelpers.html">ImageHelpers</a></li><li><a href="ProductHelpers.html">ProductHelpers</a></li></ul><h3>Classes</h3><ul><li><a href="CheckoutResource.html">CheckoutResource</a></li><li><a href="Client.html">Client</a></li><li><a href="CollectionResource.html">CollectionResource</a></li><li><a href="Config.html">Config</a></li><li><a href="ImageResource.html">ImageResource</a></li><li><a href="ProductResource.html">ProductResource</a></li><li><a href="ShopResource.html">ShopResource</a></li></ul>
 </nav>
 
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Wed May 01 2024 10:19:56 GMT-0400 (Eastern Daylight Time)
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Tue Dec 03 2024 13:47:23 GMT-0500 (Eastern Standard Time)
 </footer>
 
 <script> prettyPrint(); </script>

diff --git a/docs/CollectionResource.html b/docs/CollectionResource.html
@@ -11,13 +11,39 @@
     <![endif]-->
     <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
     <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
+    <style>
+    /* Hide the deprecation notice on the home page so we don't double up  */
+    body.home blockquote:nth-of-type(1), body.home hr:nth-of-type(1) {
+      display: none;
+    }
+    /* Tidy headings */
+    section h1 {
+      margin-left: 0;
+    }
+    #deprecation-notice {
+      background-color: #fff9e3;
+      border: 1px solid #ff9900;
+      border-radius: 5px;
+      color: #333;
+      margin: 20px;
+      padding: 10px 20px;
+      font-family: Arial;
+    }
+    </style>
 </head>
 
-<body>
+<body class="class: collectionresource">
+
+
 
 <div id="main">
+    <div id="deprecation-notice">
+      <strong>The JS Buy SDK is deprecated as of January, 2025.</strong> For more information, please see the <a href="https://github.com/Shopify/js-buy-sdk/blob/main/README.md" target="_blank">README</a>.
+    </div>
 
-    <h1 class="page-title">Class: CollectionResource</h1>
+
+      <h1 class="page-title">Class: CollectionResource</h1>
+
 
 
 
@@ -1272,13 +1298,13 @@ <h5>Example</h5>
 </div>
 
 <nav>
-    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="ImageHelpers.html">ImageHelpers</a></li><li><a href="ProductHelpers.html">ProductHelpers</a></li></ul><h3>Classes</h3><ul><li><a href="CheckoutResource.html">CheckoutResource</a></li><li><a href="Client.html">Client</a></li><li><a href="CollectionResource.html">CollectionResource</a></li><li><a href="Config.html">Config</a></li><li><a href="ImageResource.html">ImageResource</a></li><li><a href="ProductResource.html">ProductResource</a></li><li><a href="ShopResource.html">ShopResource</a></li></ul><h3>Tutorials</h3><ul><li><a href="tutorial-MIGRATION_GUIDE.html">MIGRATION_GUIDE</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="ImageHelpers.html">ImageHelpers</a></li><li><a href="ProductHelpers.html">ProductHelpers</a></li></ul><h3>Classes</h3><ul><li><a href="CheckoutResource.html">CheckoutResource</a></li><li><a href="Client.html">Client</a></li><li><a href="CollectionResource.html">CollectionResource</a></li><li><a href="Config.html">Config</a></li><li><a href="ImageResource.html">ImageResource</a></li><li><a href="ProductResource.html">ProductResource</a></li><li><a href="ShopResource.html">ShopResource</a></li></ul>
 </nav>
 
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Wed May 01 2024 10:19:56 GMT-0400 (Eastern Daylight Time)
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Tue Dec 03 2024 13:47:23 GMT-0500 (Eastern Standard Time)
 </footer>
 
 <script> prettyPrint(); </script>

diff --git a/docs/Config.html b/docs/Config.html
@@ -11,13 +11,39 @@
     <![endif]-->
     <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
     <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
+    <style>
+    /* Hide the deprecation notice on the home page so we don't double up  */
+    body.home blockquote:nth-of-type(1), body.home hr:nth-of-type(1) {
+      display: none;
+    }
+    /* Tidy headings */
+    section h1 {
+      margin-left: 0;
+    }
+    #deprecation-notice {
+      background-color: #fff9e3;
+      border: 1px solid #ff9900;
+      border-radius: 5px;
+      color: #333;
+      margin: 20px;
+      padding: 10px 20px;
+      font-family: Arial;
+    }
+    </style>
 </head>
 
-<body>
+<body class="class: config">
+
+
 
 <div id="main">
+    <div id="deprecation-notice">
+      <strong>The JS Buy SDK is deprecated as of January, 2025.</strong> For more information, please see the <a href="https://github.com/Shopify/js-buy-sdk/blob/main/README.md" target="_blank">README</a>.
+    </div>
 
-    <h1 class="page-title">Class: Config</h1>
+
+      <h1 class="page-title">Class: Config</h1>
+
 
 
 
@@ -276,13 +302,13 @@ <h6>Properties</h6>
 </div>
 
 <nav>
-    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="ImageHelpers.html">ImageHelpers</a></li><li><a href="ProductHelpers.html">ProductHelpers</a></li></ul><h3>Classes</h3><ul><li><a href="CheckoutResource.html">CheckoutResource</a></li><li><a href="Client.html">Client</a></li><li><a href="CollectionResource.html">CollectionResource</a></li><li><a href="Config.html">Config</a></li><li><a href="ImageResource.html">ImageResource</a></li><li><a href="ProductResource.html">ProductResource</a></li><li><a href="ShopResource.html">ShopResource</a></li></ul><h3>Tutorials</h3><ul><li><a href="tutorial-MIGRATION_GUIDE.html">MIGRATION_GUIDE</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="ImageHelpers.html">ImageHelpers</a></li><li><a href="ProductHelpers.html">ProductHelpers</a></li></ul><h3>Classes</h3><ul><li><a href="CheckoutResource.html">CheckoutResource</a></li><li><a href="Client.html">Client</a></li><li><a href="CollectionResource.html">CollectionResource</a></li><li><a href="Config.html">Config</a></li><li><a href="ImageResource.html">ImageResource</a></li><li><a href="ProductResource.html">ProductResource</a></li><li><a href="ShopResource.html">ShopResource</a></li></ul>
 </nav>
 
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Wed May 01 2024 10:19:56 GMT-0400 (Eastern Daylight Time)
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Tue Dec 03 2024 13:47:23 GMT-0500 (Eastern Standard Time)
 </footer>
 
 <script> prettyPrint(); </script>

diff --git a/docs/ImageHelpers.html b/docs/ImageHelpers.html
@@ -11,13 +11,39 @@
     <![endif]-->
     <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
     <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
+    <style>
+    /* Hide the deprecation notice on the home page so we don't double up  */
+    body.home blockquote:nth-of-type(1), body.home hr:nth-of-type(1) {
+      display: none;
+    }
+    /* Tidy headings */
+    section h1 {
+      margin-left: 0;
+    }
+    #deprecation-notice {
+      background-color: #fff9e3;
+      border: 1px solid #ff9900;
+      border-radius: 5px;
+      color: #333;
+      margin: 20px;
+      padding: 10px 20px;
+      font-family: Arial;
+    }
+    </style>
 </head>
 
-<body>
+<body class="namespace: imagehelpers">
+
+
 
 <div id="main">
+    <div id="deprecation-notice">
+      <strong>The JS Buy SDK is deprecated as of January, 2025.</strong> For more information, please see the <a href="https://github.com/Shopify/js-buy-sdk/blob/main/README.md" target="_blank">README</a>.
+    </div>
 
-    <h1 class="page-title">Namespace: ImageHelpers</h1>
+
+      <h1 class="page-title">Namespace: ImageHelpers</h1>
+
 
 
 
@@ -379,13 +405,13 @@ <h5>Example</h5>
 </div>
 
 <nav>
-    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="ImageHelpers.html">ImageHelpers</a></li><li><a href="ProductHelpers.html">ProductHelpers</a></li></ul><h3>Classes</h3><ul><li><a href="CheckoutResource.html">CheckoutResource</a></li><li><a href="Client.html">Client</a></li><li><a href="CollectionResource.html">CollectionResource</a></li><li><a href="Config.html">Config</a></li><li><a href="ImageResource.html">ImageResource</a></li><li><a href="ProductResource.html">ProductResource</a></li><li><a href="ShopResource.html">ShopResource</a></li></ul><h3>Tutorials</h3><ul><li><a href="tutorial-MIGRATION_GUIDE.html">MIGRATION_GUIDE</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Namespaces</h3><ul><li><a href="ImageHelpers.html">ImageHelpers</a></li><li><a href="ProductHelpers.html">ProductHelpers</a></li></ul><h3>Classes</h3><ul><li><a href="CheckoutResource.html">CheckoutResource</a></li><li><a href="Client.html">Client</a></li><li><a href="CollectionResource.html">CollectionResource</a></li><li><a href="Config.html">Config</a></li><li><a href="ImageResource.html">ImageResource</a></li><li><a href="ProductResource.html">ProductResource</a></li><li><a href="ShopResource.html">ShopResource</a></li></ul>
 </nav>
 
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Wed May 01 2024 10:19:56 GMT-0400 (Eastern Daylight Time)
+    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Tue Dec 03 2024 13:47:23 GMT-0500 (Eastern Standard Time)
 </footer>
 
 <script> prettyPrint(); </script>