crowetic/commerce
1
0
Fork 1
mirror of https://github.com/vercel/commerce.git synced 2025-05-18 07:26:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated docs

Browse Source
This commit is contained in:
LFades 2022-01-27 16:35:58 -05:00
parent 5484c2abe6
commit f1e0aa9d75
9 changed files with 78 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@ -35,11 +35,10 @@ Next.js Commerce integrates out-of-the-box with BigCommerce, Shopify, Swell, Sal
## Considerations ## Considerations
- `framework/commerce` contains all types, helpers and functions to be used as base to build a new **provider**. - `packages/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 (`framework/commerce`). - **Providers** live under `packages`'s root folder and they will extend Next.js Commerce types and functionality (`packages/commerce`).
- 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. - 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`
## Configuration ## Configuration
@ -55,18 +54,9 @@ NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN=xxxxxxx.myshopify.com NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN=xxxxxxx.myshopify.com
``` ```
And check that the `tsconfig.json` resolves to the chosen provider:
```
"@framework": ["framework/shopify"],
"@framework/*": ["framework/shopify/*"]
```
That's it!
### Features ### Features
Every provider defines the features that it supports under `framework/{provider}/commerce.config.json` Every provider defines the features that it supports under `packages/{provider}/src/commerce.config.json`
#### Features Available #### Features Available
@ -98,9 +88,7 @@ For example: Turning `cart` off will disable Cart capabilities.
### How to create a new provider ### How to create a new provider
🔔 New providers are on hold [until we have a new API for commerce](https://github.com/vercel/commerce/pull/252) 🔔 Follow our docs for [Adding a new Commerce Provider](packages/commerce/new-provider.md).
Follow our docs for [Adding a new Commerce Provider](framework/commerce/new-provider.md).
If you succeeded building a provider, submit a PR with a valid demo and we'll review it asap. If you succeeded building a provider, submit a PR with a valid demo and we'll review it asap.
@ -119,7 +107,7 @@ Our commitment to Open Source can be found [here](https://vercel.com/oss).
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) 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. People actively working on this project: @okbel, @lfades, @dominiksipowicz, @gbibeaul.
## Troubleshoot ## Troubleshoot

2
packages/bigcommerce/README.md
View File

@ -9,7 +9,7 @@ With the deploy button below you'll be able to have a [BigCommerce](https://www.
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): 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):
```bash ```bash
cp framework/bigcommerce/.env.template .env.local cp packages/bigcommerce/.env.template .env.local
``` ```
Then, set the environment variables in `.env.local` to match the ones from your store. Then, set the environment variables in `.env.local` to match the ones from your store.

170
packages/commerce/new-provider.md
View File

