diff --git a/www/apps/api-reference/app/_mdx/client-libraries.mdx b/www/apps/api-reference/app/_mdx/client-libraries.mdx
index a722782bb5..335f8602b1 100644
--- a/www/apps/api-reference/app/_mdx/client-libraries.mdx
+++ b/www/apps/api-reference/app/_mdx/client-libraries.mdx
@@ -8,11 +8,15 @@ Check out the [Medusa v2 Documentation](https://docs.medusajs.com/v2).
-
+
Medusa JS SDK
-JavaScript client libraries are coming soon for Medusa v2.
+To use Medusa's JS SDK library, install the following packages in your project (not required for admin customizations):
-
+```bash
+npm install @medusajs/js-sdk@rc @medusajs/types@rc
+```
+
+Learn more about the JS SDK in [this documentation](https://docs.medusajs.com/v2/resources/js-sdk).
### Download Full Reference
diff --git a/www/apps/book/app/learn/advanced-development/admin/tips/page.mdx b/www/apps/book/app/learn/advanced-development/admin/tips/page.mdx
index 25d3bb0631..1975cc38aa 100644
--- a/www/apps/book/app/learn/advanced-development/admin/tips/page.mdx
+++ b/www/apps/book/app/learn/advanced-development/admin/tips/page.mdx
@@ -1,3 +1,5 @@
+import { CodeTabs, CodeTab } from "docs-ui"
+
export const metadata = {
title: `${pageNumber} Admin Development Tips`,
}
@@ -8,42 +10,64 @@ In this chapter, you'll find some tips for your admin development.
## Send Requests to API Routes
-To send a request to an API route in the Medusa Application, use the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch).
+To send a request to an API route in the Medusa Application, use Medusa's [JS SDK](!resources!/js-sdk) with [Tanstack Query](https://tanstack.com/query/latest). Both of these tools are installed in your project by default.
+
+First, create the file `src/admin/lib/config.ts` to setup the SDK for use in your customizations:
+
+```ts
+import Medusa from "@medusajs/js-sdk"
+
+export const sdk = new Medusa({
+ baseUrl: "http://localhost:9000",
+ debug: process.env.NODE_ENV === "development",
+ auth: {
+ type: "session",
+ },
+})
+```
+
+
+
+Learn more about the JS SDK's configurations [this documentation](!resources!/js-sdk#js-sdk-configurations).
+
+
+
+Then, use the configured SDK with the `useQuery` Tanstack Query hook to send `GET` requests, and `useMutation` hook to send `POST` or `DELETE` requests.
For example:
-export const fetchHighlights = [
- ["14", "fetch", "Send a request to the `/admin/products` API route."]
+
+
+
+export const queryHighlights = [
+ ["8", "useQuery", "Use Tanstack Query's `useQuery` to send a `GET` request."],
+ ["9", "sdk.admin.product.list", "Use the SDK to send the request."],
+ ["10", "queryKey", "Specify the key used to cache data."]
]
-```tsx title="src/admin/widgets/product-widget.tsx" highlights={fetchHighlights}
+```tsx title="src/admin/widgets/product-widget.ts" highlights={queryHighlights}
import { defineWidgetConfig } from "@medusajs/admin-sdk"
-import { Container } from "@medusajs/ui"
-import { useEffect, useState } from "react"
+import { Button, Container } from "@medusajs/ui"
+import { useQuery } from "@tanstack/react-query"
+import { sdk } from "../lib/config"
+import { DetailWidgetProps, HttpTypes } from "@medusajs/framework/types"
const ProductWidget = () => {
- const [productsCount, setProductsCount] = useState(0)
- const [loading, setLoading] = useState(true)
-
- useEffect(() => {
- if (!loading) {
- return
- }
-
- fetch(`/admin/products`, {
- credentials: "include",
- })
- .then((res) => res.json())
- .then(({ count }) => {
- setProductsCount(count)
- setLoading(false)
- })
- }, [loading])
-
+ const { data, isLoading } = useQuery({
+ queryFn: () => sdk.admin.product.list(),
+ queryKey: ["products"]
+ })
+
return (
- {loading && Loading...}
- {!loading && You have {productsCount} Product(s).}
+ {isLoading && Loading...}
+ {data?.products && (
+
+ {data.products.map((product) => (
+
{product.title}
+ ))}
+
+ )}
)
}
@@ -55,7 +79,52 @@ export const config = defineWidgetConfig({
export default ProductWidget
```
-In this example, you send a request to the [List Products API route](!api!/admin#products_getproducts) and show the count of products in a widget.
+
+
+
+export const mutationHighlights = [
+ ["10", "useMutation", "Use Tanstack Query's `useMutation` to send `POST` or `DELETE` requests."],
+ ["12", "sdk.admin.product.update", "Use the configured SDK to send the request."],
+]
+
+```tsx title="src/admin/widgets/product-widget.ts" highlights={mutationHighlights}
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Button, Container } from "@medusajs/ui"
+import { useMutation } from "@tanstack/react-query"
+import { sdk } from "../lib/config"
+import { DetailWidgetProps, HttpTypes } from "@medusajs/framework/types"
+
+const ProductWidget = ({
+ data: productData
+}: DetailWidgetProps) => {
+ const { mutateAsync } = useMutation({
+ mutationFn: (payload: HttpTypes.AdminUpdateProduct) =>
+ sdk.admin.product.update(productData.id, payload),
+ onSuccess: () => alert("updated product")
+ })
+
+ const handleUpdate = () => {
+ mutateAsync({
+ title: "New Product Title"
+ })
+ }
+
+ return (
+
+
+
+ )
+}
+
+export const config = defineWidgetConfig({
+ zone: "product.details.before",
+})
+
+export default ProductWidget
+```
+
+
+
---
diff --git a/www/apps/book/app/learn/storefront-development/page.mdx b/www/apps/book/app/learn/storefront-development/page.mdx
index e19cf131e3..14bc0e2fe9 100644
--- a/www/apps/book/app/learn/storefront-development/page.mdx
+++ b/www/apps/book/app/learn/storefront-development/page.mdx
@@ -10,7 +10,7 @@ You're free to choose how to build your storefront. You can start with our Next.
-To learn how to build a storefront from scratch, check out the [Storefront Development guides](!resources!/storefront-development) in the Development Resources documentation.
+To learn how to build a storefront from scratch, check out the [Storefront Development guides](!resources!/storefront-development).
diff --git a/www/apps/resources/app/js-sdk/page.mdx b/www/apps/resources/app/js-sdk/page.mdx
new file mode 100644
index 0000000000..e63abd01d3
--- /dev/null
+++ b/www/apps/resources/app/js-sdk/page.mdx
@@ -0,0 +1,395 @@
+import { CodeTabs, CodeTab, Table } from "docs-ui"
+
+export const metadata = {
+ title: `Medusa JS SDK`,
+}
+
+# {metadata.title}
+
+In this documentation, you'll learn how to install and use Medusa's JS SDK.
+
+## What is Medusa JS SDK?
+
+Medusa's JS SDK is a library to easily send requests to your Medusa application. You can use it in your admin customizations or custom storefronts.
+
+---
+
+## How to Install Medusa JS SDK?
+
+The Medusa JS SDK is available in your Medusa application by default. So, you don't need to install it before using it in your admin customizations.
+
+To install the Medusa JS SDK in other projects, such as a custom storefront, run the following command:
+
+```bash npm2yarn
+npm install @medusajs/js-sdk@rc @medusajs/types@rc
+```
+
+You install two libraries:
+
+- `@medusajs/js-sdk`: the Medusa JS SDK.
+- `@medusajs/types`: Medusa's types library, which is useful if you're using TypeScript in your development.
+
+---
+
+## Setup JS SDK
+
+In your project, create the following `config.ts` file:
+
+
+
+For admin customizations, create this file at `src/admin/lib/config.ts`.
+
+
+
+
+
+
+```ts title="src/admin/lib/config.ts"
+import Medusa from "@medusajs/js-sdk"
+
+export const sdk = new Medusa({
+ baseUrl: "http://localhost:9000",
+ debug: process.env.NODE_ENV === "development",
+ auth: {
+ type: "session",
+ },
+})
+```
+
+
+
+
+```ts title="config.ts"
+import Medusa from "@medusajs/js-sdk"
+
+let MEDUSA_BACKEND_URL = "http://localhost:9000"
+
+if (process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL) {
+ MEDUSA_BACKEND_URL = process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL
+}
+
+export const sdk = new Medusa({
+ baseUrl: MEDUSA_BACKEND_URL,
+ debug: process.env.NODE_ENV === "development",
+ publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+})
+```
+
+
+
+
+### JS SDK Configurations
+
+The `Medusa` initializer accepts as a parameter an object with the following properties:
+
+
+
+
+ Property
+ Description
+ Default
+
+
+
+
+
+
+ `baseUrl`
+
+
+
+
+ A required string indicating the URL to the Medusa backend.
+
+
+
+
+ \-
+
+
+
+
+
+
+ `publishableKey`
+
+
+
+
+ A string indicating the publishable API key to use in the storefront. You can retrieve it from the Medusa Admin.
+
+ This is required for storefront applications. Otherwise, all requests will fail.
+
+
+
+
+ \-
+
+
+
+
+
+
+ `auth.type`
+
+
+
+
+ A string that specifies the user authentication method to use.
+
+ Possible types are:
+
+ - `session`: The user is authenticated with a cookie session.
+ - `jwt`: The user is authenticated with a JWT token that's passed in the Bearer authorization header.
+
+
+
+
+ \-
+
+
+
+
+
+
+ `auth.jwtTokenStorageKey`
+
+
+
+
+ A string that, when `auth.type` is `jwt`, specifies the key of the JWT token in the storage specified in the `auth.jwtTokenStorageMethod` configuration.
+
+
+
+
+ `medusa_auth_token`
+
+
+
+
+
+
+ `auth.jwtTokenStorageMethod`
+
+
+
+
+ A string that, when `auth.type` is `jwt`, specifies where the JWT token is stored. Possible values are:
+
+ - `local` for the Local Storage.
+ - `session` for the Session Storage.
+ - `memory` to store it within the SDK for the current application's runtime.
+
+
+
+
+ `local`
+
+
+
+
+
+
+ `globalHeaders`
+
+
+
+
+ An object of key-value pairs indicating headers to pass in all requests, where the key indicates the name of the header field.
+
+
+
+
+ \-
+
+
+
+
+
+
+ `apiKey`
+
+
+
+
+ A string indicating the admin user's API key. If specified, it's used to send authenticated requests.
+
+
+
+
+ \-
+
+
+
+
+
+
+ `debug`
+
+
+
+
+ A boolean indicating whether to show debug messages of requests sent in the console. This is useful during development.
+
+
+
+
+ `false`
+
+
+
+
+
+
+ `logger`
+
+
+
+
+ Replace the logger used by the JS SDK to log messages. The logger must be a class or object having the following methods:
+
+ - `error`: A function that accepts an error message to log.
+ - `warn`: A function that accepts a warning message to log.
+ - `info`: A function that accepts an info message to log.
+ - `debug`: A function that accepts a debug message to log.
+
+
+
+
+ JavaScript's [console](https://developer.mozilla.org/en-US/docs/Web/API/console) is used by default.
+
+
+
+
+
+
+---
+
+## Medusa JS SDK Tips
+
+### Use Tanstack (React) Query in Admin Customizations
+
+In admin customizations, use [Tanstack Query](https://tanstack.com/query/latest) with the JS SDK to send requests to custom or existing API routes.
+
+Tanstack Query is installed by default in your Medusa application.
+
+Use the [configured SDK](#setup-js-sdk) with the [useQuery](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery#usequery) Tanstack Query hook to send `GET` requests, and [useMutation](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation#usemutation) hook to send `POST` or `DELETE` requests.
+
+For example:
+
+
+
+
+export const queryHighlights = [
+ ["8", "useQuery", "Use Tanstack Query's `useQuery` to send a `GET` request."],
+ ["9", "sdk.admin.product.list", "Use the SDK to send the request."],
+ ["10", "queryKey", "Specify the key used to cache data."]
+]
+
+```tsx title="src/admin/widgets/product-widget.ts"
+import { defineWidgetConfig } from "@medusajs/admin-sdk"
+import { Button, Container } from "@medusajs/ui"
+import { useQuery } from "@tanstack/react-query"
+import { sdk } from "../lib/config"
+import { DetailWidgetProps, HttpTypes } from "@medusajs/framework/types"
+
+const ProductWidget = () => {
+ const { data, isLoading } = useQuery({
+ queryFn: () => sdk.admin.product.list(),
+ queryKey: ["products"]
+ })
+
+ return (
+
+ {isLoading && Loading...}
+ {data?.products && (
+