forked from crowetic/commerce
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:
parent
f770ad7a91
commit
936f149fcc
59
README.md
59
README.md
@ -29,43 +29,10 @@ Next.js Commerce integrates out-of-the-box with BigCommerce and Shopify. We plan
|
|||||||
## Considerations
|
## Considerations
|
||||||
|
|
||||||
- `framework/commerce` contains all types, helpers and functions to be used as base to build a new **provider**.
|
- `framework/commerce` contains all types, helpers and functions to be used as base to build a new **provider**.
|
||||||
- **Providers** live under `framework`'s root folder and they will extend Next.js Commerce types and functionality.
|
- **Providers** live under `framework`'s root folder and they will extend Next.js Commerce types and functionality (`framework/commerce`).
|
||||||
- **Features API** is to ensure feature parity between the UI and the Provider. The UI should update accordingly and no extra code should be bundled. All extra configuration for features will live under `features` in `commerce.config.json` and if needed it can also be accessed programatically.
|
- We have a **Features API** to ensure feature parity between the UI and the Provider. The UI should update accordingly and no extra code should be bundled. All extra configuration for features will live under `features` in `commerce.config.json` and if needed it can also be accessed programatically.
|
||||||
- Each **provider** should add its corresponding `next.config.js` and `commerce.config.json` adding specific data related to the provider. For example in case of BigCommerce, the images CDN and additional API routes.
|
- Each **provider** should add its corresponding `next.config.js` and `commerce.config.json` adding specific data related to the provider. For example in case of BigCommerce, the images CDN and additional API routes.
|
||||||
- **Providers don't depend on anything that's specific to the application they're used in**. They only depend on `framework/commerce`, on their own framework folder and on some dependencies included in `package.json`
|
- **Providers don't depend on anything that's specific to the application they're used in**. They only depend on `framework/commerce`, on their own framework folder and on some dependencies included in `package.json`
|
||||||
- We recommend that each **provider** ships with an `env.template` file and a `[readme.md](http://readme.md)` file.
|
|
||||||
|
|
||||||
## Provider Structure
|
|
||||||
|
|
||||||
Next.js Commerce provides a set of utilities and functions to create new providers. This is how a provider structure looks like.
|
|
||||||
|
|
||||||
- `product`
|
|
||||||
- usePrice
|
|
||||||
- useSearch
|
|
||||||
- getProduct
|
|
||||||
- getAllProducts
|
|
||||||
- `wishlist`
|
|
||||||
- useWishlist
|
|
||||||
- useAddItem
|
|
||||||
- useRemoveItem
|
|
||||||
- `auth`
|
|
||||||
- useLogin
|
|
||||||
- useLogout
|
|
||||||
- useSignup
|
|
||||||
- `customer`
|
|
||||||
- useCustomer
|
|
||||||
- getCustomerId
|
|
||||||
- getCustomerWistlist
|
|
||||||
- `cart`
|
|
||||||
- useCart
|
|
||||||
- useAddItem
|
|
||||||
- useRemoveItem
|
|
||||||
- useUpdateItem
|
|
||||||
- `env.template`
|
|
||||||
- `provider.ts`
|
|
||||||
- `commerce.config.json`
|
|
||||||
- `next.config.js`
|
|
||||||
- `README.md`
|
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
@ -95,15 +62,9 @@ Every provider defines the features that it supports under `framework/{provider}
|
|||||||
|
|
||||||
### How to create a new provider
|
### How to create a new provider
|
||||||
|
|
||||||
We'd recommend to duplicate a provider folder and push your providers SDK.
|
Follow our docs for [Adding a new Commerce Provider](framework/commerce/new-provider.md).
|
||||||
|
|
||||||
If you succeeded building a provider, submit a PR so we can all enjoy it.
|
If you succeeded building a provider, submit a PR with a valid demo and we'll review it asap.
|
||||||
|
|
||||||
## Work in progress
|
|
||||||
|
|
||||||
We're using Github Projects to keep track of issues in progress and todo's. Here is our [Board](https://github.com/vercel/commerce/projects/1)
|
|
||||||
|
|
||||||
People actively working on this project: @okbel & @lfades.
|
|
||||||
|
|
||||||
## Contribute
|
## Contribute
|
||||||
|
|
||||||
@ -113,11 +74,15 @@ Our commitment to Open Source can be found [here](https://vercel.com/oss).
|
|||||||
2. Create a new branch `git checkout -b MY_BRANCH_NAME`
|
2. Create a new branch `git checkout -b MY_BRANCH_NAME`
|
||||||
3. Install yarn: `npm install -g yarn`
|
3. Install yarn: `npm install -g yarn`
|
||||||
4. Install the dependencies: `yarn`
|
4. Install the dependencies: `yarn`
|
||||||
5. Duplicate `.env.template` and rename it to `.env.local`.
|
5. Duplicate `.env.template` and rename it to `.env.local`
|
||||||
6. Add proper store values to `.env.local`.
|
6. Add proper store values to `.env.local`
|
||||||
7. Run `yarn dev` to build and watch for code changes
|
7. Run `yarn dev` to build and watch for code changes
|
||||||
8. The development branch is `canary` (this is the branch pull requests should be made against).
|
|
||||||
On a release, `canary` branch is rebased into `master`.
|
## Work in progress
|
||||||
|
|
||||||
|
We're using Github Projects to keep track of issues in progress and todo's. Here is our [Board](https://github.com/vercel/commerce/projects/1)
|
||||||
|
|
||||||
|
People actively working on this project: @okbel & @lfades.
|
||||||
|
|
||||||
## Troubleshoot
|
## Troubleshoot
|
||||||
|
|
||||||
|
@ -1,3 +1,5 @@
|
|||||||
|
COMMERCE_PROVIDER=bigcommerce
|
||||||
|
|
||||||
BIGCOMMERCE_STOREFRONT_API_URL=
|
BIGCOMMERCE_STOREFRONT_API_URL=
|
||||||
BIGCOMMERCE_STOREFRONT_API_TOKEN=
|
BIGCOMMERCE_STOREFRONT_API_TOKEN=
|
||||||
BIGCOMMERCE_STORE_API_URL=
|
BIGCOMMERCE_STORE_API_URL=
|
||||||
|
@ -1,45 +1,34 @@
|
|||||||
# Table of Contents
|
# Bigcommerce Provider
|
||||||
|
|
||||||
- [BigCommerce Storefront Data Hooks](#bigcommerce-storefront-data-hooks)
|
**Demo:** https://bigcommerce.demo.vercel.store/
|
||||||
- [Installation](#installation)
|
|
||||||
- [General Usage](#general-usage)
|
|
||||||
- [CommerceProvider](#commerceprovider)
|
|
||||||
- [useLogin hook](#uselogin-hook)
|
|
||||||
- [useLogout](#uselogout)
|
|
||||||
- [useCustomer](#usecustomer)
|
|
||||||
- [useSignup](#usesignup)
|
|
||||||
- [usePrice](#useprice)
|
|
||||||
- [Cart Hooks](#cart-hooks)
|
|
||||||
- [useCart](#usecart)
|
|
||||||
- [useAddItem](#useadditem)
|
|
||||||
- [useUpdateItem](#useupdateitem)
|
|
||||||
- [useRemoveItem](#useremoveitem)
|
|
||||||
- [Wishlist Hooks](#wishlist-hooks)
|
|
||||||
- [Product Hooks and API](#product-hooks-and-api)
|
|
||||||
- [useSearch](#usesearch)
|
|
||||||
- [getAllProducts](#getallproducts)
|
|
||||||
- [getProduct](#getproduct)
|
|
||||||
- [More](#more)
|
|
||||||
|
|
||||||
# BigCommerce Storefront Data Hooks
|
With the deploy button below you'll be able to have a [BigCommerce](https://www.bigcommerce.com/) account and a store that works with this starter:
|
||||||
|
|
||||||
> This project is under active development, new features and updates will be continuously added over time
|
[](https://vercel.com/new/git/external?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fcommerce&project-name=commerce&repo-name=commerce&demo-title=Next.js%20Commerce&demo-description=An%20all-in-one%20starter%20kit%20for%20high-performance%20e-commerce%20sites.&demo-url=https%3A%2F%2Fdemo.vercel.store&demo-image=https%3A%2F%2Fbigcommerce-demo-asset-ksvtgfvnd.vercel.app%2Fbigcommerce.png&integration-ids=oac_MuWZiE4jtmQ2ejZQaQ7ncuDT)
|
||||||
|
|
||||||
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:
|
If you already have a BigCommerce account and want to use your current store, then copy the `.env.template` file in this directory to `.env.local` in the main directory (which will be ignored by Git):
|
||||||
|
|
||||||
- Code splitted hooks for data fetching using [SWR](https://swr.vercel.app/), and to handle common user actions
|
```bash
|
||||||
- Code splitted data fetching methods for initial data population and static generation of content
|
cp framework/bigcommerce/.env.template .env.local
|
||||||
- Helpers to create the API endpoints that connect to the hooks, very well suited for Next.js applications
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
To install:
|
|
||||||
|
|
||||||
```
|
|
||||||
yarn add storefront-data-hooks
|
|
||||||
```
|
```
|
||||||
|
|
||||||
After install, the first thing you do is: <b>set your environment variables</b> in `.env.local`
|
Then, set the environment variables in `.env.local` to match the ones from your store.
|
||||||
|
|
||||||
|
## Contribute
|
||||||
|
|
||||||
|
Our commitment to Open Source can be found [here](https://vercel.com/oss).
|
||||||
|
|
||||||
|
If you find an issue with the provider or want a new feature, feel free to open a PR or [create a new issue](https://github.com/vercel/commerce/issues).
|
||||||
|
|
||||||
|
## Troubleshoot
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>I already own a BigCommerce store. What should I do?</summary>
|
||||||
|
<br>
|
||||||
|
First thing you do is: <b>set your environment variables</b>
|
||||||
|
<br>
|
||||||
|
<br>
|
||||||
|
.env.local
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
BIGCOMMERCE_STOREFRONT_API_URL=<>
|
BIGCOMMERCE_STOREFRONT_API_URL=<>
|
||||||
@ -50,331 +39,21 @@ BIGCOMMERCE_STORE_API_CLIENT_ID=<>
|
|||||||
BIGCOMMERCE_CHANNEL_ID=<>
|
BIGCOMMERCE_CHANNEL_ID=<>
|
||||||
```
|
```
|
||||||
|
|
||||||
## General Usage
|
If your project was started with a "Deploy with Vercel" button, you can use Vercel's CLI to retrieve these credentials.
|
||||||
|
|
||||||
### CommerceProvider
|
1. Install Vercel CLI: `npm i -g vercel`
|
||||||
|
2. Link local instance with Vercel and Github accounts (creates .vercel file): `vercel link`
|
||||||
|
3. Download your environment variables: `vercel env pull .env.local`
|
||||||
|
|
||||||
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.
|
Next, you're free to customize the starter. More updates coming soon. Stay tuned.
|
||||||
|
|
||||||
```jsx
|
</details>
|
||||||
...
|
|
||||||
import { CommerceProvider } from '@bigcommerce/storefront-data-hooks'
|
|
||||||
|
|
||||||
const App = ({ locale = 'en-US', children }) => {
|
<details>
|
||||||
return (
|
<summary>BigCommerce shows a Coming Soon page and requests a Preview Code</summary>
|
||||||
<CommerceProvider locale={locale}>
|
<br>
|
||||||
{children}
|
After Email confirmation, Checkout should be manually enabled through BigCommerce platform. Look for "Review & test your store" section through BigCommerce's dashboard.
|
||||||
</CommerceProvider>
|
<br>
|
||||||
)
|
<br>
|
||||||
}
|
BigCommerce team has been notified and they plan to add more detailed about this subject.
|
||||||
...
|
</details>
|
||||||
```
|
|
||||||
|
|
||||||
### 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: LineItem) => count + item.quantity
|
|
||||||
|
|
||||||
const CartNumber = () => {
|
|
||||||
const { data } = useCart()
|
|
||||||
const itemsCount = data?.lineItems.reduce(countItem, 0) ?? 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))
|
|
||||||
|
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.
|
@ -1,2 +1,4 @@
|
|||||||
|
COMMERCE_PROVIDER=shopify
|
||||||
|
|
||||||
NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN=
|
NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN=
|
||||||
NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN=
|
NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN=
|
||||||
|
@ -1,57 +1,28 @@
|
|||||||
## Table of Contents
|
## Shopify Provider
|
||||||
|
|
||||||
- [Getting Started](#getting-started)
|
**Demo:** https://shopify.demo.vercel.store/
|
||||||
- [Modifications](#modifications)
|
|
||||||
- [Adding item to Cart](#adding-item-to-cart)
|
|
||||||
- [Proceed to Checkout](#proceed-to-checkout)
|
|
||||||
- [General Usage](#general-usage)
|
|
||||||
- [CommerceProvider](#commerceprovider)
|
|
||||||
- [useCommerce](#usecommerce)
|
|
||||||
- [Hooks](#hooks)
|
|
||||||
- [usePrice](#useprice)
|
|
||||||
- [useAddItem](#useadditem)
|
|
||||||
- [useRemoveItem](#useremoveitem)
|
|
||||||
- [useUpdateItem](#useupdateitem)
|
|
||||||
- [APIs](#apis)
|
|
||||||
- [getProduct](#getproduct)
|
|
||||||
- [getAllProducts](#getallproducts)
|
|
||||||
- [getAllCollections](#getallcollections)
|
|
||||||
- [getAllPages](#getallpages)
|
|
||||||
|
|
||||||
# Shopify Storefront Data Hooks
|
Before getting starter, a [Shopify](https://www.shopify.com/) account and store is required before using the provider.
|
||||||
|
|
||||||
Collection of hooks and data fetching functions to integrate Shopify in a React application. Designed to work with [Next.js Commerce](https://demo.vercel.store/).
|
Next, copy the `.env.template` file in this directory to `.env.local` in the main directory (which will be ignored by Git):
|
||||||
|
|
||||||
## Getting Started
|
```bash
|
||||||
|
cp framework/shopify/.env.template .env.local
|
||||||
1. Install dependencies:
|
|
||||||
|
|
||||||
```
|
|
||||||
yarn add shopify-buy
|
|
||||||
yarn add @types/shopify-buy
|
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Environment variables need to be set:
|
Then, set the environment variables in `.env.local` to match the ones from your store.
|
||||||
|
|
||||||
```
|
## Contribute
|
||||||
SHOPIFY_STORE_DOMAIN=
|
|
||||||
SHOPIFY_STOREFRONT_ACCESS_TOKEN=
|
|
||||||
NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN=
|
|
||||||
NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN=
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Point the framework to `shopify` by updating `tsconfig.json`:
|
Our commitment to Open Source can be found [here](https://vercel.com/oss).
|
||||||
|
|
||||||
```
|
If you find an issue with the provider or want a new feature, feel free to open a PR or [create a new issue](https://github.com/vercel/commerce/issues).
|
||||||
"@framework/*": ["framework/shopify/*"],
|
|
||||||
"@framework": ["framework/shopify"]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Modifications
|
## Modifications
|
||||||
|
|
||||||
These modifications are temporarily until contributions are made to remove them.
|
These modifications are temporarily until contributions are made to remove them.
|
||||||
|
|
||||||
#### Adding item to Cart
|
### Adding item to Cart
|
||||||
|
|
||||||
```js
|
```js
|
||||||
// components/product/ProductView/ProductView.tsx
|
// components/product/ProductView/ProductView.tsx
|
||||||
@ -72,7 +43,7 @@ const ProductView: FC<Props> = ({ product }) => {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Proceed to Checkout
|
### Proceed to Checkout
|
||||||
|
|
||||||
```js
|
```js
|
||||||
// components/cart/CartSidebarView/CartSidebarView.tsx
|
// components/cart/CartSidebarView/CartSidebarView.tsx
|
||||||
@ -88,114 +59,6 @@ const CartSidebarView: FC = () => {
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## General Usage
|
|
||||||
|
|
||||||
### CommerceProvider
|
|
||||||
|
|
||||||
Provider component that creates the commerce context for children.
|
|
||||||
|
|
||||||
```js
|
|
||||||
import { CommerceProvider } from '@framework'
|
|
||||||
|
|
||||||
const App = ({ children }) => {
|
|
||||||
return <CommerceProvider locale={locale}>{children}</CommerceProvider>
|
|
||||||
}
|
|
||||||
|
|
||||||
export default App
|
|
||||||
```
|
|
||||||
|
|
||||||
### useCommerce
|
|
||||||
|
|
||||||
Returns the configs that are defined in the nearest `CommerceProvider`. Also provides access to Shopify's `checkout` and `shop`.
|
|
||||||
|
|
||||||
```js
|
|
||||||
import { useCommerce } from 'nextjs-commerce-shopify'
|
|
||||||
|
|
||||||
const { checkout, shop } = useCommerce()
|
|
||||||
```
|
|
||||||
|
|
||||||
- `checkout`: The information required to checkout items and pay ([Documentation](https://shopify.dev/docs/storefront-api/reference/checkouts/checkout)).
|
|
||||||
- `shop`: Represents a collection of the general settings and information about the shop ([Documentation](https://shopify.dev/docs/storefront-api/reference/online-store/shop/index)).
|
|
||||||
|
|
||||||
## Hooks
|
|
||||||
|
|
||||||
### usePrice
|
|
||||||
|
|
||||||
Display the product variant price according to currency and locale.
|
|
||||||
|
|
||||||
```js
|
|
||||||
import usePrice from '@framework/product/use-price'
|
|
||||||
|
|
||||||
const { price } = usePrice({
|
|
||||||
amount,
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
Takes in either `amount` or `variant`:
|
|
||||||
|
|
||||||
- `amount`: A price value for a particular item if the amount is known.
|
|
||||||
- `variant`: A shopify product variant. Price will be extracted from the variant.
|
|
||||||
|
|
||||||
### useAddItem
|
|
||||||
|
|
||||||
```js
|
|
||||||
import { useAddItem } from '@framework/cart'
|
|
||||||
|
|
||||||
const AddToCartButton = ({ variantId, quantity }) => {
|
|
||||||
const addItem = useAddItem()
|
|
||||||
|
|
||||||
const addToCart = async () => {
|
|
||||||
await addItem({
|
|
||||||
variantId,
|
|
||||||
})
|
|
||||||
}
|
|
||||||
|
|
||||||
return <button onClick={addToCart}>Add To Cart</button>
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### useRemoveItem
|
|
||||||
|
|
||||||
```js
|
|
||||||
import { useRemoveItem } from '@framework/cart'
|
|
||||||
|
|
||||||
const RemoveButton = ({ item }) => {
|
|
||||||
const removeItem = useRemoveItem()
|
|
||||||
|
|
||||||
const handleRemove = async () => {
|
|
||||||
await removeItem({ id: item.id })
|
|
||||||
}
|
|
||||||
|
|
||||||
return <button onClick={handleRemove}>Remove</button>
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### useUpdateItem
|
|
||||||
|
|
||||||
```js
|
|
||||||
import { useUpdateItem } from '@framework/cart'
|
|
||||||
|
|
||||||
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}
|
|
||||||
/>
|
|
||||||
)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## APIs
|
## APIs
|
||||||
|
|
||||||
Collections of APIs to fetch data from a Shopify store.
|
Collections of APIs to fetch data from a Shopify store.
|
||||||
|
Loading…
x
Reference in New Issue
Block a user