4
0
forked from crowetic/commerce
commerce/README.md
Tomek Niezgoda d77d000431
Spree Commerce Provider (#484)
* Include @spree/storefront-api-v2-sdk

* Add basic Spree framework structure

* Add Spree as allowed Framework

* Fetch product images, standardize API fetch using Spree SDK

* Include slug and path in products

* Fetch single product during build time

* PLP with searching by category

* Fetch Spree Categories and Brands

* Sort PLP

* Search products by name

* Fix option values collection

* Fix hasNonMasterVariants

* Sort Categories and Brands

* Add configuration to show product options when there's one variant available

* Enable text search for the Spree Framework

* Allow removing line items

* Allow updating line item quantity

* Add __typename to variant options to allow adding the selected variant to the cart

* Use fetch and Request from node-fetch in Spree SDK

* Update Spree SDK fetcher

* Show placeholder message for /chechout and adjust api fetcher type

* Use kebab case instead of camel case

* Remove outdated comments

* Remove outdated comment

* Resolve isColorProductOption duplication

* Type Spree variants and line items and temporarily remove height, width and depth

* Remove outdated comment

* Update comments about cart discounts

* Remove 'spree' prefix from isomorphicConfig and add lastUpdatedProductsPrerenderCount

* Implement getAllProductPaths to prerender some products during build time

* Adjust fetchers to the latest Spree SDK interface

* Add types to Spree taxons mapping

* Revert port change in package.json scripts

* Add basic README describing Spree installation

* Expand README's installation section

* Upgrade Spree SDK to 4.7.0 and add node-fetch to dependencies

* Order providers alphanumerically

Co-authored-by: Damian Legawiec <damian@sparksolutions.co>

* Sort products by available_on when using the Trending sorting in useSearch

* Change the default Spree port to 4000 and update README in sync with Spree Starter changes

* Save primary variant's SKU when normalizing a product from Spree

* Create a new cart if Spree can't find the current using a token

* Add separator to README

* Add missing Error subclass

* Allow placeholder images for products and line items without images

* Add image

* Reset tsconfig.json paths to originla values

* Search taxonomies by permalinks instead of IDs

* Upgrade Spree SDK to version 4.7.1

* Remove references to @framework and use relative paths instead

* Generalize TypeScript and add typings to getPage

* Update fetcher to avoid parsing non-JSON responses

* Use original product image by default instead of resized

* Link to an online demo of the Spree integration in the README

* Flatten fetcher responses

* Include Spree in the list of supported ecommerce backends in README

* Update README.md

* Format Spree's README

* Add link to the Spree demo site in the main README

* Update README.md

* Update README.md

* Allow setting a taxon id for getAllProducts

* Use Spree SDK's JSON:API helpers

* Sort getAllProducts by -updated_at when using a taxonomy

* Remove slash '/' from line item's paths

* Allow filtering variant images by option type

* Upgrade checkout behavior in line with core NextJS Commerce changes

* Remove dummy submitCheckout function

* [NX-24] Display PDP option types sorted by position from Spree

* Supply Spree primary variant if a product has no option variants

* Do not throw an error if a product doesn't have NEXT_PUBLIC_SPREE_IMAGES_OPTION_FILTER

* [NX-43] Uses image transformations when fetching products images

* Use bind to properly call Spree SDK methods and update SDK fetcher in line with SDK 4.12.0

* Fix ESLint issues in useHook

* Support account sign up, login and logout

Also
- Converts the guest cart to a persisted cart tied to the logged in user after log in.
- Fixes issues with use-remove-item. The cart will now properly refresh after an item is removed.
- Uses the logged in user's token to adjust the cart and make other authenticated requests.
- Transparently refreshed the access token of the logged in user with a refresh token. Replays requests to Spree which fail with a 401 error after refreshing the access token.

* Fetch logged in user's cart after login or signup but associate guest cart only after signup

* Support Spree default wishlist show, add and remove wished items operations

* Fetch Spree CMS Pages

* Fix login, handle critical token errors and fix WishlistCard

Fix to WishlistCard changes its props to be consistent with WishlistButton when calling useRemoveItem

* Fix variable name (#574)

Variable name should be `ChevronRight`

* Update get-cart.ts (#474)

include digital items

Co-authored-by: Gonzalo Pozzo <gonzalo.pozzo4@gmail.com>

* Update normalize.ts (#475)

add missing options property to `normalizeLineItem`

Co-authored-by: Gonzalo Pozzo <gonzalo.pozzo4@gmail.com>

* Update add-item.ts (#473)

* Update add-item.ts

include digital items

* Update add-item.ts

include digital items

Co-authored-by: Gonzalo Pozzo <gonzalo.pozzo4@gmail.com>

* fix typo (#572)

Co-authored-by: Gonzalo Pozzo <gonzalo.pozzo4@gmail.com>

* Fix authentication.refreshToken arguments

* Remove redundant comments and logs

* Fix createEmptyCart request to Spree and add option to disable auto login

* Fix formatting issues

* Apply image transformation when fetching images for products in cart

* Replace call to qs with Spree SDK built-in helper

* Upgrade Spree SDK to 5.0.1

* Rename zeitFetch import to vercelFetch

* Abstract fetcher JSON Content-Type checking into separate function

* Rename imageUrl to url

getMediaGallery already provides context for the constant

* Remove return type for getProductPath

The return type can be trivially determined from the returned value.

* Change URL to Spree demo store in root README

Co-authored-by: Gonzalo Pozzo <gonzalo.pozzo4@gmail.com>

* Change label for link to Spree demo store in Spree's README

Co-authored-by: Gonzalo Pozzo <gonzalo.pozzo4@gmail.com>

* Change URL to Spree demo store in Spree's README

Co-authored-by: Gonzalo Pozzo <gonzalo.pozzo4@gmail.com>

* Use only relative paths to /framework/spree from itself

Co-authored-by: tniezg <tomek.niezgoda@mail.com>
Co-authored-by: Damian Legawiec <damian@sparksolutions.co>
Co-authored-by: Robert Nowakowski <aplegatt@gmail.com>
Co-authored-by: Grey <57859708+greyhere@users.noreply.github.com>
Co-authored-by: pfcodes <phil@auroradigit.al>
Co-authored-by: Gonzalo Pozzo <gonzalo.pozzo4@gmail.com>
Co-authored-by: Konrad Kruk <github@konradk.pl>
2021-12-13 17:42:30 -03:00

159 lines
6.2 KiB
Markdown

[![Deploy with Vercel](https://vercel.com/button)](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)
# Next.js Commerce
The all-in-one starter kit for high-performance e-commerce sites. With a few clicks, Next.js developers can clone, deploy and fully customize their own store.
Start right now at [nextjs.org/commerce](https://nextjs.org/commerce)
Demo live at: [demo.vercel.store](https://demo.vercel.store/)
- Shopify Demo: https://shopify.vercel.store/
- Swell Demo: https://swell.vercel.store/
- BigCommerce Demo: https://bigcommerce.vercel.store/
- Vendure Demo: https://vendure.vercel.store
- Saleor Demo: https://saleor.vercel.store/
- Ordercloud Demo: https://ordercloud.vercel.store/
- Spree Demo: https://spree.vercel.store/
## Features
- Performant by default
- SEO Ready
- Internationalization
- Responsive
- UI Components
- Theming
- Standardized Data Hooks
- Integrations - Integrate seamlessly with the most common ecommerce platforms.
- Dark Mode Support
## Integrations
Next.js Commerce integrates out-of-the-box with BigCommerce, Shopify, Swell, Saleor, Vendure and Spree. We plan to support all major ecommerce backends.
## Considerations
- `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`).
- 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`
## Configuration
### How to change providers
Open `.env.local` and change the value of `COMMERCE_PROVIDER` to the provider you would like to use, then set the environment variables for that provider (use `.env.template` as the base).
The setup for Shopify would look like this for example:
```
COMMERCE_PROVIDER=shopify
NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxx
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
Every provider defines the features that it supports under `framework/{provider}/commerce.config.json`
#### Features Available
The following features can be enabled or disabled. This means that the UI will remove all code related to the feature.
For example: Turning `cart` off will disable Cart capabilities.
- cart
- search
- wishlist
- customerAuth
- customCheckout
#### How to turn Features on and off
> NOTE: The selected provider should support the feature that you are toggling. (This means that you can't turn wishlist on if the provider doesn't support this functionality out the box)
- Open `commerce.config.json`
- You'll see a config file like this:
```json
{
"features": {
"wishlist": false,
"customCheckout": true
}
}
```
- Turn `wishlist` on by setting `wishlist` to `true`.
- Run the app and the wishlist functionality should be back on.
### 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](framework/commerce/new-provider.md).
If you succeeded building a provider, submit a PR with a valid demo and we'll review it asap.
## Contribute
Our commitment to Open Source can be found [here](https://vercel.com/oss).
1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
2. Create a new branch `git checkout -b MY_BRANCH_NAME`
3. Install the dependencies: `npm i`
4. Duplicate `.env.template` and rename it to `.env.local`
5. Add proper store values to `.env.local`
6. Run `npm run dev` to build and watch for code changes
## 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
<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
BIGCOMMERCE_STOREFRONT_API_URL=<>
BIGCOMMERCE_STOREFRONT_API_TOKEN=<>
BIGCOMMERCE_STORE_API_URL=<>
BIGCOMMERCE_STORE_API_TOKEN=<>
BIGCOMMERCE_STORE_API_CLIENT_ID=<>
BIGCOMMERCE_CHANNEL_ID=<>
```
If your project was started with a "Deploy with Vercel" button, you can use Vercel's CLI to retrieve these credentials.
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`
Next, you're free to customize the starter. More updates coming soon. Stay tuned.
</details>
<details>
<summary>BigCommerce shows a Coming Soon page and requests a Preview Code</summary>
<br>
After Email confirmation, Checkout should be manually enabled through BigCommerce platform. Look for "Review & test your store" section through BigCommerce's dashboard.
<br>
<br>
BigCommerce team has been notified and they plan to add more details about this subject.
</details>