From 0226a7f0e906a412c8dd8b658baa0e0ce5a85bb1 Mon Sep 17 00:00:00 2001 From: Luis Alvarez Date: Wed, 31 Mar 2021 11:39:34 -0600 Subject: [PATCH] Updated core docs, main repo docs, and new provider docs --- README.md | 39 +++--------------------------- framework/commerce/README.md | 6 +++-- framework/commerce/new-provider.md | 39 ++++++++++++++++++++++++++++-- 3 files changed, 44 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 11f5e03fb..941b1699b 100644 --- a/README.md +++ b/README.md @@ -30,42 +30,9 @@ Next.js Commerce integrates out-of-the-box with BigCommerce and Shopify. We plan - `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 (`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. - **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 @@ -95,9 +62,9 @@ Every provider defines the features that it supports under `framework/{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. ## Contribute diff --git a/framework/commerce/README.md b/framework/commerce/README.md index 660fd957d..ecdebb8c0 100644 --- a/framework/commerce/README.md +++ b/framework/commerce/README.md @@ -21,8 +21,6 @@ - [Commerce API](#commerce-api) - [More](#more) -> 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. - 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: @@ -30,6 +28,10 @@ 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. diff --git a/framework/commerce/new-provider.md b/framework/commerce/new-provider.md index e58b88316..4051c0f01 100644 --- a/framework/commerce/new-provider.md +++ b/framework/commerce/new-provider.md @@ -5,12 +5,47 @@ A commerce provider is a headless e-commerce platform that integrates with the [ - BigCommerce ([framework/bigcommerce](../bigcommerce)) - Shopify ([framework/shopify](../shopify)) -Adding a commerce provider means adding a provider object with handlers for the [Commerce Hooks](./README.md#commerce-hooks) and a Node.js provider for the [Commerce API](./README.md#commerce-api) +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: @@ -201,4 +236,4 @@ export const handler: MutationHook = { 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. \ No newline at end of file +> 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.