asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: update Next.js documentation based on the new storefront (#1880)

Browse Source 
* update next.js storefront docs

* made changes to Next.js sections
This commit is contained in:
Shahed Nasser
2022-07-20 12:08:08 +03:00
committed by GitHub
parent f623a85c5d
commit 45dcf420c6
3 changed files with 182 additions and 185 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/content/add-plugins/paypal.md
+32 -141
View File
@@ -22,7 +22,9 @@ Additionally, you need a Medusa server installed and set up. If not, you can fol
You also need [Medusa Admin](../admin/quickstart.md) installed to enable PayPal as a payment provider. You can alternatively use our [REST APIs](https://docs.medusajs.com/api/admin/auth).
## Plugin Installation
## Medusa Server
### Install the PayPal Plugin
In the root of your Medusa server, run the following command to install the PayPal plugin:
@@ -30,7 +32,7 @@ In the root of your Medusa server, run the following command to install the PayP
npm install medusa-payment-paypal
```
### Plugin Configuration
### Configure the PayPal Plugin
Next, you need to add configurations for your PayPal plugin.
@@ -68,7 +70,15 @@ That’s all you need to install PayPal on your Medusa server!
## Admin Setup
The next step is to enable PayPal as a payment provider in at least one region from the Medusa Admin.
This section will guide you through adding PayPal as a payment provider in a region using your Medusa admin dashboard.
This step is required for you to be able to use PayPal as a payment provider in your storefront.
### Admin Prerequisites
If you don’t have a Medusa admin installed, make sure to follow along with [the guide on how to install it](../admin/quickstart.md) before continuing with this section.
### Add PayPal to Regions
Run your Medusa server and Medusa admin, then open the Medusa admin and login.
@@ -86,171 +96,52 @@ Once you’re done, click Save. PayPal is now a payment provider in your store i
This section will take you through the steps to add PayPal as a payment method on the storefront. It includes the steps necessary when using one of Medusa’s official storefronts as well as your own custom React-based storefront.
### Storefront Prerequisites
All storefronts require that you obtain your PayPal Client ID. You can retrieve it from your PayPal developer dashboard.
### Process Overview
Aside from the Next.js Storefront, you need to add the implementation with PayPal manually.
:::note
It is recommended to read through the [Frontend Checkout Flow](/advanced/storefront/how-to-implement-checkout-flow) first to fully understand how payment is implemented on the storefront.
:::
### Process Overview
Although the 3 next sections have different implementations to add PayPal into your storefront, they essentially follow the same process:
Although the next sections have different implementations to add PayPal into your storefront, they essentially follow the same process:
1. Show PayPal’s button if the PayPal provider is available for the current cart.
2. When the button is clicked, open PayPal’s payment portal and wait for the customer to authorize the payment.
3. If the payment is authorized successfully, set PayPal’s [Payment Session](../advanced/backend/payment/overview.md#payment-session) as the session used to perform the payment for the current cart, then update the Payment Session on the server with the data received from PayPal’s payment portal. This data is essential to the server to verify the authorization and perform additional payment processing later such as capturing payment.
4. Complete the cart to create the order.
:::note
:::info
In Medusa, by default, payments are authorized during checkout, but the payment is not captured right away. The payment should be manually [captured from the Medusa Admin](#capture-payment).
:::
## Next.js Storefront
### Add to Next.js Storefront
Medusa has a Next.js storefront that you can easily use with your Medusa server. If you don’t have the storefront installed, you can follow [this quickstart guide](../starters/nextjs-medusa-starter.md).
In your `.env.local` file (or the file you’re using for your environment variables), add the following variable with its value set to the Client ID:
In your `.env.local` file (or the file you’re using for your environment variables), add the following variable:
```bash
NEXT_PUBLIC_PAYPAL_CLIENT_ID=<CLIENT_ID>
NEXT_PUBLIC_PAYPAL_CLIENT_ID=<YOUR_CLIENT_ID>
```
Then, install [PayPal’s React components](https://www.npmjs.com/package/@paypal/react-paypal-js) library:
Make sure to replace `<YOUR_CLIENT_ID>` with your PayPal Client ID.
```bash npm2yarn
npm install @paypal/react-paypal-js
```
Now, if you run your Medusa server and your storefront, on checkout you’ll be able to use PayPal].
Next, create a new file `components/checkout/paypal.jsx` with the following content:
```jsx
import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js";
import React, { useContext, useState } from "react";
import { BiLeftArrowAlt } from "react-icons/bi";
import DisplayContext from "../../context/display-context";
import StoreContext from "../../context/store-context";
import { createClient } from "../../utils/client"
import styles from "../../styles/injectable-payment-card.module.css";
import { useRouter } from "next/router";
const paypalClientId = process.env.NEXT_PUBLIC_PAYPAL_CLIENT_ID || ""
const Paypal = () => {
const [error, setError] = useState(null);
const [processing, setProcessing] = useState("");
const { cart, setPaymentSession } = useContext(StoreContext);
const { updateCheckoutStep } = useContext(DisplayContext);
const router = useRouter();
const client = createClient()
const handleSubmit = async (data, actions) => {
actions.order.authorize().then(async (authorization) => {
if (authorization.status !== 'COMPLETED') {
setError(`An error occurred, status: ${authorization.status}`);
setProcessing(false);
return;
}
const { cart } = await setPaymentSession("paypal")
if (!cart) {
setProcessing(false)
return
}
await client.carts.updatePaymentSession(cart.id, "paypal", {
data: {
data: {
...authorization
}
}
});
setError(null);
setProcessing(false);
router.push(`/payment`);
})
};
return (
<>
<PayPalScriptProvider options={{
"client-id": paypalClientId,
"currency": cart.region.currency_code.toUpperCase(),
"intent": "authorize"
}}>
{error && (
<span className="text-rose-500 mt-4">{error}</span>
)}
<PayPalButtons
style={{ layout: "horizontal" }}
onApprove={handleSubmit}
disabled={processing}
/>
</PayPalScriptProvider>
<button
className={styles.stepBack}
onClick={() => updateCheckoutStep(2)}
>
<BiLeftArrowAlt /> Back to shipping method
</button>
</>
)
}
export default Paypal
```
Here’s briefly what this code snippet does:
1. This component renders a PayPal button to initialize the payment using PayPal. You use the components from the PayPal React components library to render the button and you pass the `PayPalScriptProvider` component the Client ID.
2. When the button is clicked, the `handleSubmit` function is executed. In this method, you initialize the payment authorization using `actions.order.authorize()`. It takes the customer to another page to log in with PayPal and authorize the payment.
3. After the payment is authorized successfully on PayPal’s portal, the fulfillment function passed to `actions.order.authorize().then` will be executed.
4. In the fulfillment function, you first ensure that the payment session for the PayPal payment provider is set as the [selected Payment Session in the cart](https://docs.medusajs.com/api/store/cart/select-a-payment-session). Then, you send a request to the server to [update the payment session](https://docs.medusajs.com/api/store/cart/update-a-payment-session) data with the authorization data received from PayPal.
5. After all that is done successfully, you navigate to the `/payment` page which will automatically [complete the cart and place the order](https://docs.medusajs.com/api/store/cart/complete-a-cart).
The last step is to add this component as the component to render when PayPal is available as a payment provider.
In `src/checkout/payment-step.jsx` you’ll find in the return statement a switch statement that checks the payment provider for each payment session and renders the component based on the ID. Add before the `default` case a case for `paypal`:
```jsx
switch (ps.provider_id) {
case "stripe":
//..
case "manual":
//...
case "paypal":
return (
<div key="paypal">
<h2>PayPal Payment</h2>
<Paypal />
</div>
)
default:
return null;
}
```
Make sure to also import the `Paypal` component at the top of the file:
```jsx
import Paypal from "./paypal";
```
That’s all you need to integrate PayPal into the Next.js storefront.
Now, start the Medusa server and the Next.js storefront server. Try adding an item into the cart and proceeding to checkout. When you reach the payment step, you should see the PayPal button.
![PayPal Button](https://i.imgur.com/bDhBcV3.png)
![PayPal Button](https://i.imgur.com/F8OvsOJ.png)
You can test out the payment with PayPal using your sandbox account.
### Gatsby Storefront
### Add to Gatsby Storefront
Medusa also has a Gatsby storefront that you can use as your ecommerce storefront. If you don’t have the storefront installed, you can follow [this quickstart guide](../starters/gatsby-medusa-starter.md).
@@ -399,7 +290,7 @@ Now, start the Medusa server and the Gatsby storefront server. Try adding an ite
You can test out the payment with PayPal using your sandbox account.
### Custom Storefront
### Add to Custom Storefront
This section guides you to add PayPal into a React-based framework. The instructions are general instructions that you can use in your storefront.
@@ -503,7 +394,7 @@ If you run the Medusa server and the storefront server, you should see the PayPa
![PayPal Button](https://i.imgur.com/PsibgPY.png)
## Capture Payment
## Capture Payments
After the customer places an order, you can see the order on the admin panel. In the payment information under the “Payment” section, you should see a “Capture” button.
docs/content/add-plugins/stripe.md
+16 -20
View File
@@ -28,7 +28,7 @@ This section guides you over the steps necessary to add Stripe as a payment prov
If you don’t have a Medusa server installed yet, you must follow our [quickstart guide](../quickstart/quick-start) first.
### Plugin Installation
### Install the Stripe Plugin
In the root of your Medusa server, run the following command to install the stripe plugin:
@@ -36,7 +36,7 @@ In the root of your Medusa server, run the following command to install the stri
npm install medusa-payment-stripe
```
### Plugin Configuration
### Configure the Stripe Plugin
Next, you need to add configurations for your stripe plugin.
@@ -63,7 +63,7 @@ You might find that this code is already available but commented out. You can pr
The Stripe plugin uses 2 configuration options. The `api_key` is essential to both your development and production environments. As for the `webhook_secret`, it’s essential for your production environment. So, if you’re only using Stripe for development you can skip adding the value for this option at the moment.
### Retrieving The Keys
### Retrieve Stripe's Keys
On the [dashboard](https://dashboard.stripe.com) of your Stripe account click on the Developers link at the top right. This will take you to the developer dashboard.
@@ -101,11 +101,11 @@ This section will guide you through adding Stripe as a payment provider in a reg
This step is required for you to be able to use Stripe as a payment provider in your storefront.
### Prerequisites
### Admin Prerequisites
If you don’t have a Medusa admin installed, make sure to follow along with [the guide on how to install it](https://github.com/medusajs/admin#-quickstart) before continuing with this section.
### Adding Stripe
### Add Stripe to Regions
First, make sure that both your Medusa server and Medusa Admin are running.
@@ -123,31 +123,27 @@ Once you’re done, click Save. Stripe is now a payment provider in your store i
This guide will take you through how to set up Stripe payments in your Medusa storefront. It includes the steps necessary when using one of Medusa’s official storefronts as well as your own custom React-based storefront.
### Prerequisites
### Storefront Prerequisites
All storefronts require that you obtain your Stripe’s Publishable Key. You can retrieve it from your Stripe’s developer dashboard by choosing API Keys and then copying the Publishable Key.
### Next.js Storefront
### Add to Next.js Storefront
Medusa has a Next.js storefront that you can easily use with your Medusa server. If you don’t have the storefront installed, you can follow [this quickstart guide](../starters/nextjs-medusa-starter).
In your `.env.local` file (or the file you’re using for your environment variables), add the following variable with its value set to the Publishable Key:
In your `.env.local` file (or the file you’re using for your environment variables), add the following variable:
```jsx
NEXT_PUBLIC_STRIPE_KEY=pk_...
```bash
NEXT_PUBLIC_STRIPE_KEY=<YOUR_PUBLISHABLE_KEY>
```
:::note
This variable might be available in your `.env` file but commented out. You can instead remove the comment and change its value.
:::
Make sure to replace `<YOUR_PUBLISHABLE_KEY>` with your Stripe Publishable Key.
Now, if you run your Medusa server and your storefront, on checkout you’ll be able to use Stripe.
![Next.js Stripe Form](https://i.imgur.com/1XvW776.png)
![Next.js Stripe Form](https://i.imgur.com/h5mWdJT.png)
### Gatsby Storefront
### Add to Gatsby Storefront
Medusa also has a Gatsby storefront that you can use as your ecommerce store. If you don’t have the storefront installed, you can follow [this quickstart guide](../starters/gatsby-medusa-starter).
@@ -167,7 +163,7 @@ Now, if you run your Medusa server and your storefront, on checkout you’ll be
![Gatsby Stripe Form](https://i.imgur.com/1XvW776.png)
### Custom Storefront
### Add to Custom Storefront
This section will go over how to add Stripe into a React-based framework. The instructions are general instructions that you can use in your storefront.
@@ -180,7 +176,7 @@ The integration with stripe must have the following workflow:
3. After the user enters their card details and submits the form, confirm the payment with Stripe.
4. If the payment is confirmed successfully, [complete the order](https://docs.medusajs.com/api/store/cart/complete-a-cart) in Medusa. Otherwise show an error.
#### Installing Dependencies
#### Install Dependencies
Before you start the implementations you need to install the necessary dependencies. You’ll be using Stripe’s React libraries to show the UI and handle the payment confirmation:
@@ -360,7 +356,7 @@ If you run your server and storefront now, you’ll see the Stripe UI element an
![Stripe Form](https://i.imgur.com/NOi8THw.png)
## Capturing Payment
## Capture Payments
After the customer places an order, you’ll be able to see the order on the admin panel. In the payment information under the “Payment” section, you should see a “Capture” button.
docs/content/starters/nextjs-medusa-starter.md
+134 -24
View File
@@ -2,13 +2,7 @@
This document guides you to install and set up the Next.js Storefront for your Medusa Server.
:::info
The Next.js storefront is meant as a starter storefront with basic features. We have an advanced Next.js storefront currently in the works with a better design and more functionalities coming soon!
:::
![Next.js Storefront Quick Look](https://i.imgur.com/HIVLwN4.gif)
![Next.js Storefront Demo](https://i.imgur.com/koJl8uR.gif)
## Prerequisites
@@ -16,21 +10,21 @@ This document assumes you already have a Medusa server installed. If you don’t
## Installation
1\. Create a new Next.js project using the [Medusa starter template](https://github.com/medusajs/nextjs-starter-medusa):
1. Create a new Next.js project using the [Medusa starter template](https://github.com/medusajs/nextjs-starter-medusa):
```bash
npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefront
```
2\. Change to the newly created directory `my-medusa-storefront` and rename the template environment variable file to use environment variables in development:
1. Change to the newly created directory `my-medusa-storefront` and rename the template environment variable file to use environment variables in development:
```bash
mv .env.template .env.local
```
3\. Make sure the Medusa server is running, then run the local Next.js server:
1. Make sure the Medusa server is running, then run the local Next.js server:
```bash npm2yarn
```bash
npm run dev
```
@@ -38,13 +32,131 @@ Your Next.js storefront is now running at `localhost:8000`!
## Development Notes
### Toggle Search Engine Feature
The Next.js storefront by default is compatible with MeiliSearch.
To enable or disable the search engine, change the value of the feature in `store.config.json`:
```json
{
"features": {
"search": false
}
}
```
Then, restart your Next.js server. Depending on whether you enabled or disabled the search engine, the search bar will appear or disappear in the navigation bar accordingly.
### MeiliSearch Integration
If you have the search engine feature enabled, it is expected that you have installed the MeiliSearch plugin on your Medusa server. If not, [follow this guide to install it](../add-plugins/meilisearch.md).
In your Next.js storefront, set the environment variables necessary for the MeiliSearch integration:
```json
NEXT_PUBLIC_SEARCH_ENDPOINT=<YOUR_MEILISEARCH_URL>
NEXT_PUBLIC_SEARCH_API_KEY=<YOUR_API_KEY>
NEXT_PUBLIC_SEARCH_INDEX_NAME=products
```
`<YOUR_MEILISEARCH_URL>` is the URL MeiliSearch is running on. The default is `http://127.0.0.1:7700`.
`NEXT_PUBLIC_SEARCH_INDEX_NAME` is the index name of the products in MeiliSearch. By default, it’s `products`.
`<YOUR_API_KEY>` is the API key used to search through MeiliSearch indexes. To create a new API Key, make sure that the MeiliSearch service is running and send the following request:
```bash
curl \
-X POST '<MEILISEARCH_URL>/keys' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <MEILISEARCH_MASTER_KEY>' \
--data-binary '{
"description": "Search products",
"actions": ["search"],
"indexes": ["products"],
"expiresAt": "2024-01-01T00:00:00Z"
}'
```
Make sure to replace `<MEILISEARCH_URL>` with the URL MeiliSearch is running on and `<MEILISEARCH_MASTER_KEY>` with your MeiliSearch [master key](https://docs.meilisearch.com/learn/security/master_api_keys.html#protecting-a-meilisearch-instance).
Then, restart the Next.js server. You’ll be able to search through available products by clicking the search icon in the navigation bar.
### Algolia Integration
Instead of using the default MeiliSearch search engine, you can switch to using Algolia. Make sure you start by installing the Algolia plugin on your Medusa server. You can do it by [following this guide](../add-plugins/algolia.md).
In your Next.js storefront, set the environment variables necessary for the Algolia integration:
```bash
NEXT_PUBLIC_SEARCH_APP_ID=<YOUR_APP_ID>
NEXT_PUBLIC_SEARCH_API_KEY=<YOUR_SEARCH_API_KEY>
NEXT_PUBLIC_SEARCH_INDEX_NAME=products
```
Where `<YOUR_APP_ID>` and `<YOUR_SEARCH_API_KEY>` are the Algolia App ID and Algolia Search API Key respectively. You can retrieve them from Algolia by going to [API Keys](https://www.algolia.com/account/api-keys/all) in your account settings.
`NEXT_PUBLIC_SEARCH_INDEX_NAME` is the index name of the products in Algolia. By default, it’s `products`.
Next, change the content of `src/lib/search-client.ts` to the following:
```bash
import algoliasearch from "algoliasearch/lite"
const appId = process.env.NEXT_PUBLIC_SEARCH_APP_ID || "" // You should add this to your environment variables
const apiKey = process.env.NEXT_PUBLIC_SEARCH_API_KEY || "test_key"
export const searchClient = algoliasearch(appId, apiKey)
export const SEARCH_INDEX_NAME =
process.env.NEXT_PUBLIC_INDEX_NAME || "products"
```
Then, restart the Next.js server. You’ll be able to search through available products by clicking the search icon in the navigation bar.
![Search Pop-up in Next.js Storefront](https://i.imgur.com/ZLgX5Ad.png)
### Stripe Payment Integration
Stripe integration is supported by default. Make sure you have Stripe installed and enabled on your Medusa server first. You can [follow this guide to learn how to install it](../add-plugins/stripe.md).
Then, in your Next.js storefront, set the environment variable necessary for the Stripe integration:
```bash
NEXT_PUBLIC_STRIPE_KEY=<YOUR_PUBLISHABLE_KEY>
```
Make sure to replace `<YOUR_PUBLISHABLE_KEY>` with your Stripe publishable key. It can be retrieved from your [Stripe dashboard](https://dashboard.stripe.com/) by going to Developers → API Keys.
If you restart your Next.js server you should be able to pay with Stripe on checkout.
![Pay with Stripe on Checkout](https://i.imgur.com/h5mWdJT.png)
### PayPal Payment Integration
PayPal integration is supported by default. Make sure you have PayPal installed and enabled on your Medusa server first. You can [follow this guide to learn how to install it](../add-plugins/paypal.md).
Then, in your Next.js storefront, set the environment variable necessary for the PayPal integration:
```bash
NEXT_PUBLIC_PAYPAL_CLIENT_ID=<YOUR_CLIENT_ID>
```
Make sure to replace `<YOUR_CLIENT_ID>` with your PayPal client ID. You can retrieve it from the [PayPal developer dashboard](https://developer.paypal.com/developer/applications/).
If you restart your Next.js server you should be able to pay with PayPal on checkout.
![Pay with PayPal on Checkout](https://i.imgur.com/F8OvsOJ.png)
### Customization
To customize the pages of the storefront, you can customize the files under the `pages` directory.
To customize the pages of the storefront, you can customize the files under the `src/pages` directory.
To customize the components used in the storefront, you can customize the files under the `components` directory.
To customize the components used in the storefront, you can customize the files under the `src/modules` directory.
To customize the styles of the storefront, you can customize the `styles` directory.
To customize the styles of the storefront, you can customize the `src/styles` directory.
### Change Port
@@ -67,27 +179,25 @@ Then, on your server, update the environment variable `STORE_CORS` to the URL
STORE_CORS=http://localhost:<PORT>
```
:::info
For more details about the Store CORS configuration, check out the [Configure your Server documentation](../usage/configurations.md#storefront-cors).
:::
### Development Resources
You can learn more about development with Next.js through [their documentation](https://nextjs.org/docs/getting-started).
## Storefront Features
- View products and manage your cart.
- View all products and manage your cart.
![Product Page](https://i.imgur.com/wCeWJio.png)
![All Products Page](https://i.imgur.com/1vLAYbH.png)
- Customer authentication and profiles.
![Customer Profile](https://i.imgur.com/etW3b3L.png)
- Full checkout workflow.
![Shipping Details on Checkout](https://i.imgur.com/7la2KhW.png)
![Checkout Page](https://i.imgur.com/VC8SYfb.png)
## What’s Next 🚀
- Check the [Storefront API reference](https://docs.medusajs.com/api/store/auth) for a full list of REST APIs to use on your storefront.
- Learn how to add [Stripe as a payment provider](../add-plugins/stripe.md#nextjs-storefront).
- Learn [how to install Medusa Admin](../admin/quickstart.md).