api-ref: custom API reference (#4770)
* initialized next.js project * finished markdown sections * added operation schema component * change page metadata * eslint fixes * fixes related to deployment * added response schema * resolve max stack issue * support for different property types * added support for property types * added loading for components * added more loading * type fixes * added oneOf type * removed console * fix replace with push * refactored everything * use static content for description * fixes and improvements * added code examples section * fix path name * optimizations * fixed tag navigation * add support for admin and store references * general enhancements * optimizations and fixes * fixes and enhancements * added search bar * loading enhancements * added loading * added code blocks * added margin top * add empty response text * fixed oneOf parameters * added path and query parameters * general fixes * added base path env variable * small fix for arrays * enhancements * design enhancements * general enhancements * fix isRequired * added enum values * enhancements * general fixes * general fixes * changed oas generation script * additions to the introduction section * added copy button for code + other enhancements * fix response code block * fix metadata * formatted store introduction * move sidebar logic to Tags component * added test env variables * fix code block bug * added loading animation * added expand param + loading * enhance operation loading * made responsive + improvements * added loading provider * fixed loading * adjustments for small devices * added sidebar label for endpoints * added feedback component * fixed analytics * general fixes * listen to scroll for other headings * added sample env file * update api ref files + support new fields * fix for external docs link * added new sections * fix last item in sidebar not showing * move docs content to www/docs * change redirect url * revert change * resolve build errors * configure rewrites * changed to environment variable url * revert changing environment variable name * add environment variable for API path * fix links * fix tailwind settings * remove vercel file * reconfigured api route * move api page under api * fix page metadata * fix external link in navigation bar * update api spec * updated api specs * fixed google lint error * add max-height on request samples * add padding before loading * fix for one of name * fix undefined types * general fixes * remove response schema example * redesigned navigation bar * redesigned sidebar * fixed up paddings * added feedback component + report issue * fixed up typography, padding, and general styling * redesigned code blocks * optimization * added error timeout * fixes * added indexing with algolia + fixes * fix errors with algolia script * redesign operation sections * fix heading scroll * design fixes * fix padding * fix padding + scroll issues * fix scroll issues * improve scroll performance * fixes for safari * optimization and fixes * fixes to docs + details animation * padding fixes for code block * added tab animation * fixed incorrect link * added selection styling * fix lint errors * redesigned details component * added detailed feedback form * api reference fixes * fix tabs * upgrade + fixes * updated documentation links * optimizations to sidebar items * fix spacing in sidebar item * optimizations and fixes * fix endpoint path styling * remove margin * final fixes * change margin on small devices * generated OAS * fixes for mobile * added feedback modal * optimize dark mode button * fixed color mode useeffect * minimize dom size * use new style system * radius and spacing design system * design fixes * fix eslint errors * added meta files * change cron schedule * fix docusaurus configurations * added operating system to feedback data * change content directory name * fixes to contribution guidelines * revert renaming content * added api-reference to documentation workflow * fixes for search * added dark mode + fixes * oas fixes * handle bugs * added code examples for clients * changed tooltip text * change authentication to card * change page title based on selected section * redesigned mobile navbar * fix icon colors * fix key colors * fix medusa-js installation command * change external regex in algolia * change changeset * fix padding on mobile * fix hydration error * update depedencies
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,307 @@
|
||||
---
|
||||
title: 'Get started with Next.js for e-commerce'
|
||||
description: 'Learn how to get started with a Next.js storefront and Medusa. The Next.js Starter includes ready-integrations with plugins like Stripe and Algolia. It offers features like customer accounts, cart and checkout flows, and more.'
|
||||
---
|
||||
|
||||
import Feedback from '@site/src/components/Feedback';
|
||||
import QueryNote from '@site/src/components/QueryNote';
|
||||
import Troubleshooting from '@site/src/components/Troubleshooting'
|
||||
import ModuleXErrorSection from '../troubleshooting/common-installation-errors/_module-x-error.mdx'
|
||||
import CorsErrorSection from '../troubleshooting/cors-issues.md'
|
||||
|
||||
# Next.js Quickstart
|
||||
|
||||
This document guides you to install and set up the Next.js Starter Template.
|
||||
|
||||
<!-- vale docs.We = NO -->
|
||||
|
||||
<QueryNote
|
||||
query={{
|
||||
key: 'ref',
|
||||
value: 'gatsby-medusa-starter'
|
||||
}}
|
||||
admonition={{
|
||||
type: 'note'
|
||||
}}
|
||||
>
|
||||
We've deprecated the Gatsby starter storefront and instead recommend using the Next.js Starter Template or [building your own custom storefront](../storefront/roadmap.mdx).
|
||||
</QueryNote>
|
||||
|
||||
<!-- vale docs.We = YES -->
|
||||
|
||||
|
||||
|
||||
## Instant Deployment to Vercel
|
||||
|
||||
Instead of manually following this guide to install then later deploy the Next.js Starter Template, you can deploy the Next.js Starter Template to Vercel with this button:
|
||||
|
||||
<a
|
||||
href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fmedusajs%2Fnextjs-starter-medusa.git&env=NEXT_PUBLIC_MEDUSA_BACKEND_URL&envDescription=URL%20of%20your%20Medusa%20Backend" class="img-url no-zoom-img">
|
||||
<img src="https://vercel.com/button" alt="Deploy with Vercel" class="no-zoom-img"/>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
This document assumes you already have a Medusa backend installed. If you don’t, you can install the Medusa backend with the following command:
|
||||
|
||||
```bash
|
||||
npx create-medusa-app@latest
|
||||
```
|
||||
|
||||
Learn more about prerequisites of `create-medusa-app` and troubleshooting in [this guide](../create-medusa-app.mdx).
|
||||
|
||||
You should also have Node.js with v16 or greater installed. You can check your Node.js version with the following command:
|
||||
|
||||
```bash noReport
|
||||
node -v
|
||||
```
|
||||
|
||||
You can install Node from the [official website](https://nodejs.org/en/).
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
cd my-medusa-storefront
|
||||
mv .env.template .env.local
|
||||
```
|
||||
|
||||
3\. Make sure the Medusa backend is running, then run the local Next.js server:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Your Next.js Starter Template is now running at `localhost:8000`
|
||||
|
||||
<Feedback
|
||||
event="survey_nextjs_quickstart"
|
||||
question="Did you set up the storefront successfully?"
|
||||
positiveQuestion="Is there anything that should improved?"
|
||||
negativeQuestion="Please describe the issue you faced."
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Installation
|
||||
|
||||
<Troubleshooting
|
||||
sections={[
|
||||
{
|
||||
title: 'CORS Error',
|
||||
content: <CorsErrorSection />
|
||||
},
|
||||
{
|
||||
title: 'Resolve "Cannot find module X" Errors',
|
||||
content: <ModuleXErrorSection />
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## Development Notes
|
||||
|
||||
### Changing Medusa Backend URL
|
||||
|
||||
By default, the Medusa backend runs at `http://localhost:9000`. This value is defined in your Next.js starter template under the environment variable `NEXT_PUBLIC_MEDUSA_BACKEND_URL`.
|
||||
|
||||
If you need to change the URL of your Medusa backend because you changed the backend's default port or because you deployed your backend, change the value of `NEXT_PUBLIC_MEDUSA_BACKEND_URL` (typically in `.env.local`) to your backend URL. For example:
|
||||
|
||||
```bash
|
||||
NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9001
|
||||
```
|
||||
|
||||
### Toggle Search Engine Feature
|
||||
|
||||
The Next.js Starter Template 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 backend. 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 backend. If not, [follow this guide to install it](../plugins/search/meilisearch.md).
|
||||
|
||||
In your Next.js Starter Template, 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 backend. You’ll be able to search through available products by clicking the search icon in the navigation bar.
|
||||
|
||||
:::note
|
||||
|
||||
To make sure the Next.js Starter Template properly displays the products in the search result, include in the `displayedAttributes` setting of the MeiliSearch plugin on the Medusa backend at least the fields `title`, `handle`, `description`, and `thumbnail`.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
|
||||
### 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 backend. You can do it by [following this guide](../plugins/search/algolia.md).
|
||||
|
||||
In your Next.js Starter Template, 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 backend. You’ll be able to search through available products by clicking the search icon in the navigation bar.
|
||||
|
||||
|
||||
|
||||
### Stripe Payment Integration
|
||||
|
||||
Stripe integration is supported by default. Make sure you have Stripe installed and enabled on your Medusa backend first. You can [follow this guide to learn how to install it](../plugins/payment/stripe.mdx).
|
||||
|
||||
Then, in your Next.js Starter Template, 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 backend you should be able to pay with Stripe on checkout.
|
||||
|
||||
|
||||
|
||||
### PayPal Payment Integration
|
||||
|
||||
PayPal integration is supported by default. Make sure you have PayPal installed and enabled on your Medusa backend first. You can [follow this guide to learn how to install it](../plugins/payment/paypal.md).
|
||||
|
||||
Then, in your Next.js Starter Template, 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 backend you should be able to pay with PayPal on checkout.
|
||||
|
||||
|
||||
|
||||
### Customization
|
||||
|
||||
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 `src/modules` directory.
|
||||
|
||||
To customize the styles of the storefront, you can customize the `src/styles` directory.
|
||||
|
||||
### Change Port
|
||||
|
||||
By default, the Next.js Starter Template runs on port `8000`.
|
||||
|
||||
To change the port, change the `develop` command in `package.json` to the following:
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
//other scripts
|
||||
"dev": "next dev -p <PORT>"
|
||||
}
|
||||
```
|
||||
|
||||
Make sure to replace `<PORT>` with the port number you want the storefront to run on. For example, `3000`.
|
||||
|
||||
Then, on your backend, update the environment variable `STORE_CORS` to the URL with the new port:
|
||||
|
||||
```bash
|
||||
STORE_CORS=http://localhost:<PORT>
|
||||
```
|
||||
|
||||
### Development Resources
|
||||
|
||||
You can learn more about development with Next.js through [their documentation](https://nextjs.org/docs/getting-started).
|
||||
|
||||
---
|
||||
|
||||
## Storefront Features
|
||||
|
||||
- View all products and manage your cart.
|
||||
|
||||
|
||||
|
||||
- Customer authentication and profiles.
|
||||
|
||||
|
||||
|
||||
- Full checkout workflow.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Storefront API reference](https://docs.medusajs.com/api/store)
|
||||
- [Install Medusa Admin](../admin/quickstart.mdx).
|
||||
- [Install Stripe as a payment processor](../plugins/payment/stripe.mdx#add-to-nextjs-storefront)
|
||||
Reference in New Issue
Block a user