mirror of
https://github.com/vercel/commerce.git
synced 2025-07-26 03:31:23 +00:00
Update provider and commerce docs (#256)
* Updating the docs for framework/commerce * Added more docs * Updated cart hooks docs * Updated docs for wishlist and Node.js * Added a note * Updated table of contents * Adding new provider docs * Updated core docs, main repo docs, and new provider docs * Updated bigcommerce docs * Updated shopify docs
This commit is contained in:
Luis Alvarez D
GitHub
334
framework/commerce/README.md
Normal file
334
framework/commerce/README.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# Commerce Framework
|
||||
|
||||
- [Commerce Framework](#commerce-framework)
|
||||
- [Commerce Hooks](#commerce-hooks)
|
||||
- [CommerceProvider](#commerceprovider)
|
||||
- [Authentication Hooks](#authentication-hooks)
|
||||
- [useSignup](#usesignup)
|
||||
- [useLogin](#uselogin)
|
||||
- [useLogout](#uselogout)
|
||||
- [Customer Hooks](#customer-hooks)
|
||||
- [useCustomer](#usecustomer)
|
||||
- [Product Hooks](#product-hooks)
|
||||
- [usePrice](#useprice)
|
||||
- [useSearch](#usesearch)
|
||||
- [Cart Hooks](#cart-hooks)
|
||||
- [useCart](#usecart)
|
||||
- [useAddItem](#useadditem)
|
||||
- [useUpdateItem](#useupdateitem)
|
||||
- [useRemoveItem](#useremoveitem)
|
||||
- [Wishlist Hooks](#wishlist-hooks)
|
||||
- [Commerce API](#commerce-api)
|
||||
- [More](#more)
|
||||
|
||||
The commerce framework ships multiple hooks and a Node.js API, both using an underlying headless e-commerce platform, which we call commerce providers.
|
||||
|
||||
The core features are:
|
||||
|
||||
- Code splitted hooks for data fetching using [SWR](https://swr.vercel.app/), and to handle common user actions
|
||||
- A Node.js API for initial data population, static generation of content and for creating the API endpoints that connect to the hooks, if required.
|
||||
|
||||
> 👩🔬 If you would like to contribute a new provider, check the docs for [Adding a new Commerce Provider](./new-provider.md).
|
||||
|
||||
> 🚧 The core commerce framework is under active development, new features and updates will be continuously added over time. Breaking changes are expected while we finish the API.
|
||||
|
||||
## Commerce Hooks
|
||||
|
||||
A commerce hook is a [React hook](https://reactjs.org/docs/hooks-intro.html) that's connected to a commerce provider. They focus on user actions and data fetching of data that wasn't statically generated.
|
||||
|
||||
Data fetching hooks use [SWR](https://swr.vercel.app/) underneath and you're welcome to use any of its [return values](https://swr.vercel.app/docs/options#return-values) and [options](https://swr.vercel.app/docs/options#options). For example, using the `useCustomer` hook:
|
||||
|
||||
```jsx
|
||||
const { data, isLoading, error } = useCustomer({
|
||||
swrOptions: {
|
||||
revalidateOnFocus: true,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### CommerceProvider
|
||||
|
||||
This component adds the provider config and handlers to the context of your React tree for it's children. You can optionally pass the `locale` to it:
|
||||
|
||||
```jsx
|
||||
import { CommerceProvider } from '@framework'
|
||||
|
||||
const App = ({ locale = 'en-US', children }) => {
|
||||
return <CommerceProvider locale={locale}>{children}</CommerceProvider>
|
||||
}
|
||||
```
|
||||
|
||||
## Authentication Hooks
|
||||
|
||||
### useSignup
|
||||
|
||||
Returns a _signup_ function that can be used to sign up the current visitor:
|
||||
|
||||
```jsx
|
||||
import useSignup from '@framework/auth/use-signup'
|
||||
|
||||
const SignupView = () => {
|
||||
const signup = useSignup()
|
||||
|
||||
const handleSignup = async () => {
|
||||
await signup({
|
||||
email,
|
||||
firstName,
|
||||
lastName,
|
||||
password,
|
||||
})
|
||||
}
|
||||
|
||||
return <form onSubmit={handleSignup}>{children}</form>
|
||||
}
|
||||
```
|
||||
|
||||
### useLogin
|
||||
|
||||
Returns a _login_ function that can be used to sign in the current visitor into an existing customer:
|
||||
|
||||
```jsx
|
||||
import useLogin from '@framework/auth/use-login'
|
||||
|
||||
const LoginView = () => {
|
||||
const login = useLogin()
|
||||
const handleLogin = async () => {
|
||||
await login({
|
||||
email,
|
||||
password,
|
||||
})
|
||||
}
|
||||
|
||||
return <form onSubmit={handleLogin}>{children}</form>
|
||||
}
|
||||
```
|
||||
|
||||
### useLogout
|
||||
|
||||
Returns a _logout_ function that signs out the current customer when called.
|
||||
|
||||
```jsx
|
||||
import useLogout from '@framework/auth/use-logout'
|
||||
|
||||
const LogoutButton = () => {
|
||||
const logout = useLogout()
|
||||
return (
|
||||
<button type="button" onClick={() => logout()}>
|
||||
Logout
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Customer Hooks
|
||||
|
||||
### useCustomer
|
||||
|
||||
Fetches and returns the data of the signed in customer:
|
||||
|
||||
```jsx
|
||||
import useCustomer from '@framework/customer/use-customer'
|
||||
|
||||
const Profile = () => {
|
||||
const { data, isLoading, error } = useCustomer()
|
||||
|
||||
if (isLoading) return <p>Loading...</p>
|
||||
if (error) return <p>{error.message}</p>
|
||||
if (!data) return null
|
||||
|
||||
return <div>Hello, {data.firstName}</div>
|
||||
}
|
||||
```
|
||||
|
||||
## Product Hooks
|
||||
|
||||
### usePrice
|
||||
|
||||
Helper hook to format price according to the commerce locale and currency code. It also handles discounts:
|
||||
|
||||
```jsx
|
||||
import useCart from '@framework/cart/use-cart'
|
||||
import usePrice from '@framework/product/use-price'
|
||||
|
||||
// ...
|
||||
const { data } = useCart()
|
||||
const { price, discount, basePrice } = usePrice(
|
||||
data && {
|
||||
amount: data.subtotalPrice,
|
||||
currencyCode: data.currency.code,
|
||||
// If `baseAmount` is used, a discount will be calculated
|
||||
// baseAmount: number,
|
||||
}
|
||||
)
|
||||
// ...
|
||||
```
|
||||
|
||||
### useSearch
|
||||
|
||||
Fetches and returns the products that match a set of filters:
|
||||
|
||||
```jsx
|
||||
import useSearch from '@framework/product/use-search'
|
||||
|
||||
const SearchPage = ({ searchString, category, brand, sortStr }) => {
|
||||
const { data } = useSearch({
|
||||
search: searchString || '',
|
||||
categoryId: category?.entityId,
|
||||
brandId: brand?.entityId,
|
||||
sort: sortStr,
|
||||
})
|
||||
|
||||
return (
|
||||
<Grid layout="normal">
|
||||
{data.products.map((product) => (
|
||||
<ProductCard key={product.path} product={product} />
|
||||
))}
|
||||
</Grid>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Cart Hooks
|
||||
|
||||
### useCart
|
||||
|
||||
Fetches and returns the data of the current cart:
|
||||
|
||||
```jsx
|
||||
import useCart from '@framework/cart/use-cart'
|
||||
|
||||
const CartTotal = () => {
|
||||
const { data, isLoading, isEmpty, error } = useCart()
|
||||
|
||||
if (isLoading) return <p>Loading...</p>
|
||||
if (error) return <p>{error.message}</p>
|
||||
if (isEmpty) return <p>The cart is empty</p>
|
||||
|
||||
return <p>The cart total is {data.totalPrice}</p>
|
||||
}
|
||||
```
|
||||
|
||||
### useAddItem
|
||||
|
||||
Returns a function that adds a new item to the cart when called, if this is the first item it will create the cart:
|
||||
|
||||
```jsx
|
||||
import { useAddItem } from '@framework/cart'
|
||||
|
||||
const AddToCartButton = ({ productId, variantId }) => {
|
||||
const addItem = useAddItem()
|
||||
|
||||
const addToCart = async () => {
|
||||
await addItem({
|
||||
productId,
|
||||
variantId,
|
||||
})
|
||||
}
|
||||
|
||||
return <button onClick={addToCart}>Add To Cart</button>
|
||||
}
|
||||
```
|
||||
|
||||
### useUpdateItem
|
||||
|
||||
Returns a function that updates a current item in the cart when called, usually the quantity.
|
||||
|
||||
```jsx
|
||||
import { useUpdateItem } from '@framework/cart'
|
||||
|
||||
const CartItemQuantity = ({ item }) => {
|
||||
const [quantity, setQuantity] = useState(item.quantity)
|
||||
const updateItem = useUpdateItem({ item })
|
||||
|
||||
const updateQuantity = async (e) => {
|
||||
const val = e.target.value
|
||||
|
||||
setQuantity(val)
|
||||
await updateItem({ quantity: val })
|
||||
}
|
||||
|
||||
return (
|
||||
<input
|
||||
type="number"
|
||||
max={99}
|
||||
min={0}
|
||||
value={quantity}
|
||||
onChange={updateQuantity}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
If the `quantity` is lower than 1 the item will be removed from the cart.
|
||||
|
||||
### useRemoveItem
|
||||
|
||||
Returns a function that removes an item in the cart when called:
|
||||
|
||||
```jsx
|
||||
import { useRemoveItem } from '@framework/cart'
|
||||
|
||||
const RemoveButton = ({ item }) => {
|
||||
const removeItem = useRemoveItem()
|
||||
const handleRemove = async () => {
|
||||
await removeItem(item)
|
||||
}
|
||||
|
||||
return <button onClick={handleRemove}>Remove</button>
|
||||
}
|
||||
```
|
||||
|
||||
## Wishlist Hooks
|
||||
|
||||
Wishlist hooks work just like [cart hooks](#cart-hooks). Feel free to check how those work first.
|
||||
|
||||
The example below shows how to use the `useWishlist`, `useAddItem` and `useRemoveItem` hooks:
|
||||
|
||||
```jsx
|
||||
import { useWishlist, useAddItem, useRemoveItem } from '@framework/wishlist'
|
||||
|
||||
const WishlistButton = ({ productId, variant }) => {
|
||||
const addItem = useAddItem()
|
||||
const removeItem = useRemoveItem()
|
||||
const { data, isLoading, isEmpty, error } = useWishlist()
|
||||
|
||||
if (isLoading) return <p>Loading...</p>
|
||||
if (error) return <p>{error.message}</p>
|
||||
if (isEmpty) return <p>The wihslist is empty</p>
|
||||
|
||||
const { data: customer } = useCustomer()
|
||||
const itemInWishlist = data?.items?.find(
|
||||
(item) => item.product_id === productId && item.variant_id === variant.id
|
||||
)
|
||||
|
||||
const handleWishlistChange = async (e) => {
|
||||
e.preventDefault()
|
||||
if (!customer) return
|
||||
|
||||
if (itemInWishlist) {
|
||||
await removeItem({ id: itemInWishlist.id })
|
||||
} else {
|
||||
await addItem({
|
||||
productId,
|
||||
variantId: variant.id,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<button onClick={handleWishlistChange}>
|
||||
<Heart fill={itemInWishlist ? 'var(--pink)' : 'none'} />
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Commerce API
|
||||
|
||||
While commerce hooks focus on client side data fetching and interactions, the commerce API focuses on static content generation for pages and API endpoints in a Node.js context.
|
||||
|
||||
> The commerce API is currently going through a refactor in https://github.com/vercel/commerce/pull/252 - We'll update the docs once the API is released.
|
||||
|
||||
## More
|
||||
|
||||
Feel free to read through the source for more usage, and check the commerce vercel demo and commerce repo for usage examples: ([demo.vercel.store](https://demo.vercel.store/)) ([repo](https://github.com/vercel/commerce))
|
||||
239
framework/commerce/new-provider.md
Normal file
239
framework/commerce/new-provider.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# Adding a new Commerce Provider
|
||||
|
||||
A commerce provider is a headless e-commerce platform that integrates with the [Commerce Framework](./README.md). Right now we have the following providers:
|
||||
|
||||
- BigCommerce ([framework/bigcommerce](../bigcommerce))
|
||||
- Shopify ([framework/shopify](../shopify))
|
||||
|
||||
Adding a commerce provider means adding a new folder in `framework` with a folder structure like the next one:
|
||||
|
||||
- `api`
|
||||
- index.ts
|
||||
- `product`
|
||||
- usePrice
|
||||
- useSearch
|
||||
- getProduct
|
||||
- getAllProducts
|
||||
- `wishlist`
|
||||
- useWishlist
|
||||
- useAddItem
|
||||
- useRemoveItem
|
||||
- `auth`
|
||||
- useLogin
|
||||
- useLogout
|
||||
- useSignup
|
||||
- `customer`
|
||||
- useCustomer
|
||||
- getCustomerId
|
||||
- getCustomerWistlist
|
||||
- `cart`
|
||||
- useCart
|
||||
- useAddItem
|
||||
- useRemoveItem
|
||||
- useUpdateItem
|
||||
- `env.template`
|
||||
- `index.ts`
|
||||
- `provider.ts`
|
||||
- `commerce.config.json`
|
||||
- `next.config.js`
|
||||
- `README.md`
|
||||
|
||||
`provider.ts` exports a provider object with handlers for the [Commerce Hooks](./README.md#commerce-hooks) and `api/index.ts` exports a Node.js provider for the [Commerce API](./README.md#commerce-api)
|
||||
|
||||
> **Important:** We use TypeScript for every provider and expect its usage for every new one.
|
||||
|
||||
The app imports from the provider directly instead of the core commerce folder (`framework/commerce`), but all providers are interchangeable and to achieve it every provider always has to implement the core types and helpers.
|
||||
|
||||
The provider folder should only depend on `framework/commerce` and dependencies in the main `package.json`. In the future we'll move the `framework` folder to a package that can be shared easily for multiple apps.
|
||||
|
||||
## Adding the provider hooks
|
||||
|
||||
Using BigCommerce as an example. The first thing to do is export a `CommerceProvider` component that includes a `provider` object with all the handlers that can be used for hooks:
|
||||
|
||||
```tsx
|
||||
import type { ReactNode } from 'react'
|
||||
import {
|
||||
CommerceConfig,
|
||||
CommerceProvider as CoreCommerceProvider,
|
||||
useCommerce as useCoreCommerce,
|
||||
} from '@commerce'
|
||||
import { bigcommerceProvider, BigcommerceProvider } from './provider'
|
||||
|
||||
export { bigcommerceProvider }
|
||||
export type { BigcommerceProvider }
|
||||
|
||||
export const bigcommerceConfig: CommerceConfig = {
|
||||
locale: 'en-us',
|
||||
cartCookie: 'bc_cartId',
|
||||
}
|
||||
|
||||
export type BigcommerceConfig = Partial<CommerceConfig>
|
||||
|
||||
export type BigcommerceProps = {
|
||||
children?: ReactNode
|
||||
locale: string
|
||||
} & BigcommerceConfig
|
||||
|
||||
export function CommerceProvider({ children, ...config }: BigcommerceProps) {
|
||||
return (
|
||||
<CoreCommerceProvider
|
||||
provider={bigcommerceProvider}
|
||||
config={{ ...bigcommerceConfig, ...config }}
|
||||
>
|
||||
{children}
|
||||
</CoreCommerceProvider>
|
||||
)
|
||||
}
|
||||
|
||||
export const useCommerce = () => useCoreCommerce<BigcommerceProvider>()
|
||||
```
|
||||
|
||||
The exported types and components extend from the core ones exported by `@commerce`, which refers to `framework/commerce`.
|
||||
|
||||
The `bigcommerceProvider` object looks like this:
|
||||
|
||||
```tsx
|
||||
import { handler as useCart } from './cart/use-cart'
|
||||
import { handler as useAddItem } from './cart/use-add-item'
|
||||
import { handler as useUpdateItem } from './cart/use-update-item'
|
||||
import { handler as useRemoveItem } from './cart/use-remove-item'
|
||||
|
||||
import { handler as useWishlist } from './wishlist/use-wishlist'
|
||||
import { handler as useWishlistAddItem } from './wishlist/use-add-item'
|
||||
import { handler as useWishlistRemoveItem } from './wishlist/use-remove-item'
|
||||
|
||||
import { handler as useCustomer } from './customer/use-customer'
|
||||
import { handler as useSearch } from './product/use-search'
|
||||
|
||||
import { handler as useLogin } from './auth/use-login'
|
||||
import { handler as useLogout } from './auth/use-logout'
|
||||
import { handler as useSignup } from './auth/use-signup'
|
||||
|
||||
import fetcher from './fetcher'
|
||||
|
||||
export const bigcommerceProvider = {
|
||||
locale: 'en-us',
|
||||
cartCookie: 'bc_cartId',
|
||||
fetcher,
|
||||
cart: { useCart, useAddItem, useUpdateItem, useRemoveItem },
|
||||
wishlist: {
|
||||
useWishlist,
|
||||
useAddItem: useWishlistAddItem,
|
||||
useRemoveItem: useWishlistRemoveItem,
|
||||
},
|
||||
customer: { useCustomer },
|
||||
products: { useSearch },
|
||||
auth: { useLogin, useLogout, useSignup },
|
||||
}
|
||||
|
||||
export type BigcommerceProvider = typeof bigcommerceProvider
|
||||
```
|
||||
|
||||
The provider object, in this case `bigcommerceProvider`, has to match the `Provider` type defined in [framework/commerce](./index.ts).
|
||||
|
||||
A hook handler, like `useCart`, looks like this:
|
||||
|
||||
```tsx
|
||||
import { useMemo } from 'react'
|
||||
import { SWRHook } from '@commerce/utils/types'
|
||||
import useCart, { UseCart, FetchCartInput } from '@commerce/cart/use-cart'
|
||||
import { normalizeCart } from '../lib/normalize'
|
||||
import type { Cart } from '../types'
|
||||
|
||||
export default useCart as UseCart<typeof handler>
|
||||
|
||||
export const handler: SWRHook<
|
||||
Cart | null,
|
||||
{},
|
||||
FetchCartInput,
|
||||
{ isEmpty?: boolean }
|
||||
> = {
|
||||
fetchOptions: {
|
||||
url: '/api/bigcommerce/cart',
|
||||
method: 'GET',
|
||||
},
|
||||
async fetcher({ input: { cartId }, options, fetch }) {
|
||||
const data = cartId ? await fetch(options) : null
|
||||
return data && normalizeCart(data)
|
||||
},
|
||||
useHook: ({ useData }) => (input) => {
|
||||
const response = useData({
|
||||
swrOptions: { revalidateOnFocus: false, ...input?.swrOptions },
|
||||
})
|
||||
|
||||
return useMemo(
|
||||
() =>
|
||||
Object.create(response, {
|
||||
isEmpty: {
|
||||
get() {
|
||||
return (response.data?.lineItems.length ?? 0) <= 0
|
||||
},
|
||||
enumerable: true,
|
||||
},
|
||||
}),
|
||||
[response]
|
||||
)
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
In the case of data fetching hooks like `useCart` each handler has to implement the `SWRHook` type that's defined in the core types. For mutations it's the `MutationHook`, e.g for `useAddItem`:
|
||||
|
||||
```tsx
|
||||
import { useCallback } from 'react'
|
||||
import type { MutationHook } from '@commerce/utils/types'
|
||||
import { CommerceError } from '@commerce/utils/errors'
|
||||
import useAddItem, { UseAddItem } from '@commerce/cart/use-add-item'
|
||||
import { normalizeCart } from '../lib/normalize'
|
||||
import type {
|
||||
Cart,
|
||||
BigcommerceCart,
|
||||
CartItemBody,
|
||||
AddCartItemBody,
|
||||
} from '../types'
|
||||
import useCart from './use-cart'
|
||||
|
||||
export default useAddItem as UseAddItem<typeof handler>
|
||||
|
||||
export const handler: MutationHook<Cart, {}, CartItemBody> = {
|
||||
fetchOptions: {
|
||||
url: '/api/bigcommerce/cart',
|
||||
method: 'POST',
|
||||
},
|
||||
async fetcher({ input: item, options, fetch }) {
|
||||
if (
|
||||
item.quantity &&
|
||||
(!Number.isInteger(item.quantity) || item.quantity! < 1)
|
||||
) {
|
||||
throw new CommerceError({
|
||||
message: 'The item quantity has to be a valid integer greater than 0',
|
||||
})
|
||||
}
|
||||
|
||||
const data = await fetch<BigcommerceCart, AddCartItemBody>({
|
||||
...options,
|
||||
body: { item },
|
||||
})
|
||||
|
||||
return normalizeCart(data)
|
||||
},
|
||||
useHook: ({ fetch }) => () => {
|
||||
const { mutate } = useCart()
|
||||
|
||||
return useCallback(
|
||||
async function addItem(input) {
|
||||
const data = await fetch({ input })
|
||||
await mutate(data, false)
|
||||
return data
|
||||
},
|
||||
[fetch, mutate]
|
||||
)
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Adding the Node.js provider API
|
||||
|
||||
TODO
|
||||
|
||||
> The commerce API is currently going through a refactor in https://github.com/vercel/commerce/pull/252 - We'll update the docs once the API is released.
|
||||
Reference in New Issue
Block a user