@ -4,108 +4,82 @@
A commerce provider is a headless e-commerce platform that integrates with the [Commerce Framework](./README.md). Right now we have the following providers: A commerce provider is a headless e-commerce platform that integrates with the [Commerce Framework](./README.md). Right now we have the following providers:
- Local ([framework/local](../local)) - Local ([packages/local](../local))
- Shopify ([framework/shopify](../shopify)) - Shopify ([packages/shopify](../shopify))
- Swell ([framework/swell](../swell)) - Swell ([packages/swell](../swell))
- BigCommerce ([framework/bigcommerce](../bigcommerce)) - BigCommerce ([packages/bigcommerce](../bigcommerce))
- Vendure ([framework/vendure](../vendure)) - Vendure ([packages/vendure](../vendure))
- Saleor ([framework/saleor](../saleor)) - Saleor ([packages/saleor](../saleor))
- OrderCloud ([framework/ordercloud](../ordercloud)) - OrderCloud ([packages/ordercloud](../ordercloud))
- Spree ([framework/spree](../spree)) - Spree ([packages/spree](../spree))
- Kibo Commerce ([framework/kibocommerce](../kibocommerce)) - Kibo Commerce ([packages/kibocommerce](../kibocommerce))
- Commerce.js ([framework/commercejs](../commercejs)) - Commerce.js ([packages/commercejs](../commercejs))
Adding a commerce provider means adding a new folder in `framework` with a folder structure like the next one: Adding a commerce provider means adding a new folder in `packages` with a folder structure like the next one:
- `api` - `src`
- index.ts - `api`
- `product` - index.ts
- usePrice - `product`
- useSearch - usePrice
- getProduct - useSearch
- getAllProducts - getProduct
- `wishlist` - getAllProducts
- useWishlist - `wishlist`
- useAddItem - useWishlist
- useRemoveItem - useAddItem
- `auth` - useRemoveItem
- useLogin - `auth`
- useLogout - useLogin
- useSignup - useLogout
- `customer` - useSignup
- useCustomer - `customer`
- getCustomerId - useCustomer
- getCustomerWistlist - getCustomerId
- `cart` - getCustomerWistlist
- useCart - `cart`
- useAddItem - useCart
- useRemoveItem - useAddItem
- useUpdateItem - useRemoveItem
- useUpdateItem
- `index.ts`
- `provider.ts`
- `commerce.config.json`
- `next.config.cjs`
- `package.json`
- `tsconfig.json`
- `env.template` - `env.template`
- `index.ts`
- `provider.ts`
- `commerce.config.json`
- `next.config.js`
- `README.md` - `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) `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. > **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 app imports from the provider directly instead of the core commerce folder (`packages/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.
## Updating the list of known providers ## Updating the list of known providers
Open [./config.js](./config.js) and add the provider name to the list in `PROVIDERS`. Open [/site/commerce-config.js](/site/commerce-config.js) and add the provider name to the list in `PROVIDERS`.
Then, open [/.env.template](/.env.template) and add the provider name in the first line. Then, open [/site/.env.template](/site/.env.template) and add the provider name to the list there too.
## Adding the provider hooks ## 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: 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 ```tsx
import type { ReactNode } from 'react' import { getCommerceProvider, useCommerce as useCoreCommerce } from '@vercel/commerce'
import { import { bigcommerceProvider, BigcommerceProvider } from './provider'
CommerceConfig,
CommerceProvider as CoreCommerceProvider,
useCommerce as useCoreCommerce,
} from '@commerce'
import { bigcommerceProvider } from './provider'
import type { BigcommerceProvider } from './provider'
export { bigcommerceProvider } export { bigcommerceProvider }
export type { BigcommerceProvider } export type { BigcommerceProvider }
export const bigcommerceConfig: CommerceConfig = { export const CommerceProvider = getCommerceProvider(bigcommerceProvider)
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>() export const useCommerce = () => useCoreCommerce<BigcommerceProvider>()
``` ```
The exported types and components extend from the core ones exported by `@commerce`, which refers to `framework/commerce`. The exported types and components extend from the core ones exported by `@vercel/commerce`, which refers to `packages/commerce`.
The `bigcommerceProvider` object looks like this: The `bigcommerceProvider` object looks like this:
@ -146,33 +120,23 @@ export const bigcommerceProvider = {
export type BigcommerceProvider = typeof bigcommerceProvider export type BigcommerceProvider = typeof bigcommerceProvider
``` ```
The provider object, in this case `bigcommerceProvider`, has to match the `Provider` type defined in [framework/commerce](./index.ts). The provider object, in this case `bigcommerceProvider`, has to match the `Provider` type defined in [packages/commerce](./src/index.tsx).
A hook handler, like `useCart`, looks like this: A hook handler, like `useCart`, looks like this:
```tsx ```tsx
import { useMemo } from 'react' import { useMemo } from 'react'
import { SWRHook } from '@commerce/utils/types' import { SWRHook } from '@vercel/commerce/utils/types'
import useCart, { UseCart, FetchCartInput } from '@commerce/cart/use-cart' import useCart, { UseCart } from '@vercel/commerce/cart/use-cart'
import { normalizeCart } from '../lib/normalize' import type { GetCartHook } from '@vercel/commerce/types/cart'
import type { Cart } from '../types'
export default useCart as UseCart<typeof handler> export default useCart as UseCart<typeof handler>
export const handler: SWRHook< export const handler: SWRHook<GetCartHook> = {
Cart | null,
{},
FetchCartInput,
{ isEmpty?: boolean }
> = {
fetchOptions: { fetchOptions: {
url: '/api/cart', url: '/api/cart',
method: 'GET', method: 'GET',
}, },
async fetcher({ input: { cartId }, options, fetch }) {
const data = cartId ? await fetch(options) : null
return data && normalizeCart(data)
},
useHook: useHook:
({ useData }) => ({ useData }) =>
(input) => { (input) => {
@ -200,21 +164,15 @@ In the case of data fetching hooks like `useCart` each handler has to implement
```tsx ```tsx
import { useCallback } from 'react' import { useCallback } from 'react'
import type { MutationHook } from '@commerce/utils/types' import type { MutationHook } from '@vercel/commerce/utils/types'
import { CommerceError } from '@commerce/utils/errors' import { CommerceError } from '@vercel/commerce/utils/errors'
import useAddItem, { UseAddItem } from '@commerce/cart/use-add-item' import useAddItem, { UseAddItem } from '@vercel/commerce/cart/use-add-item'
import { normalizeCart } from '../lib/normalize' import type { AddItemHook } from '@vercel/commerce/types/cart'
import type {
Cart,
BigcommerceCart,
CartItemBody,
AddCartItemBody,
} from '../types'
import useCart from './use-cart' import useCart from './use-cart'
export default useAddItem as UseAddItem<typeof handler> export default useAddItem as UseAddItem<typeof handler>
export const handler: MutationHook<Cart, {}, CartItemBody> = { export const handler: MutationHook<AddItemHook> = {
fetchOptions: { fetchOptions: {
url: '/api/cart', url: '/api/cart',
method: 'POST', method: 'POST',
@ -229,12 +187,12 @@ export const handler: MutationHook<Cart, {}, CartItemBody> = {
}) })
} }
const data = await fetch<BigcommerceCart, AddCartItemBody>({ const data = await fetch({
...options, ...options,
body: { item }, body: { item },
}) })
return normalizeCart(data) return data
}, },
useHook: useHook:
({ fetch }) => ({ fetch }) =>
@ -276,9 +234,3 @@ When creating a PR for a new provider, include this list in the PR description a
* [ ] Custom checkout * [ ] Custom checkout
* [ ] Typing (in progress) * [ ] Typing (in progress)
* [ ] Tests * [ ] Tests
## 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.

2
packages/commercejs/README.md
View File

@ -7,7 +7,7 @@ To use this provider you must have a [Commerce.js account](https://commercejs.co
Next, copy the `.env.template` file in this directory to `.env.local` in the main directory (which will be ignored by Git): Next, copy the `.env.template` file in this directory to `.env.local` in the main directory (which will be ignored by Git):
```bash ```bash
cp framework/commercejs/.env.template .env.local cp packages/commercejs/.env.template .env.local
``` ```
Then, set the environment variables in `.env.local` to match the ones from your store. You'll need your Commerce.js public API key, which can be found in your Commerce.js dashboard in the `Developer -> API keys` section. Then, set the environment variables in `.env.local` to match the ones from your store. You'll need your Commerce.js public API key, which can be found in your Commerce.js dashboard in the `Developer -> API keys` section.

2
packages/kibocommerce/README.md
View File

@ -3,7 +3,7 @@
If you already have a Kibo Commerce 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): If you already have a Kibo Commerce 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):
```bash ```bash
cp framework/kibocommerce/.env.template .env.local cp packages/kibocommerce/.env.template .env.local
``` ```
Then, set the environment variables in `.env.local` to match the ones from your store. Then, set the environment variables in `.env.local` to match the ones from your store.

2
packages/saleor/README.md
View File

@ -9,7 +9,7 @@ This provider requires Saleor **3.x** or higher.
Copy the `.env.template` file in this directory to `.env.local` in the main directory (which will be ignored by Git): Copy the `.env.template` file in this directory to `.env.local` in the main directory (which will be ignored by Git):
```bash ```bash
cp framework/saleor/.env.template .env.local cp packages/saleor/.env.template .env.local
``` ```
Then, set the environment following variables in your `.env.local`. Both, `NEXT_PUBLIC_SALEOR_API_URL` and `COMMERCE_IMAGE_HOST` must point to your own Saleor instance. Then, set the environment following variables in your `.env.local`. Both, `NEXT_PUBLIC_SALEOR_API_URL` and `COMMERCE_IMAGE_HOST` must point to your own Saleor instance.

2
packages/shopify/README.md
View File

@ -7,7 +7,7 @@ Before getting started, a [Shopify](https://www.shopify.com/) account and store
Next, copy the `.env.template` file in this directory to `.env.local` in the main directory (which will be ignored by Git): Next, copy the `.env.template` file in this directory to `.env.local` in the main directory (which will be ignored by Git):
```bash ```bash
cp framework/shopify/.env.template .env.local cp packages/shopify/.env.template .env.local
``` ```
Then, set the environment variables in `.env.local` to match the ones from your store. Then, set the environment variables in `.env.local` to match the ones from your store.

4
packages/spree/README.md
View File

@ -12,10 +12,10 @@ An integration of [Spree Commerce](https://spreecommerce.org/) within NextJS Com
1. Setup Nextjs Commerce - [instructions for setting up NextJS Commerce][2]. 1. Setup Nextjs Commerce - [instructions for setting up NextJS Commerce][2].
1. Copy the `.env.template` file in this directory (`/framework/spree`) to `.env.local` in the main directory 1. Copy the `.env.template` file in this directory (`/packages/spree`) to `.env.local` in the main directory
```bash ```bash
cp framework/spree/.env.template .env.local cp packages/spree/.env.template .env.local
``` ```
1. Set `NEXT_PUBLIC_SPREE_CATEGORIES_TAXONOMY_PERMALINK` and `NEXT_PUBLIC_SPREE_BRANDS_TAXONOMY_PERMALINK` environment variables: 1. Set `NEXT_PUBLIC_SPREE_CATEGORIES_TAXONOMY_PERMALINK` and `NEXT_PUBLIC_SPREE_BRANDS_TAXONOMY_PERMALINK` environment variables:

6
packages/vendure/README.md
View File

@ -28,8 +28,10 @@ This provider makes use of GraphQL code generation. The [schema.graphql](./schem
When developing the provider, changes to any GraphQL operations should be followed by re-generation of the types and schema files: When developing the provider, changes to any GraphQL operations should be followed by re-generation of the types and schema files:
From the project root dir, run From the package dir, run
```sh ```sh
graphql-codegen --config ./framework/vendure/codegen.json yarn generate
# or
npm run generate
``` ```