mirror of
https://github.com/vercel/commerce.git
synced 2025-06-19 05:31:22 +00:00
Add some documentation
This commit is contained in:
Michael Bromley
parent
126032877f
commit
695caba290
@ -1,377 +1,54 @@
|
|||||||
# Table of Contents
|
# Vendure Storefront Data Hooks
|
||||||
|
|
||||||
- [BigCommerce Storefront Data Hooks](#bigcommerce-storefront-data-hooks)
|
UI hooks and data fetching methods built from the ground up for e-commerce applications written in React, that use [Vendure](http://vendure.io/) as a headless e-commerce platform.
|
||||||
- [Installation](#installation)
|
|
||||||
- [General Usage](#general-usage)
|
## Usage
|
||||||
- [CommerceProvider](#commerceprovider)
|
|
||||||
- [useLogin hook](#uselogin-hook)
|
As this is still under development, no npm package is yet provided. Here's how you can try it out:
|
||||||
- [useLogout](#uselogout)
|
|
||||||
- [useCustomer](#usecustomer)
|
1. First you'll need a Vendure server. You can your own local server up-and-running with just a single command:
|
||||||
- [useSignup](#usesignup)
|
```shell
|
||||||
- [usePrice](#useprice)
|
npx @vendure/create my-app
|
||||||
- [Cart Hooks](#cart-hooks)
|
```
|
||||||
- [useCart](#usecart)
|
See the [Vendure getting started guide](https://www.vendure.io/docs/getting-started/) for more info.
|
||||||
- [useAddItem](#useadditem)
|
2. Once you have Vendure set up, change the default port to something other than 3000, to avoid conflict with your Next.js Commerce dev server:
|
||||||
- [useUpdateItem](#useupdateitem)
|
```TypeScript
|
||||||
- [useRemoveItem](#useremoveitem)
|
// vendure-config.ts
|
||||||
- [Wishlist Hooks](#wishlist-hooks)
|
export const config: VendureConfig = {
|
||||||
- [Product Hooks and API](#product-hooks-and-api)
|
apiOptions: {
|
||||||
- [useSearch](#usesearch)
|
port: 3001, // <----- here
|
||||||
- [getAllProducts](#getallproducts)
|
adminApiPath: 'admin-api',
|
||||||
- [getProduct](#getproduct)
|
// ...
|
||||||
- [More](#more)
|
}
|
||||||
|
};
|
||||||
# BigCommerce Storefront Data Hooks
|
```
|
||||||
|
3. Clone this repo and install its dependencies with `yarn install` or `npm install`
|
||||||
> This project is under active development, new features and updates will be continuously added over time
|
4. Change the paths in [tsconfig.json](../../tsconfig.json) to point to the Vendure hooks:
|
||||||
|
```diff
|
||||||
UI hooks and data fetching methods built from the ground up for e-commerce applications written in React, that use BigCommerce as a headless e-commerce platform. The package provides:
|
"paths": {
|
||||||
|
"@lib/*": ["lib/*"],
|
||||||
- Code splitted hooks for data fetching using [SWR](https://swr.vercel.app/), and to handle common user actions
|
"@assets/*": ["assets/*"],
|
||||||
- Code splitted data fetching methods for initial data population and static generation of content
|
"@config/*": ["config/*"],
|
||||||
- Helpers to create the API endpoints that connect to the hooks, very well suited for Next.js applications
|
"@components/*": ["components/*"],
|
||||||
|
"@utils/*": ["utils/*"],
|
||||||
## Installation
|
"@commerce/*": ["framework/commerce/*"],
|
||||||
|
"@commerce": ["framework/commerce"],
|
||||||
To install:
|
- "@framework/*": ["framework/bigcommerce/*"],
|
||||||
|
- "@framework": ["framework/bigcommerce"]
|
||||||
```
|
+ "@framework/*": ["framework/vendure/*"],
|
||||||
yarn add storefront-data-hooks
|
+ "@framework": ["framework/vendure"]
|
||||||
```
|
}
|
||||||
|
```
|
||||||
After install, the first thing you do is: <b>set your environment variables</b> in `.env.local`
|
5. Set the Vendure Shop API URL in your `.env.local` file:
|
||||||
|
```sh
|
||||||
```sh
|
NEXT_PUBLIC_VENDURE_SHOP_API_URL=http://localhost:3001/shop-api
|
||||||
VENDURE_SHOP_API_URL=<>
|
```
|
||||||
```
|
6. With the Vendure server running, start this project using `yarn dev` or `npm run dev`.
|
||||||
|
|
||||||
## General Usage
|
## Known Limitations
|
||||||
|
|
||||||
### CommerceProvider
|
1. Vendure does not ship with built-in wishlist functionality.
|
||||||
|
2. Nor does it come with any kind of blog/page-building feature. Both of these can be created as Vendure plugins, however.
|
||||||
This component is a provider pattern component that creates commerce context for it's children. It takes config values for the locale and an optional `fetcherRef` object for data fetching.
|
3. The entire Vendure customer flow is carried out via its GraphQL API. This means that there is no external, pre-existing checkout flow. The checkout flow must be created as part of the Next.js app.
|
||||||
|
4. By default, the sign-up flow in Vendure uses email verification. This means that using the existing "sign up" flow from this project will not grant a new user the ability to authenticate, since the new account must first be verified. Again, the necessary parts to support this flow can be created as part of the Next.js app.
|
||||||
```jsx
|
5. The mapping of products & variants may not totally match up with what the storefront expects. As the storefront matures and improves this mapping can be refined.
|
||||||
...
|
|
||||||
import { CommerceProvider } from '@bigcommerce/storefront-data-hooks'
|
|
||||||
|
|
||||||
const App = ({ locale = 'en-US', children }) => {
|
|
||||||
return (
|
|
||||||
<CommerceProvider locale={locale}>
|
|
||||||
{children}
|
|
||||||
</CommerceProvider>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
### useLogin hook
|
|
||||||
|
|
||||||
Hook for bigcommerce user login functionality, returns `login` function to handle user login.
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
...
|
|
||||||
import useLogin from '@bigcommerce/storefront-data-hooks/use-login'
|
|
||||||
|
|
||||||
const LoginView = () => {
|
|
||||||
const login = useLogin()
|
|
||||||
|
|
||||||
const handleLogin = async () => {
|
|
||||||
await login({
|
|
||||||
email,
|
|
||||||
password,
|
|
||||||
})
|
|
||||||
}
|
|
||||||
|
|
||||||
return (
|
|
||||||
<form onSubmit={handleLogin}>
|
|
||||||
{children}
|
|
||||||
</form>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
### useLogout
|
|
||||||
|
|
||||||
Hook to logout user.
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
...
|
|
||||||
import useLogout from '@bigcommerce/storefront-data-hooks/use-logout'
|
|
||||||
|
|
||||||
const LogoutLink = () => {
|
|
||||||
const logout = useLogout()
|
|
||||||
return (
|
|
||||||
<a onClick={() => logout()}>
|
|
||||||
Logout
|
|
||||||
</a>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### useCustomer
|
|
||||||
|
|
||||||
Hook for getting logged in customer data, and fetching customer info.
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
...
|
|
||||||
import useCustomer from '@bigcommerce/storefront-data-hooks/use-customer'
|
|
||||||
...
|
|
||||||
|
|
||||||
const Profile = () => {
|
|
||||||
const { data } = useCustomer()
|
|
||||||
|
|
||||||
if (!data) {
|
|
||||||
return null
|
|
||||||
}
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div>Hello, {data.firstName}</div>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### useSignup
|
|
||||||
|
|
||||||
Hook for bigcommerce user signup, returns `signup` function to handle user signups.
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
...
|
|
||||||
import useSignup from '@bigcommerce/storefront-data-hooks/use-login'
|
|
||||||
|
|
||||||
const SignupView = () => {
|
|
||||||
const signup = useSignup()
|
|
||||||
|
|
||||||
const handleSignup = async () => {
|
|
||||||
await signup({
|
|
||||||
email,
|
|
||||||
firstName,
|
|
||||||
lastName,
|
|
||||||
password,
|
|
||||||
})
|
|
||||||
}
|
|
||||||
|
|
||||||
return (
|
|
||||||
<form onSubmit={handleSignup}>
|
|
||||||
{children}
|
|
||||||
</form>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
### usePrice
|
|
||||||
|
|
||||||
Helper hook to format price according to commerce locale, and return discount if available.
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
import usePrice from '@bigcommerce/storefront-data-hooks/use-price'
|
|
||||||
...
|
|
||||||
const { price, discount, basePrice } = usePrice(
|
|
||||||
data && {
|
|
||||||
amount: data.cart_amount,
|
|
||||||
currencyCode: data.currency.code,
|
|
||||||
}
|
|
||||||
)
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
## Cart Hooks
|
|
||||||
|
|
||||||
### useCart
|
|
||||||
|
|
||||||
Returns the current cart data for use
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
...
|
|
||||||
import useCart from '@bigcommerce/storefront-data-hooks/cart/use-cart'
|
|
||||||
|
|
||||||
const countItem = (count: number, item: any) => count + item.quantity
|
|
||||||
const countItems = (count: number, items: any[]) =>
|
|
||||||
items.reduce(countItem, count)
|
|
||||||
|
|
||||||
const CartNumber = () => {
|
|
||||||
const { data } = useCart()
|
|
||||||
const itemsCount = Object.values(data?.line_items ?? {}).reduce(countItems, 0)
|
|
||||||
|
|
||||||
return itemsCount > 0 ? <span>{itemsCount}</span> : null
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### useAddItem
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
...
|
|
||||||
import useAddItem from '@bigcommerce/storefront-data-hooks/cart/use-add-item'
|
|
||||||
|
|
||||||
const AddToCartButton = ({ productId, variantId }) => {
|
|
||||||
const addItem = useAddItem()
|
|
||||||
|
|
||||||
const addToCart = async () => {
|
|
||||||
await addItem({
|
|
||||||
productId,
|
|
||||||
variantId,
|
|
||||||
})
|
|
||||||
}
|
|
||||||
|
|
||||||
return <button onClick={addToCart}>Add To Cart</button>
|
|
||||||
}
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
### useUpdateItem
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
...
|
|
||||||
import useUpdateItem from '@bigcommerce/storefront-data-hooks/cart/use-update-item'
|
|
||||||
|
|
||||||
const CartItem = ({ item }) => {
|
|
||||||
const [quantity, setQuantity] = useState(item.quantity)
|
|
||||||
const updateItem = useUpdateItem(item)
|
|
||||||
|
|
||||||
const updateQuantity = async (e) => {
|
|
||||||
const val = e.target.value
|
|
||||||
await updateItem({ quantity: val })
|
|
||||||
}
|
|
||||||
|
|
||||||
return (
|
|
||||||
<input
|
|
||||||
type="number"
|
|
||||||
max={99}
|
|
||||||
min={0}
|
|
||||||
value={quantity}
|
|
||||||
onChange={updateQuantity}
|
|
||||||
/>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
### useRemoveItem
|
|
||||||
|
|
||||||
Provided with a cartItemId, will remove an item from the cart:
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
...
|
|
||||||
import useRemoveItem from '@bigcommerce/storefront-data-hooks/cart/use-remove-item'
|
|
||||||
|
|
||||||
const RemoveButton = ({ item }) => {
|
|
||||||
const removeItem = useRemoveItem()
|
|
||||||
|
|
||||||
const handleRemove = async () => {
|
|
||||||
await removeItem({ id: item.id })
|
|
||||||
}
|
|
||||||
|
|
||||||
return <button onClick={handleRemove}>Remove</button>
|
|
||||||
}
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
## Wishlist Hooks
|
|
||||||
|
|
||||||
Wishlist hooks are similar to cart hooks. See the below example for how to use `useWishlist`, `useAddItem`, and `useRemoveItem`.
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
import useAddItem from '@bigcommerce/storefront-data-hooks/wishlist/use-add-item'
|
|
||||||
import useRemoveItem from '@bigcommerce/storefront-data-hooks/wishlist/use-remove-item'
|
|
||||||
import useWishlist from '@bigcommerce/storefront-data-hooks/wishlist/use-wishlist'
|
|
||||||
|
|
||||||
const WishlistButton = ({ productId, variant }) => {
|
|
||||||
const addItem = useAddItem()
|
|
||||||
const removeItem = useRemoveItem()
|
|
||||||
const { data } = useWishlist()
|
|
||||||
const { data: customer } = useCustomer()
|
|
||||||
const itemInWishlist = data?.items?.find(
|
|
||||||
(item) =>
|
|
||||||
item.product_id === productId &&
|
|
||||||
item.variant_id === variant?.node.entityId
|
|
||||||
)
|
|
||||||
|
|
||||||
const handleWishlistChange = async (e) => {
|
|
||||||
e.preventDefault()
|
|
||||||
|
|
||||||
if (!customer) {
|
|
||||||
return
|
|
||||||
}
|
|
||||||
|
|
||||||
if (itemInWishlist) {
|
|
||||||
await removeItem({ id: itemInWishlist.id! })
|
|
||||||
} else {
|
|
||||||
await addItem({
|
|
||||||
productId,
|
|
||||||
variantId: variant?.node.entityId!,
|
|
||||||
})
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return (
|
|
||||||
<button onClick={handleWishlistChange}>
|
|
||||||
<Heart fill={itemInWishlist ? 'var(--pink)' : 'none'} />
|
|
||||||
</button>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Product Hooks and API
|
|
||||||
|
|
||||||
### useSearch
|
|
||||||
|
|
||||||
`useSearch` handles searching the bigcommerce storefront product catalog by catalog, brand, and query string.
|
|
||||||
|
|
||||||
```jsx
|
|
||||||
...
|
|
||||||
import useSearch from '@bigcommerce/storefront-data-hooks/products/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(({ node }) => (
|
|
||||||
<ProductCard key={node.path} product={node} />
|
|
||||||
))}
|
|
||||||
</Grid>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### getAllProducts
|
|
||||||
|
|
||||||
API function to retrieve a product list.
|
|
||||||
|
|
||||||
```js
|
|
||||||
import { getConfig } from '@bigcommerce/storefront-data-hooks/api'
|
|
||||||
import getAllProducts from '@bigcommerce/storefront-data-hooks/api/operations/get-all-products'
|
|
||||||
|
|
||||||
const { products } = await getAllProducts({
|
|
||||||
variables: { field: 'featuredProducts', first: 6 },
|
|
||||||
config,
|
|
||||||
preview,
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### getProduct
|
|
||||||
|
|
||||||
API product to retrieve a single product when provided with the product
|
|
||||||
slug string.
|
|
||||||
|
|
||||||
```js
|
|
||||||
import { getConfig } from '@bigcommerce/storefront-data-hooks/api'
|
|
||||||
import getProduct from '@bigcommerce/storefront-data-hooks/api/operations/get-product'
|
|
||||||
|
|
||||||
const { product } = await getProduct({
|
|
||||||
variables: { slug },
|
|
||||||
config,
|
|
||||||
preview,
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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))
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user