docs: generate medusa-react reference (#6004)

* add new plugin for better organization * added handling in theme for mutations and query types * added tsdoc to hooks * added tsdocs to utility functions * added tsdoc to providers * generated reference * general fixes for generated reference * generated api reference specs + general fixes * add missing import react * split utilities into different directories * added overview page * added link to customer authentication section * fix lint errors * added changeset * fix readme * fixed build error * added expand fields + other sections to overview * updated what's new section * general refactoring * remove unnecessary query field * fix links * added ignoreApi option
2024-01-05 17:03:38 +02:00
parent 6fc6a9de6a
commit 7d650771d1
2811 changed files with 231856 additions and 455063 deletions
@@ -0,0 +1,93 @@
+---
+displayed_sidebar: medusaReactSidebar
+slug: /references/medusa-react/providers/medusa
+sidebar_label: Medusa
+---
+
+import ParameterTypes from "@site/src/components/ParameterTypes"
+
+# Medusa  Provider Overview
+
+## MedusaProvider
+
+The `MedusaProvider` must be used at the highest possible point in the React component tree. Using any of `medusa-react`'s hooks or providers requires having `MedusaProvider`
+higher in the component tree.
+
+### Example
+
+```tsx title="src/App.ts"
+import { MedusaProvider } from "medusa-react"
+import Storefront from "./Storefront"
+import { QueryClient } from "@tanstack/react-query"
+import React from "react"
+
+const queryClient = new QueryClient()
+
+const App = () => {
+  return (
+    <MedusaProvider
+      queryClientProviderProps={{ client: queryClient }}
+      baseUrl="http://localhost:9000"
+    >
+      <Storefront />
+    </MedusaProvider>
+  )
+}
+
+export default App
+```
+
+In the example above, you wrap the `Storefront` component with the `MedusaProvider`. `Storefront` is assumed to be the top-level component of your storefront, but you can place `MedusaProvider` at any point in your tree. Only children of `MedusaProvider` can benefit from its hooks.
+
+The `Storefront` component and its child components can now use hooks exposed by Medusa React.
+
+### Parameters
+
+<ParameterTypes parameters={[{"name":"param0","type":"[MedusaProviderProps](../interfaces/medusa_react.MedusaProviderProps.mdx)","description":"Props of the provider.","optional":false,"defaultValue":"","expandable":false,"children":[{"name":"baseUrl","type":"`string`","description":"The URL to your Medusa backend.","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"queryClientProviderProps","type":"`QueryClientProviderProps`","description":"An object used to set the Tanstack Query client. The object requires a `client` property, \nwhich should be an instance of [QueryClient](https://tanstack.com/query/v4/docs/react/reference/QueryClient).","optional":false,"defaultValue":"","expandable":false,"children":[]},{"name":"apiKey","type":"`string`","description":"API key used for authenticating admin requests. Follow [this guide](https://docs.medusajs.com/api/admin#authentication) to learn how to create an API key for an admin user.","optional":true,"defaultValue":"","expandable":false,"children":[]},{"name":"customHeaders","type":"`Record<string, any>`","description":"An object of custom headers to pass with every request. Each key of the object is the name of the header, and its value is the header's value.","optional":true,"defaultValue":"`{}`","expandable":false,"children":[]},{"name":"maxRetries","type":"`number`","description":"Number of times to retry a request if it fails.","optional":true,"defaultValue":"3","expandable":false,"children":[]},{"name":"publishableApiKey","type":"`string`","description":"Publishable API key used for storefront requests. You can create a publishable API key either using the \n[admin APIs](https://docs.medusajs.com/development/publishable-api-keys/admin/manage-publishable-api-keys) or the \n[Medusa admin](https://docs.medusajs.com/user-guide/settings/publishable-api-keys#create-publishable-api-key).","optional":true,"defaultValue":"","expandable":false,"children":[]}]}]} expandUrl="https://docs.medusajs.com/medusa-react/overview#expanding-fields"/>
+
+### Returns
+
+<ParameterTypes parameters={[{"name":"Element","type":"`Element`","optional":false,"defaultValue":"","description":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/medusa-react/overview#expanding-fields"/>
+
+___
+
+## useMedusa
+
+This hook gives you access to context of [MedusaProvider](medusa_react.Providers.Medusa.mdx#medusaprovider). It's useful if you want access to the 
+[Medusa JS Client](https://docs.medusajs.com/js-client/overview).
+
+### Example
+
+```ts
+import React from "react"
+import { useMeCustomer, useMedusa } from "medusa-react"
+
+const CustomerLogin = () => {
+  const { client } = useMedusa()
+  const { refetch: refetchCustomer } = useMeCustomer()
+  // ...
+
+  const handleLogin = (
+    email: string,
+    password: string
+  ) => {
+    client.auth.authenticate({
+      email,
+      password
+    })
+    .then(() => {
+      // customer is logged-in successfully
+      refetchCustomer()
+    })
+    .catch(() => {
+      // an error occurred.
+    })
+  }
+
+  // ...
+}
+```
+
+### Returns
+
+<ParameterTypes parameters={[{"name":"client","type":"`Medusa`","description":"The Medusa JS Client instance.","optional":false,"defaultValue":"","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/medusa-react/overview#expanding-fields"/>