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

docs: Improve storefront quickstart documents

Browse Source 
docs: Improve storefront quickstart documents
This commit is contained in:
Shahed Nasser
2022-06-14 10:40:50 +03:00
committed by GitHub
parent a66babe9f1 9c47736f4e
commit 7bfc224ca4
4 changed files with 152 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
docs/content/how-to/setting-up-a-nextjs-storefront-for-your-medusa-project.md
View File

@@ -1,58 +0,0 @@
---
title: Setting up a Next.js storefront for your Medusa project
---
# Setting up a Next.js storefront for your Medusa project
:::note
Medusa is a headless open source commerce platform giving engineers the foundation for building unique and scalable digital commerce projects through our API-first engine.
Being headless, our starters serve as a good foundation for you to get coupled with a frontend in a matter of minutes.
:::
This article assumes you already have the Medusa project created and ready to be linked to your Next.js starter.
## Getting started
In order to get started, let's open the terminal and use the following command to create an instance of your storefront:
```zsh
npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefront
```
Now we have a storefront codebase that is ready to be used with our Medusa server.
Next, we have to complete two steps to make our new shiny storefront to speak with our server: **link storefront to a server** and **update the `STORE_CORS` variable**.
Let's jump to these two.
## Link storefront to a server
For this part, we should navigate to a `client.js` file which you can find in the utils folder.
We don't need to do much in here, but to make sure that our storefront is pointing to the port where the server is running
```js
import Medusa from "@medusajs/medusa-js"
const BACKEND_URL = process.env.GATSBY_STORE_URL || "http://localhost:9000" // <--- That is the line we are looking for
export const createClient = () => new Medusa({ baseUrl: BACKEND_URL })
```
By default, the Medusa server is running at port 9000. So if you didn't change that, we are good to go to our next step.
## Update the `STORE_CORS` variable
Here let's navigate to your Medusa server and open `medusa-config.js`
Let's locate the `STORE_CORS` variable and make sure it's the right port (which is 3000 by default for Next.js projects).
```js
/*
* CORS to avoid issues when consuming Medusa from a client.
* Should be pointing to the port where the storefront is running.
*/
const STORE_CORS = process.env.STORE_CORS || "http://localhost:3000"
```
Now we have a storefront that interacts with our Medusa server and with that we have a sweet and complete e-commerce setup with a Next.js storefront.

112
docs/content/starters/gatsby-medusa-starter.md
View File

