Merge pull request #447 from Shopify/further_docs_improvements

Further improvements to Remix package docs

.changeset/small-masks-try.md

@@ -0,0 +1,2 @@
+---
+---

packages/shopify-app-remix/docs/generated/generated_static_pages.json

@@ -24,7 +24,7 @@
         "type": "Generic",
         "anchorLink": "headers",
         "title": "Headers",
-        "sectionContent": "It's important to note that the authentication functions in this package rely on throwing Response objects, which must be handled in your Remix routes using them.\n\nTo do that, you can set up a [Remix `ErrorBoundary`](https://remix.run/docs/en/main/guides/errors). We provide some abstractions for the error and headers boundaries to make it easier for apps to set those up.\n\n> Tip: You can also add this to a layout if you want to authenticate more than one route.",
+        "sectionContent": "The OAuth process can't happen inside the admin iframe, and this package is capable of detecting that scenario and properly redirecting using the [Remix `ErrorBoundary`](https://remix.run/docs/en/main/guides/errors) export to set the correct headers for App Bridge.\n\nUse the abstractions provided by this package in your authenticated routes, to automatically set up the error and headers boundaries to redirect outside the iframe when needed.\n\n> Tip: You can also add this to a [Remix layout](https://remix.run/docs/en/main/file-conventions/route-files-v2) if you want to authenticate more than one route, but make sure to call the Shopify boundary methods whenever you need to add your own exports.",
         "codeblock": {
           "title": "/app/routes/**/*.tsx",
           "tabs": [
@@ -105,34 +105,63 @@
   {
     "id": "shopify-app-remix",
     "title": "Shopify App package for Remix",
-    "description": "The @shopify/shopify-app-remix package enables Remix apps to authenticate with Shopify and make API calls. It uses [App Bridge](/docs/api/app-bridge-library) to enable apps to embed themselves in the Shopify Admin.\n\nIn this page we'll go over the main components you need to integrate an app with Shopify.\n\n> Tip: The quickest way to create a new app is using the Shopify CLI. Check out the [getting started guide](/docs/apps/getting-started/create), or the [app template](https://github.com/Shopify/shopify-app-template-remix) for a complete example.",
+    "description": "The [@shopify/shopify-app-remix](https://www.npmjs.com/package/@shopify/shopify-app-remix) package enables Remix apps to authenticate with Shopify and make API calls. It uses [App Bridge](/docs/api/app-bridge-library) to enable apps to embed themselves in the Shopify Admin.\n\nIn this page we'll go over the main components you need to integrate an app with Shopify.",
     "sections": [
       {
         "type": "Generic",
-        "anchorLink": "installation",
-        "title": "Installation",
-        "sectionContent": "If you're not using the CLI, then you can use the examples in this page to set up an existing app to use this package. Start by installing it using your preferred package manager.",
+        "anchorLink": "quick-start",
+        "title": "Quick start",
+        "sectionContent": "The quickest way to create a new app is using the Shopify CLI. You can use your preferred package manager for that.\n\nCheck out the [getting started guide](/docs/apps/getting-started), or the [app template](https://github.com/Shopify/shopify-app-template-remix) for a complete example.",
+        "codeblock": {
+          "title": "Create an app",
+          "tabs": [
+            {
+              "title": "npm",
+              "language": "sh",
+              "code": "npm init @shopify/app@latest\n"
+            },
+            {
+              "title": "yarn",
+              "language": "sh",
+              "code": "yarn create @shopify/app\n"
+            },
+            {
+              "title": "pnpm",
+              "language": "sh",
+              "code": "pnpm create @shopify/app\n"
+            }
+          ]
+        },
         "sectionCard": [
           {
             "name": "Build an app",
             "subtitle": "Navigate to",
             "url": "/docs/apps/getting-started/build-qr-code-app",
             "type": "tutorial"
           }
-        ],
+        ]
+      },
+      {
+        "type": "Generic",
+        "anchorLink": "installation",
+        "title": "Installation",
+        "sectionContent": "If you're not using the CLI, then you can use the examples in this page to set up an existing app to use this package. Start by installing it using your preferred package manager.",
         "codeblock": {
           "title": "Install package",
           "tabs": [
             {
               "title": "npm",
+              "language": "sh",
               "code": "npm i --save @shopify/shopify-app-remix\n"
             },
             {
               "title": "yarn",
+              "language": "sh",
               "code": "yarn add @shopify/shopify-app-remix\n"
             },
             {
               "title": "pnpm",
+              "language": "sh",
               "code": "pnpm add @shopify/shopify-app-remix\n"
             }
           ]
@@ -142,7 +171,7 @@
         "type": "Generic",
         "anchorLink": "shopify-app",
         "title": "Backend setup",
-        "sectionContent": "All of the backend features provided by this package are available through the `shopifyApp` function.\n\nThis function creates an object that can authenticate requests from Shopify, create contexts for non-Shopify requests, and much more.\n\n> Caution: When running on a node environment, you'll also need to import the node adapter, as per the example.",
+        "sectionContent": "Using the `shopifyApp` function, you can create an object that enables your app's backend to authenticate requests coming from Shopify, and interacting with Shopify APIs.\n\nThese functions make it easy for your app stays up to date, benefitting from the current best practices and security updates.\n\n> Caution: When running on a node environment, you'll also need to import the node adapter, as per the example. This will ensure your app is using the appropriate implementation of the Web [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and [crypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) APIs.",
         "sectionCard": [
           {
             "name": "shopifyApp",
@@ -181,7 +210,7 @@
         "type": "Generic",
         "anchorLink": "boundaries",
         "title": "Error boundaries",
-        "sectionContent": "The authentication functions in this package rely on throwing `Response` objects, which must be handled in your Remix routes using them.\n\nTo do that, you can set up a [Remix `ErrorBoundary`](https://remix.run/docs/en/main/guides/errors). We provide some abstractions for the error and headers boundaries to make it easier for apps to set those up.\n\n> Tip: You can also add this to a [Remix layout](https://remix.run/docs/en/main/file-conventions/route-files-v2) if you want to authenticate more than one route.",
+        "sectionContent": "The OAuth process can't happen inside the admin iframe, and this package is capable of detecting that scenario and properly redirecting using the [Remix `ErrorBoundary`](https://remix.run/docs/en/main/guides/errors) export to set the correct headers for App Bridge.\n\nUse the abstractions provided by this package in your authenticated routes, to automatically set up the error and headers boundaries to redirect outside the iframe when needed.\n\n> Tip: You can also add this to a [Remix layout](https://remix.run/docs/en/main/file-conventions/route-files-v2) if you want to authenticate more than one route, but make sure to call the Shopify boundary methods whenever you need to add your own exports.",
         "codeblock": {
           "title": "/app/routes/**/*.tsx",
           "tabs": [

packages/shopify-app-remix/docs/staticPages/admin.doc.ts

@@ -33,9 +33,9 @@ const data: LandingTemplateSchema = {
       anchorLink: 'headers',
       title: 'Headers',
       sectionContent:
-        "It's important to note that the authentication functions in this package rely on throwing Response objects, which must be handled in your Remix routes using them." +
-        '\n\nTo do that, you can set up a [Remix `ErrorBoundary`](https://remix.run/docs/en/main/guides/errors). We provide some abstractions for the error and headers boundaries to make it easier for apps to set those up.' +
-        '\n\n> Tip: You can also add this to a layout if you want to authenticate more than one route.',
+        "The OAuth process can't happen inside the admin iframe, and this package is capable of detecting that scenario and properly redirecting using the [Remix `ErrorBoundary`](https://remix.run/docs/en/main/guides/errors) export to set the correct headers for App Bridge." +
+        "\n\nUse the abstractions provided by this package in your authenticated routes, to automatically set up the error and headers boundaries to redirect outside the iframe when needed." +
+        "\n\n> Tip: You can also add this to a [Remix layout](https://remix.run/docs/en/main/file-conventions/route-files-v2) if you want to authenticate more than one route, but make sure to call the Shopify boundary methods whenever you need to add your own exports.",
       codeblock: {
         title: '/app/routes/**/*.tsx',
         tabs: [

packages/shopify-app-remix/docs/staticPages/examples/index/create.npm.example.sh

@@ -0,0 +1 @@
+npm init @shopify/app@latest

packages/shopify-app-remix/docs/staticPages/examples/index/create.pnpm.example.sh

@@ -0,0 +1 @@
+pnpm create @shopify/app

packages/shopify-app-remix/docs/staticPages/examples/index/create.yarn.example.sh

@@ -0,0 +1 @@
+yarn create @shopify/app

packages/shopify-app-remix/docs/staticPages/index.doc.ts

@@ -4,16 +4,36 @@ const data: LandingTemplateSchema = {
   id: 'shopify-app-remix',
   title: 'Shopify App package for Remix',
   description:
-    'The @shopify/shopify-app-remix package enables Remix apps to authenticate with Shopify and make API calls. It uses [App Bridge](/docs/api/app-bridge-library) to enable apps to embed themselves in the Shopify Admin.' +
-    "\n\nIn this page we'll go over the main components you need to integrate an app with Shopify." +
-    '\n\n> Tip: The quickest way to create a new app is using the Shopify CLI. Check out the [getting started guide](/docs/apps/getting-started/create), or the [app template](https://github.com/Shopify/shopify-app-template-remix) for a complete example.',
+    'The [@shopify/shopify-app-remix](https://www.npmjs.com/package/@shopify/shopify-app-remix) package enables Remix apps to authenticate with Shopify and make API calls. It uses [App Bridge](/docs/api/app-bridge-library) to enable apps to embed themselves in the Shopify Admin.' +
+    "\n\nIn this page we'll go over the main components you need to integrate an app with Shopify.",
   sections: [
     {
       type: 'Generic',
-      anchorLink: 'installation',
-      title: 'Installation',
+      anchorLink: 'quick-start',
+      title: 'Quick start',
       sectionContent:
-        "If you're not using the CLI, then you can use the examples in this page to set up an existing app to use this package. Start by installing it using your preferred package manager.",
+        "The quickest way to create a new app is using the Shopify CLI. You can use your preferred package manager for that." +
+        "\n\nCheck out the [getting started guide](/docs/apps/getting-started), or the [app template](https://github.com/Shopify/shopify-app-template-remix) for a complete example.",
+      codeblock: {
+        title: 'Create an app',
+        tabs: [
+          {
+            title: 'npm',
+            language: 'sh',
+            code: './examples/index/create.npm.example.sh',
+          },
+          {
+            title: 'yarn',
+            language: 'sh',
+            code: './examples/index/create.yarn.example.sh',
+          },
+          {
+            title: 'pnpm',
+            language: 'sh',
+            code: './examples/index/create.pnpm.example.sh',
+          },
+        ],
+      },
       sectionCard: [
         {
           name: 'Build an app',
@@ -22,19 +42,29 @@ const data: LandingTemplateSchema = {
           type: 'tutorial',
         },
       ],
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'installation',
+      title: 'Installation',
+      sectionContent:
+        "If you're not using the CLI, then you can use the examples in this page to set up an existing app to use this package. Start by installing it using your preferred package manager.",
       codeblock: {
         title: 'Install package',
         tabs: [
           {
             title: 'npm',
+            language: 'sh',
             code: './examples/index/install.npm.example.sh',
           },
           {
             title: 'yarn',
+            language: 'sh',
             code: './examples/index/install.yarn.example.sh',
           },
           {
             title: 'pnpm',
+            language: 'sh',
             code: './examples/index/install.pnpm.example.sh',
           },
         ],
@@ -45,9 +75,9 @@ const data: LandingTemplateSchema = {
       anchorLink: 'shopify-app',
       title: 'Backend setup',
       sectionContent:
-        'All of the backend features provided by this package are available through the `shopifyApp` function.' +
-        '\n\nThis function creates an object that can authenticate requests from Shopify, create contexts for non-Shopify requests, and much more.' +
-        "\n\n> Caution: When running on a node environment, you'll also need to import the node adapter, as per the example.",
+        "Using the `shopifyApp` function, you can create an object that enables your app's backend to authenticate requests coming from Shopify, and interacting with Shopify APIs." +
+        "\n\nThese functions make it easy for your app stays up to date, benefitting from the current best practices and security updates." +
+        "\n\n> Caution: When running on a node environment, you'll also need to import the node adapter, as per the example. This will ensure your app is using the appropriate implementation of the Web [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and [crypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) APIs.",
       sectionCard: [
         {
           name: 'shopifyApp',
@@ -89,9 +119,9 @@ const data: LandingTemplateSchema = {
       anchorLink: 'boundaries',
       title: 'Error boundaries',
       sectionContent:
-        'The authentication functions in this package rely on throwing `Response` objects, which must be handled in your Remix routes using them.' +
-        '\n\nTo do that, you can set up a [Remix `ErrorBoundary`](https://remix.run/docs/en/main/guides/errors). We provide some abstractions for the error and headers boundaries to make it easier for apps to set those up.' +
-        '\n\n> Tip: You can also add this to a [Remix layout](https://remix.run/docs/en/main/file-conventions/route-files-v2) if you want to authenticate more than one route.',
+        "The OAuth process can't happen inside the admin iframe, and this package is capable of detecting that scenario and properly redirecting using the [Remix `ErrorBoundary`](https://remix.run/docs/en/main/guides/errors) export to set the correct headers for App Bridge." +
+        "\n\nUse the abstractions provided by this package in your authenticated routes, to automatically set up the error and headers boundaries to redirect outside the iframe when needed." +
+        "\n\n> Tip: You can also add this to a [Remix layout](https://remix.run/docs/en/main/file-conventions/route-files-v2) if you want to authenticate more than one route, but make sure to call the Shopify boundary methods whenever you need to add your own exports.",
       codeblock: {
         title: '/app/routes/**/*.tsx',
         tabs: [

packages/shopify-app-remix/package.json

@@ -51,7 +51,7 @@
   ],
   "devDependencies": {
     "@remix-run/react": "^1.19.0",
-    "@shopify/generate-docs": "^0.11.0",
+    "@shopify/generate-docs": "^0.11.1",
     "@shopify/polaris": "^11.8.0",
     "@shopify/react-testing": "^5.1.3",
     "@shopify/shopify-app-session-storage-memory": "^1.0.12",

packages/shopify-app-remix/src/react/components/AppProvider/AppProvider.doc.ts

@@ -9,12 +9,12 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   definitions: [
     {
-      title: 'props',
-      description: 'React component that sets up App Bridge and Polaris.',
-      type: 'AppProviderGeneratedType',
-      jsDocExamples: true,
+      title: 'AppProviderProps',
+      description: 'Props for the `AppProvider` component.',
+      type: 'AppProviderProps',
     },
   ],
+  jsDocTypeExamples: ['AppProviderGeneratedType'],
   related: [
     {
       name: 'App bridge',

packages/shopify-app-remix/src/react/components/AppProvider/AppProvider.tsx

@@ -46,7 +46,8 @@ export interface AppProviderProps
  * {@link https://shopify.dev/tools/app-bridge}
  *
  * @example
- * <caption>Wrap your app in the `AppProvider` component and pass in your API key.</caption>
+ * <caption>Set up AppProvider.</caption>
+ * <description>Wrap your app in the `AppProvider` component and pass in your API key.</description>
  * ```ts
  * import {authenticate} from '~/shopify.server';
  * import {AppProvider} from '@shopify/shopify-app-remix/react';
@@ -69,7 +70,8 @@ export interface AppProviderProps
  * ```
  *
  * @example
- * <caption>Load a different locale for Polaris.</caption>
+ * <caption>Localize Polaris components.</caption>
+ * <description>Pass in a different locale for Polaris to translate its components.</description>
  * ```ts
  * import {authenticate} from '~/shopify.server';
  * import {AppProvider} from '@shopify/shopify-app-remix/react';

packages/shopify-app-remix/src/server/authenticate/admin/authenticate.admin.api.doc.ts

@@ -14,9 +14,9 @@ const data: ReferenceEntityTemplateSchema = {
       description:
         'Provides utilities that apps can use to make requests to the Admin API.',
       type: 'AdminApiContext',
-      jsDocExamples: true,
     },
   ],
+  jsDocTypeExamples: ['AdminApiContext'],
   related: [
     {
       name: 'Authenticated context',

packages/shopify-app-remix/src/server/authenticate/admin/authenticate.admin.billing.doc.ts

@@ -3,7 +3,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 const data: ReferenceEntityTemplateSchema = {
   name: 'Billing',
   description:
-    'Contains function used to bill merchants for your app.\n\nThis object is returned on authenticated Admin requests. Refer to the [Related](#related) section for more information.',
+    'Contains function used to bill merchants for your app.\n\nThis object is returned on authenticated Admin requests.',
   category: 'APIs',
   type: 'object',
   isVisualComponent: false,
@@ -13,9 +13,9 @@ const data: ReferenceEntityTemplateSchema = {
       description:
         'Provides utilities that apps can use to request billing for the app using the Admin API.',
       type: 'BillingContext',
-      jsDocExamples: true,
     },
   ],
+  jsDocTypeExamples: ['BillingContext'],
   related: [
     {
       name: 'Admin context',

packages/shopify-app-remix/src/server/authenticate/admin/authenticate.admin.doc.ts

@@ -3,7 +3,7 @@ import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 const data: ReferenceEntityTemplateSchema = {
   name: 'Admin',
   description:
-    'Contains functions for authenticating and interacting with the Admin API.\n\nThis function can handle requests for apps embedded in the Admin, Admin extensions, or non-embedded apps.\n\nRefer to the [Related](#related) section to see all supported actions in `admin` and `billing`.',
+    'Contains functions for authenticating and interacting with the Admin API.\n\nThis function can handle requests for apps embedded in the Admin, Admin extensions, or non-embedded apps.',
   category: 'Authenticate',
   type: 'object',
   isVisualComponent: false,
@@ -14,24 +14,11 @@ const data: ReferenceEntityTemplateSchema = {
         'Authenticates requests coming from the Shopify admin.\n\nThe shape of the returned object changes depending on the `isEmbeddedApp` config.',
       type: 'AuthenticateAdmin',
     },
-    {
-      title: 'AdminContext',
-      description: 'Object returned by `authenticate.admin`.',
-      type: 'EmbeddedAdminContext',
-      jsDocExamples: true,
-    },
-    {
-      title: 'AdminApiContext',
-      description: 'Components of the `admin` response object.',
-      type: 'AdminApiContext',
-      jsDocExamples: true,
-    },
-    {
-      title: 'BillingContext',
-      description: 'Components of the `billing` response object.',
-      type: 'BillingContext',
-      jsDocExamples: true,
-    },
+  ],
+  jsDocTypeExamples: [
+    'EmbeddedAdminContext',
+    'AdminApiContext',
+    'BillingContext',
   ],
   related: [
     {