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

Update README.md (#337)

Browse Source 
* Update README.md

* Update README.md

* Update README.md

* Create CONTRIBUTING.md

* Update README.md

* Update README.md

* Update CONTRIBUTING.md

* Update README.md
This commit is contained in:
Sebastian Rindom
2021-08-17 09:05:54 +02:00
committed by GitHub
parent 9467f7ecbd
commit 617e13a56b
2 changed files with 174 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,61 @@
# Contributing
Thank you for considering contributing to Medusa! This document will outline how to submit changes to this repository and which conventions to follow. If you are ever in doubt about anything we encourage you to reach out either by submitting an issue here or reaching out [via Discord](https://discord.gg/xpCwq3Kfn8).
## Prerequisites
- **You're familiar with GitHub Issues and Pull Requests**
- **You've read the [docs](https://docs.medusa-commerce.com).**
- **You've setup a test project with `medusa new`**
## Issues before PRs
1. Before you start working on a change please make sure that there is an issue for what you will be working on. You can either find and [existing issue](https://github.com/medusajs/medusa/issues) or [open a new issue](https://github.com/medusajs/medusa/issues/new) if none exists. Doing this makes sure that others can contribute with thoughts or suggest alternatives, ultimately making sure that we only add changes that make
2. When you are ready to start working on a change you should first [fork the Medusa repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) and [branch out]](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository) from the `develop` branch.
3. Make your changes.
4. [Open a pull request towards the develop branch in the Medusa repo](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). Within a couple of days a Medusa team member will review, comment and eventually approve your PR.
## Workflow
### Branches
All changes should be part of a branch and submitted as a pull request - your branches should be prefixed with one of:
- `fix/` for bug fixes
- `feat/` for features
- `docs/` for documentation changes
### Commits
Strive towards keeping your commits small and isolated - this helps the reviewer understand what is going on and makes it easier to process your requests.
### Pull Requests
Once your changes are ready you must submit your branch as a pull request. Your pull request should be opened against the `develop` branch in the main Medusa repo.
In your PR's description you should follow the structure:
- **What** - what changes are in this PR
- **Why** - why are these changes relevant
- **How** - how have the changes been implemented
- **Testing** - how has the changes been tested or how can the reviewer test the feature
We highly encourage that you do a self-review prior to requesting a review. To do a self review click the review button in the top right corner, go through your code and annotate your changes. This makes it easier for the reviewer to process your PR.
#### Merge Style
All pull requests are squashed and merged.
### Testing
All PRs should include tests for the changes that are included. We have two types of tests that must be written:
- **Unit tests** found under `packages/*/src/services/__tests__` and `packages/*/src/api/routes/*/__tests__`
- **Integration tests** found in `integration-tests/*/__tests__`
### Documentation
- We generally encourage to document your changes through comments in your code.
- If you alter user-facing behaviour you must provide documentation for such changes.
- All methods and endpoints should be documented using [JSDoc](https://jsdoc.app/) and [`swagger-inline`](https://www.npmjs.com/package/swagger-inline)
### Release
The Medusa team will regularly create releases from the develop branch.

183
README.md
View File

@@ -1,89 +1,114 @@
# Medusa
<p align="center">
<a href="https://www.medusa-commerce.com">
<img alt="Medusa" src="https://user-images.githubusercontent.com/7554214/129161578-19b83dc8-fac5-4520-bd48-53cba676edd2.png" width="100" />
</a>
</p>
<h1 align="center">
Medusa
</h1>
<p align="center">
Medusa is an open-source headless commerce engine that enables developers to create amazing digital commerce experiences.
</p>
<p align="center">
<a href="https://github.com/medusajs/medusa/blob/master/LICENSE">
<img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
</a>
<a href="https://circleci.com/gh/medusajs/medusa">
<img src="https://circleci.com/gh/medusajs/medusa.svg?style=shield" alt="Current CircleCI build status." />
</a>
<a href="https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md">
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
</a>
<a href="https://discord.gg/xpCwq3Kfn8">
<img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
</a>
<a href="https://twitter.com/intent/follow?screen_name=medusajs">
<img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
</a>
</p>
Medusa is a headless commerce engine built with Node.js using Express with a Postgresql database.
## Documentation
See [Medusa Commerce API docs](https://docs.medusa-commerce.com/api/store/) for Node.js.
## Get started in less than 5 minutes
You can get a Medusa engine up and running in your local development environment within a couple of minutes. Perform the following steps:
1. Install Medusa, the Medusa CLI, Medusa babel preset and Medusa interfaces
## 🚀 Quickstart
1. **Install Medusa CLI**
```bash
# core medusa
npm install @medusajs/medusa
yarn add @medusajs/medusa
# CLI
npm install -g @medusajs/medusa-cli
yarn add global @medusajs/medusa-cli
# babel preset
npm install babel-preset-medusa-package
yarn add babel-preset-medusa-package
# interfaces
npm install medusa-interfaces
yarn add medusa-interfaces
```
2. Create a file `medusa-config.js` at the root level of your Node.js project and fill in required settings
2. **Create a new Medusa project**
```
// CORS to avoid issues when consuming Medusa from a client
const STORE_CORS = "http://localhost:8000";
// Database URL (here we use a local database called medusa-development)
const DATABASE_URL = "postgres://localhost/medusa-development";
// Medusa uses Redis, so this needs configuration as well
const REDIS_URL = "redis://localhost:6379"
// This is the place to include plugins. See API documentation for a thorough guide on plugins.
const plugins = [];
module.exports = {
projectConfig: {
redis_url: REDIS_URL,
database_url: DATABASE_URL,
database_logging: true,
database_extra:
process.env.NODE_ENV === "production" ||
process.env.NODE_ENV === "staging"
? {
ssl: { rejectUnauthorized: false },
}
: {},
database_type: "postgres",
store_cors: STORE_CORS,
},
plugins,
};
medusa new my-medusa-store --seed
```
3. Create a Medusa user, such that you can perform authenticated calls
```bash
# provide email and password to the command
medusa user -e lebron@james.com -p lebronjames123
```
4. Start your Medusa engine in your local environment
3. **Start your Medusa engine**
```bash
medusa develop
```
5. Open any client or API tool to start using your Medusa engine
4. **Use the API**
```bash
curl localhost:9000/store/products | python -m json.tool
```
Medusa is running at `http://localhost:4000`. You should now investigate our [API docs](https://docs.medusa-commerce.com/api/store/) to start playing around with your new headless commerce engine.
After these four steps and only a couple of minutes, you now have a complete commerce engine running locally. You may now explore [the documentation](https://docs.medusa-commerce.com/api) to learn how to interact with the Medusa API. You may also add [plugins](https://github.com/medusajs/medusa/tree/master/packages) to your Medusa store by specifying them in your `medusa-config.js` file.
After these four steps and only a couple of minutes, you now have a complete commerce engine running locally.
## ⭐️ Features
Medusa comes with a set of building blocks that allow you to create amazing digital commerce experiences, below is a list of some of the features that Medusa come with out of the box:
- **Headless**: Medusa is a highly customizable commerce API which means that you may use any presentation layer such as a website, app, chat bots, etc.
- **Regions** allow you to specify currencies, payment providers, shipping providers, tax rates and more for one or more countries for truly international sales.
- **Orders** come with all the functionality necessary to perform powerful customer service operations with ease.
- **Carts** allow customers to collect products for purchase, add shipping details and complete payments.
- **Products** come with relevant fields for customs, stock keeping and sales. Medusa supports multiple options and unlimited variants.
- **Swaps** allow customers to exchange products after purchase (e.g. for incorrect sizes). Accounting, payment and fulfillment plugins handle all the tedious work for you for automated customer service.
- **Claims** can be created if customers experience problems with one of their products. Plugins make sure to automate sending out replacements, handling refunds and collecting valuable data for analysis.
- **Returns** allow customers to send back products and can be configured to function in a 100% automated flow through accounting and payment plugins.
- **Fulfillment API** makes it easy to integrate with any fulfillment provider by creating fulfillment plugins, check the `/packages` directory for a full list of plugins.
- **Payments API** makes it easy to integrate with any payment provider by creatingn payment plugins, we already support Stripe, Paypal and Klarna.
- **Notification API** allow integrations with email providers, chat bots, Slack channels etc.
- **Customer Login** to give customers a way of managing their data, viewing their orders and saving payment details.
- **Shipping Options & Profiles** enable powerful rules for free shipping limits, multiple fulfillment methods and more.
- **Medusa's Plugin Architecture** makes it intuitive and easy to manage your integrations, switch providers and grow with ease.
- **Customization** is supported for those special use cases that all the other ecommerce platforms can't accommodate.
## 🛒 Setting up a storefront for your Medusa project
Medusa is a headless commerce engine which means that it can be used for any type of digital commerce experience - you may use it as the backend for an app, a voice application, social commerce experiences or a traditional e-commerce website, you may even want to integrate Medusa into your own software to enable commerce functionality. All of these are use cases that Medusa supports - to learn more read the documentation or reach out.
To provide a quick way to get you started with a storefront install one of our traditional e-commerce starters:
- [Gatsby Starter](https://github.com/medusajs/gatsby-starter-medusa)
```
npm install -g gatsby-cli
gatsby new my-medusa-storefront https://github.com/medusajs/gatsby-starter-medusa
```
- [Nextjs Starter](https://github.com/medusajs/nextjs-starter-medusa)
```
npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefront
```
With your starter and your Medusa store running you can open http://localhost:8000 (for Gatsby) or http://localhost:3000 (for Nextjs) in your browser and view the products in your store, build a cart, add shipping details and pay and complete an order.
## ☁️ Linking development to Medusa Cloud
With your project in local development you can link your Medusa instance to Medusa Cloud - this will allow you to manage your store, view orders and test out the amazing functionalities that you are building. Linking your project to Medusa Cloud requires that you have a Medusa Cloud account.
1. **Authenticate your CLI with Medusa Cloud:**
```
medusa login
```
2. **Link project**
```
medusa link --develop
```
You can now navigate to Orders in Medusa Cloud to view the orders in your local Medusa project, just like you would if your store was running in production.
## Database support
In production Medusa requires Postgres and Redis, but SQLite is supported for development and testing purposes. If you plan on using Medusa for a project it is recommended that you install Postgres and Redis on your dev machine.
- [Install PostgreSQL](https://www.postgresql.org/download/)
- [Install Redis](https://redis.io/download)
To use Postgres and Redis you should provide a `database_url` and `redis_url` in your `medusa-config.js`.
## Contribution
Medusa is all about the community. Therefore, we would love for you to help us build the most robust and powerful commerce engine on the market. Whether its fixing bugs, improving our documentation or simply spreading the word, please feel free to join in.
Medusa is all about the community. Therefore, we would love for you to help us build the most robust and powerful commerce engine on the market. Whether its fixing bugs, improving our documentation or simply spreading the word, please feel free to join in. Please check [our contribution guide](https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md) for further details about how to contribute.
## Repository structure
@@ -94,3 +119,21 @@ The Medusa repository is a mono-repository managed using Lerna. Lerna allows us
Licensed under the [MIT License](https://github.com/medusajs/medusa/blob/master/LICENSE)
## Thank you!
<p>
<a href="https://www.medusa-commerce.com">
Website
</a>
|
<a href="https://medusajs.notion.site/medusajs/Medusa-Home-3485f8605d834a07949b17d1a9f7eafd">
Notion Home
</a>
|
<a href="https://twitter.com/intent/follow?screen_name=medusajs">
Twitter
</a>
|
<a href="https://docs.medusa-commerce.com">
Docs
</a>
</p>