@@ -1,47 +1,101 @@
# Quickstart: Gatsby
# Quickstart: Gatsby Storefront
**Create a new Gatsby project using the Medusa starter template**
This document guides you to install and set up the Gatsby Storefront for your Medusa Server.
```bash
gatsby new my-medusa-store https://github.com/medusajs/gatsby-starter-medusa
![Gatsby Storefront Quick Look](https://i.imgur.com/LcAsi8r.gif)
## Prerequisites
This document assumes you already have a Medusa server installed. If you don’t, please follow the [Quickstart guide for the Medusa server](../quickstart/quick-start.md) to learn how to do it.
You should also have the Gatsby CLI installed:
```bash npm2yarn
npm install gatsby-cli -g
```
**Set up environment variables**
Navigate into your projects directory and get your environment variables ready:
## Installation
```shell
1\. Create a new Gatsby project using the [Medusa starter template](https://github.com/medusajs/gatsby-starter-medusa):
```bash
gatsby new my-medusa-storefront https://github.com/medusajs/gatsby-starter-medusa
```
2\. 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.development
```
**Install dependencies**
Use your favourite package manager to install dependencies:
```bash npm2yarn
npm install
```
**Start developing.**
Start up the local server:
3\. Make sure the Medusa server is running, then run the local Gatsby server:
```bash npm2yarn
npm run start
```
Your site is now running at http://localhost:8000!
Your Gatsby storefront is now running at `localhost:8000`!
Edit `src/pages/index.js` to see your site update in real-time!
## Development Notes
**Learn more about Medusa**
### Customization
- [Website](https://www.medusajs.com/)
- [GitHub](https://github.com/medusajs)
- [Documentation](https://docs.medusajs.com/)
To customize the components, pages, and UI of your Gatsby storefront, just edit files under the `src` directory.
**Learn more about Gatsby**
### Data Refresh
- [Documentation](https://www.gatsbyjs.com/docs/?utm_source=starter&utm_medium=readme&utm_campaign=minimal-starter)
- [Tutorials](https://www.gatsbyjs.com/tutorial/?utm_source=starter&utm_medium=readme&utm_campaign=minimal-starter)
- [Guides](https://www.gatsbyjs.com/tutorial/?utm_source=starter&utm_medium=readme&utm_campaign=minimal-starter)
- [API Reference](https://www.gatsbyjs.com/docs/api-reference/?utm_source=starter&utm_medium=readme&utm_campaign=minimal-starter)
- [Plugin Library](https://www.gatsbyjs.com/plugins?utm_source=starter&utm_medium=readme&utm_campaign=minimal-starter)
- [Cheat Sheet](https://www.gatsbyjs.com/docs/cheat-sheet/?utm_source=starter&utm_medium=readme&utm_campaign=minimal-starter)
The Gatsby storefront uses the [gatsby-source-medusa](https://github.com/medusajs/medusa/tree/master/packages/gatsby-source-medusa) plugin to source data from your Medusa server. This data includes products, collections, and regions, and as a result, you can query this data in the storefront starter using GraphQL queries. You can also explore the data in your store on `localhost:8000/___graphql`.
Because of this, you must rebuild the site every time you update any of this data for it to be reflected in your storefront. We will soon be releasing a new version of the plugin which adds incremental builds, which will improve build times.
### Change Port
By default, the Gatsby storefront runs on port `8000`.
To change the port, change the `develop` command in `package.json` to the following:
```json
"scripts": {
//other scripts
"develop": "gatsby develop --port=<PORT>"
}
```
Make sure to replace `<PORT>` with the port number you want the storefront to run on. For example, `3000`.
Then, on your server, update the environment variable `STORE_CORS` to the URL with the new port:
```bash
STORE_CORS=http://localhost:<PORT>
```
### Development Resources
If you’re not familiar with Gatsby, you can learn more about it through the following resources:
- [Documentation](https://www.gatsbyjs.com/docs)
- [Plugin Library](https://www.gatsbyjs.com/plugins/)
- [Cheat Sheet](https://www.gatsbyjs.com/docs/cheat-sheet/)
## Storefront Features
The Gatsby storefront comes with a lot of features out of the box including:
- View all products and manage your cart.
![Products Page](https://i.imgur.com/P0Mpvxh.png)
- Customer authentication.
![Sign In Page](https://i.imgur.com/0sVcZeS.png)
- Full checkout workflow.
![One-Page Checkout](https://i.imgur.com/5wSs3yZ.png)
- Request swaps and returns using a customer’s order ID and Email.
![Request Return for Order](https://i.imgur.com/mAChp3f.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 [deploy the Gatsby storefront on Netlify](../how-to/deploying-gatsby-on-netlify.md).
- Learn how to add [Stripe as a payment provider](../add-plugins/stripe.md#gatsby-storefront).

89
docs/content/starters/nextjs-medusa-starter.md
View File

@@ -1,42 +1,87 @@
# Quickstart: Next.js
# Quickstart: Next.js Storefront
**Create a new Next.js project using the Medusa starter template**
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)
## Prerequisites
This document assumes you already have a Medusa server installed. If you don’t, please follow the [Quickstart guide for the Medusa server](../quickstart/quick-start.md) to learn how to do it.
## 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
```
**Set up environment variables**
Navigate into your projects directory and get your environment variables ready:
2\. Change to the newly created directory `my-medusa-storefront` and rename the template environment variable file to use environment variables in development:
```shell
```bash
mv .env.template .env.local
```
**Install dependencies**
Use your favourite package manager to install dependencies:
```bash npm2yarn
npm install
```
**Start developing.**
Start up the local server:
3\. Make sure the Medusa server is running, then run the local Next.js server:
```bash npm2yarn
npm run dev
```
Your site is now running at http://localhost:8000!
Your Next.js storefront is now running at `localhost:8000`!
Edit `src/pages/index.js` to see your site update in real-time!
## Development Notes
**Learn more about Medusa**
### Customization
- [Website](https://www.medusajs.com/)
- [GitHub](https://github.com/medusajs)
- [Documentation](https://docs.medusajs.com/)
To customize the pages of the storefront, you can customize the files under the `pages` directory.
**Learn more about Next.js**
To customize the components used in the storefront, you can customize the files under the `components` directory.
- [Documentation](https://nextjs.org/docs)
To customize the styles of the storefront, you can customize the `styles` directory.
### Change Port
By default, the Next.js storefront 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 server, 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 products and manage your cart.
![Product Page](https://i.imgur.com/wCeWJio.png)
- Full checkout workflow.
![Shipping Details on Checkout](https://i.imgur.com/7la2KhW.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).

9
www/docs/sidebars.js
View File

@@ -44,17 +44,12 @@ module.exports = {
{
type: "doc",
id: "starters/gatsby-medusa-starter",
label: "Quickstart: Gatsby",
label: "Gatsby Storefront Quickstart",
},
{
type: "doc",
id: "starters/nextjs-medusa-starter",
label: "Quickstart: Next.js",
},
{
type: "doc",
id: "how-to/setting-up-a-nextjs-storefront-for-your-medusa-project",
label: "Set Up a Next.js Storefront for your Medusa Project"
label: "Next.js Storefront Quickstart",
},
],
},