Merge branch 'master' into develop
This commit is contained in:
olivermrbl
@@ -297,7 +297,7 @@ You don’t have to create a template for every type in the reference. You can s
|
||||
```
|
||||
</details>
|
||||
|
||||
### Order Cancelled
|
||||
### Order Canceled
|
||||
|
||||
**Key in plugin options:** `order_canceled_template`
|
||||
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
# Migrations
|
||||
|
||||
In this document, you’ll learn about what Migrations are, their purpose, how you can run them, and how you can create your own Migrations.
|
||||
|
||||
:::note
|
||||
|
||||
Medusa’s Migrations do not work with SQLite databases. They are intended to be used with PostgreSQL databases, which is the recommended Database for your Medusa production server.
|
||||
|
||||
:::
|
||||
|
||||
## Overview
|
||||
|
||||
Migrations are scripts that are used to make additions or changes to your database schema. In Medusa, they are essential for both when you first install your server and for subsequent server upgrades later on.
|
||||
|
||||
When you first create your Medusa server, the database schema used must have all the tables necessary for the server to run.
|
||||
|
||||
When a new Medusa version introduces changes to the database schema, you'll have to run migrations to apply them to your own database.
|
||||
|
||||
:::tip
|
||||
|
||||
Migrations are used to apply changes to the database schema. However, there are some version updates of Medusa that require updating the data in your database to fit the new schema. Those are specific to each version and you should check out the version under Upgrade Guides for details on the steps.
|
||||
|
||||
:::
|
||||
|
||||
## How to Run Migrations
|
||||
|
||||
Migrations in Medusa can be done in one of two ways:
|
||||
|
||||
### Migrate Command
|
||||
|
||||
Using the Medusa CLI tool, you can run migrations with the following command:
|
||||
|
||||
```bash
|
||||
medusa migrations run
|
||||
```
|
||||
|
||||
This will check for any migrations that contain changes to your database schema that aren't applied yet and run them on your server.
|
||||
|
||||
### Seed Command
|
||||
|
||||
Seeding is the process of filling your database with data that is either essential or for testing and demo purposes. In Medusa, the `seed` command will run the migrations to your database if necessary before it seeds your database with dummy data.
|
||||
|
||||
You can use the following command to seed your database:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run seed
|
||||
```
|
||||
|
||||
This will use the underlying `seed` command provided by Medusa's CLI to seed your database with data from the file `data/seed.json` on your Medusa server.
|
||||
|
||||
## How to Create Migrations
|
||||
|
||||
In this section, you’ll learn how to create your own migrations using [Typeorm](https://typeorm.io). This will allow you to modify Medusa’s predefined tables or create your own tables.
|
||||
|
||||
### Create Migration
|
||||
|
||||
To create a migration that makes changes to your Medusa schema, run the following command:
|
||||
|
||||
```bash
|
||||
npx typeorm migration:create -n src/path/to/UserChanged
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
The migration file should be inside the src directory to make sure it is built when the build command is run next.
|
||||
|
||||
:::
|
||||
|
||||
This will create the migration file in the path you specify. You can use this without the need to install Typeorm's CLI tool. You can then go ahead and make changes to it as necessary.
|
||||
|
||||
:::tip
|
||||
|
||||
You can learn more about writing migrations in [Typeorm’s Documentation](https://typeorm.io/migrations).
|
||||
|
||||
:::
|
||||
|
||||
### Build Files
|
||||
|
||||
Before you can run the migrations you need to run the build command to transpile the TypeScript files to JavaScript files:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Run Migration
|
||||
|
||||
The last step is to run the migration with the command detailed earlier
|
||||
|
||||
```bash
|
||||
medusa migrations run
|
||||
```
|
||||
|
||||
If you check your database now you should see that the change defined by the migration has been applied successfully.
|
||||
|
||||
## What’s Next 🚀
|
||||
|
||||
- Learn more about [setting up your development server](../../tutorial/0-set-up-your-development-environment.md).
|
||||
@@ -6,7 +6,7 @@ In this document, you’ll learn how to add a Payment Provider to your Medusa se
|
||||
|
||||
A Payment Provider is the payment method used to authorize, capture, and refund payment, among other actions. An example of a Payment Provider is Stripe.
|
||||
|
||||
By default, Medusa has a [manual payment provider](https://github.com/medusajs/medusa/tree/2e6622ec5d0ae19d1782e583e099000f0a93b051/packages/medusa-fulfillment-manual) that has minimal implementation. It can be synonymous with a Cash on Delivery payment method. It allows store operators to manage the payment themselves but still keep track of its different stages on Medusa.
|
||||
By default, Medusa has a [manual payment provider](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-manual) that has minimal implementation. It can be synonymous with a Cash on Delivery payment method. It allows store operators to manage the payment themselves but still keep track of its different stages on Medusa.
|
||||
|
||||
Adding a Payment Provider is as simple as creating a [service](../services/create-service.md) file in `src/services`. A Payment Provider is essentially a service that extends `PaymentService` from `medusa-interfaces`.
|
||||
|
||||
@@ -42,9 +42,9 @@ These methods are used at different points in the Checkout flow as well as when
|
||||
|
||||
|
||||
|
||||
## Create a Fulfillment Provider
|
||||
## Create a Payment Provider
|
||||
|
||||
The first step to create a fulfillment provider is to create a file in `src/services` with the following content:
|
||||
The first step to create a payment provider is to create a file in `src/services` with the following content:
|
||||
|
||||
```jsx
|
||||
import { PaymentService } from "medusa-interfaces"
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# v1.3.1
|
||||
|
||||
Version 1.3.1 of Medusa introduces new features including the addition of Line Item Adjustments and a more advanced Promotions API. The changes do not affect the public APIs and require only running necessary data migrations.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Both the actions required for this update need you to set the following environment variables:
|
||||
|
||||
```bash
|
||||
TYPEORM_CONNECTION=postgres
|
||||
TYPEORM_URL=<DATABASE_URL>
|
||||
TYPEORM_LOGGING=true
|
||||
TYPEORM_ENTITIES=./node_modules/@medusajs/medusa/dist/models/*.js
|
||||
TYPEORM_MIGRATIONS=./node_modules/@medusajs/medusa/dist/migrations/*.js
|
||||
```
|
||||
|
||||
These environment variables are used in the data migration scripts in this upgrade. Make sure to replace `<DATABASE_URL>` with your PostgreSQL database URL.
|
||||
|
||||
## Line Item Adjustments
|
||||
|
||||
This new version of Medusa allows store operators to adjust line items in an order or a swap which provides more customization capabilities.
|
||||
|
||||
It introduces a new model `LineItemAdjustment` which gives more flexibility to adjust the pricing of line items in a cart, order, or swap. A discount can be added, removed, or modified and the price will reflect on the total calculation of the cart, order, or swap.
|
||||
|
||||
This also introduces an optimization to the calculation of totals, as it is no longer necessary to calculate the discounts every time the totals are retrieved.
|
||||
|
||||
### Actions Required
|
||||
|
||||
This new version adds a new data migration script that will go through your list of existing orders and add line item adjustments for each of the line items in the order.
|
||||
|
||||
For that reason, it’s essential to run the data migration script after upgrading your server and before starting your Medusa server:
|
||||
|
||||
```bash
|
||||
node ./node_modules/@medusajs/medusa/dist/scripts/line-item-adjustment-migration.js
|
||||
```
|
||||
|
||||
## Advanced Discount Conditions
|
||||
|
||||
This new version of Medusa holds advanced promotions functionalities to provide store operators with even more customization capabilities when creating discounts. You can now add even more conditions to your discounts to make them specific for a set of products, collections, customer groups, and more.
|
||||
|
||||
This change required creating a new model `DiscountCondition` which belongs to `DiscountRule` and includes a few relationships with other models to make the aforementioned feature possible.
|
||||
|
||||
### Actions Required
|
||||
|
||||
To ensure your old discount rules play well with the new Promotions API and schema, this version includes a migration script that will go through your existing discount rules, create discount conditions for these rules, and move the former direct relationship between discount rules and products to become between discount conditions and products.
|
||||
|
||||
For that reason, it’s essential to run the data migration script after upgrading your server and before starting your Medusa server:
|
||||
|
||||
```bash
|
||||
node ./node_modules/@medusajs/medusa/dist/scripts/discount-rule-migration.js
|
||||
```
|
||||
@@ -55,7 +55,7 @@ For the walkthrough purposes, we assume that the selected starter is `medusa-sta
|
||||
|
||||
### Selecting a Storefront
|
||||
|
||||
After selecting your Medusa starter you will be given the option to install one of our storefront starters. At the moment we have starters for Gatsby and Next.js:
|
||||
After selecting your Medusa starter, you will be given the option to install one of our storefront starters. At the moment, we have starters for Gatsby and Next.js:
|
||||
|
||||
```bash
|
||||
Which storefront starter would you like to install? …
|
||||
@@ -74,7 +74,7 @@ Creating new project from git: https://github.com/medusajs/medusa-starter-defaul
|
||||
Installing packages...
|
||||
```
|
||||
|
||||
Once the installation has been completed you will have a Medusa backend, a demo storefront, and an admin dashboard.
|
||||
Once the installation has been completed, you will have a Medusa backend, a Demo storefront, and an Admin dashboard.
|
||||
|
||||
## What's inside
|
||||
|
||||
@@ -87,7 +87,7 @@ Inside the root folder which was specified at the beginning of the installation
|
||||
/admin // Medusa admin panel
|
||||
```
|
||||
|
||||
`create-medusa-app` prints out the commands that are available to you after installation. When each project is started you can visit your storefront, complete the order, and view the order in Medusa admin.
|
||||
`create-medusa-app` prints out the commands that are available to you after installation. When each project is started, you can visit your storefront, complete the order, and view the order in Medusa admin.
|
||||
|
||||
```bash
|
||||
⠴ Installing packages...
|
||||
@@ -112,10 +112,10 @@ Create initial git commit in my-medusa-store/admin
|
||||
|
||||
## **What's next?**
|
||||
|
||||
To learn more about Medusa to go through our docs to get some inspiration and guidance for the next steps and further development:
|
||||
To learn more about Medusa, go through our docs to get some inspiration and guidance for the next steps and further development:
|
||||
|
||||
- [Find out how to set up a Medusa project with Gatsby and Contentful](https://docs.medusajs.com/how-to/headless-ecommerce-store-with-gatsby-contentful-medusa)
|
||||
- [Move your Medusa setup to the next level with some custom functionality](https://docs.medusajs.com/tutorial/adding-custom-functionality)
|
||||
- [Create your own Medusa plugin](https://docs.medusajs.com/guides/plugins)
|
||||
|
||||
If you have any follow-up questions or want to chat directly with our engineering team we are always happy to meet you at our [Discord](https://discord.gg/DSHySyMu).
|
||||
If you have any follow-up questions or want to chat directly with our engineering team, we are always happy to meet you at our [Discord](https://discord.gg/DSHySyMu).
|
||||
|
||||
@@ -15,7 +15,7 @@ This article assumes you already have the Medusa project created and ready to be
|
||||
|
||||
## Getting started
|
||||
|
||||
In order to get started let's open the terminal and use the following command to create an instance of your storefront:
|
||||
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
|
||||
@@ -31,7 +31,7 @@ Let's jump to these two.
|
||||
|
||||
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
|
||||
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"
|
||||
@@ -39,13 +39,13 @@ const BACKEND_URL = process.env.GATSBY_STORE_URL || "http://localhost:9000" // <
|
||||
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.
|
||||
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)
|
||||
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
|
||||
/*
|
||||
|
||||
@@ -18,7 +18,7 @@ Your Medusa server will include all functionalities related to your store’s ch
|
||||
|
||||
The admin dashboard is accessible by store operators. Store operators can use the admin dashboard to view, create, and modify data such as orders and products.
|
||||
|
||||
Medusa provides a beautiful [admin dashboard](https://demo.medusajs.com) that you can use right off the bat. Our admin dashboard provides a lot of functionalities to manage your store including Order management, product management, user management and more.
|
||||
Medusa provides a beautiful [admin dashboard](https://demo.medusajs.com) that you can use right off the bat. Our admin dashboard provides a lot of functionalities to manage your store including Order management, Product management, User management and more.
|
||||
|
||||
You can also create your own admin dashboard by utilizing the [Admin REST APIs](https://docs.medusajs.com/api/admin/auth).
|
||||
|
||||
|
||||
@@ -39,20 +39,20 @@ You can install Node from the [official website](https://nodejs.org/en/).
|
||||
```
|
||||
|
||||
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.medusajs.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.
|
||||
We have a prebuilt admin dashboard that you can use to configure and manage your store find it here: [Medusa Admin](https://github.com/medusajs/admin)
|
||||
We have a prebuilt Admin dashboard that you can use to configure and manage your store find it here: [Medusa Admin](https://github.com/medusajs/admin)
|
||||
|
||||
## What's next?
|
||||
|
||||
### Set up a storefront for your Medusa project
|
||||
|
||||
We have created two starters for you that can help you lay a foundation for your storefront. The starters work with your new server with minimal configuration simply clone the starters from here:
|
||||
We have created two starters for you that can help you lay a foundation for your storefront. The starters work with your new server with minimal configuration, simply clone the starters from here:
|
||||
|
||||
- [Nextjs Starter](https://github.com/medusajs/nextjs-starter-medusa)
|
||||
- [Gatsby Starter](https://github.com/medusajs/gatsby-starter-medusa)
|
||||
|
||||
:::tip
|
||||
|
||||
Medusa runs on port 9000 by default and the storefront starters are both configured to run on port 8000. If you wish to run your storefront starter on another port you should update your CORS settings in your project's `medusa-config.js`.
|
||||
Medusa runs on port 9000 by default and the storefront starters are both configured to run on port 8000. If you wish to run your storefront starter on another port, you should update your CORS settings in your project's `medusa-config.js`.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
@@ -6,15 +6,15 @@ title: Creating your Medusa server
|
||||
|
||||
## Introduction
|
||||
|
||||
With the required software installed on your computer you are ready to start working on your first Medusa project.
|
||||
With the required software installed on your computer, you are ready to start working on your first Medusa project.
|
||||
|
||||
In this part of the tutorial we will setup the skeleton for a Medusa store and will be making the first requests to your Medusa server.
|
||||
In this part of the tutorial, we will setup the skeleton for a Medusa store and will be making the first requests to your Medusa server.
|
||||
|
||||
Once you have completed this part of the tutorial you will have a powerful backend for digital commerce experiences. The server will be capable of handling orders, ensuring payments are going through, keeping basic product and customer data in sync, etc. You can use one of the frontend starters to quickly hook up your server to a presentation layer ([Gatsby](https://github.com/medusajs/gatsby-starter-medusa) or [Next](https://github.com/medusajs/nextjs-starter-medusa)).
|
||||
Once you have completed this part of the tutorial, you will have a powerful backend for digital commerce experiences. The server will be capable of handling orders, ensuring payments are going through, keeping basic product and customer data in sync, etc. You can use one of the frontend starters to quickly hook up your server to a presentation layer ([Gatsby](https://github.com/medusajs/gatsby-starter-medusa) or [Next](https://github.com/medusajs/nextjs-starter-medusa)).
|
||||
|
||||
## Setup a Medusa project
|
||||
|
||||
With Medusa CLI installed it is very easy to setup a new Medusa project, with the `new` command. In your command line run:
|
||||
With Medusa CLI installed, it is very easy to setup a new Medusa project, with the `new` command. In your command line run:
|
||||
|
||||
```shell
|
||||
medusa new my-medusa-server --seed
|
||||
@@ -28,7 +28,7 @@ The command will do a number of things:
|
||||
- create a database in postgres with the name my-medusa-server
|
||||
- the `--seed` flag indicates that the database should be populated with some test data after the project has been set up
|
||||
|
||||
If you navigate to the root folder of your new project you will see the following files in your directory:
|
||||
If you navigate to the root folder of your new project, you will see the following files in your directory:
|
||||
|
||||
```
|
||||
.
|
||||
@@ -43,11 +43,11 @@ If you navigate to the root folder of your new project you will see the followin
|
||||
└── package.json
|
||||
```
|
||||
|
||||
There is not a lot of files needed to get your Medusa store setup and this is all due to the fact that the main Medusa core (`@medusajs/medusa`) is installed as a dependency in your project giving you all the fundamental needs for a digital commerce experience.
|
||||
There is not a lot of files needed to get your Medusa store setup and this is all due to the fact that the main Medusa core (`@medusajs/medusa`) is installed as a dependency in your project, giving you all the fundamental needs for a digital commerce experience.
|
||||
|
||||
Much of Medusa's power lies in the `medusa-config.js` which is the file that configures your store and orchestrates the plugins that you wish to use together with your store. There are some different types of plugin categories such as payment plugins, notification plugins and fulfillment plugins, but plugins can contain any form of extension that enhances your store.
|
||||
|
||||
For customizations that are more particular to your project you can extend your Medusa server by adding files in the `api` and `services` directories. More about customizing your server will follow in the following parts.
|
||||
For customizations that are more particular to your project, you can extend your Medusa server by adding files in the `api` and `services` directories. More about customizing your server will follow in the following parts.
|
||||
|
||||
## Starting your Medusa server
|
||||
|
||||
@@ -64,7 +64,7 @@ cd my-medusa-server
|
||||
medusa develop
|
||||
```
|
||||
|
||||
If you ran the new command with the `--seed` flag you will already have products available in your store. To view these you can run the following command in your command line:
|
||||
If you ran the new command with the `--seed` flag, you will already have products available in your store. To view these, you can run the following command in your command line:
|
||||
|
||||
```shell
|
||||
curl -X GET localhost:9000/store/products | python -m json.tool
|
||||
@@ -78,19 +78,19 @@ Other options you could take are:
|
||||
|
||||
### Add a frontend to your server
|
||||
|
||||
We have created two starters for you that can help you lay a foundation for your storefront. The starters work with your new server with minimal configuration simply clone the starters from here:
|
||||
We have created two starters for you that can help you lay a foundation for your storefront. The starters work with your new server with minimal configuration, simply clone the starters from here:
|
||||
|
||||
- [Nextjs Starter](https://github.com/medusajs/nextjs-starter-medusa)
|
||||
- [Gatsby Starter](https://github.com/medusajs/gatsby-starter-medusa)
|
||||
|
||||
### Browse the API reference
|
||||
|
||||
In the API reference docs you can find all the available requests that are exposed by your new Medusa server. Interacting with the API is the first step to creating truly unique experiences.
|
||||
In the API reference docs, you can find all the available requests that are exposed by your new Medusa server. Interacting with the API is the first step to creating truly unique experiences.
|
||||
|
||||
### Setup Stripe as a payment provider (Guide coming soon)
|
||||
|
||||
One of the first things you may want to do when building out your store would be to add a payment provider. Your starter project comes with a dummy payment provider that simply fakes payments being processed. In the real world you want a payment provider that can handle credit card information securely and make sure that funds are being transferred to your account. Stripe is one of the most popular payment providers and Medusa has an official plugin that you can easily install in your project.
|
||||
One of the first things you may want to do when building out your store would be to add a payment provider. Your starter project comes with a dummy payment provider that simply fakes payments being processed. In the real world, you want a payment provider that can handle credit card information securely and make sure that funds are being transferred to your account. Stripe is one of the most popular payment providers and Medusa has an official plugin that you can easily install in your project.
|
||||
|
||||
## Summary
|
||||
|
||||
In this part of the tutorial we have setup your first Medusa project using the `medusa new` command. You have now reached a key milestone as you are ready to start building your Medusa store; from here there are no limits to how you can use Medusa as you can customize and extend the functionality of the core. In the next part of the tutorial we will be exploring how you can add custom services and endpoints to fit your exact needs.
|
||||
In this part of the tutorial, we have setup your first Medusa project using the `medusa new` command. You have now reached a key milestone as you are ready to start building your Medusa store; from here there are no limits to how you can use Medusa, as you can customize and extend the functionality of the core. In the next part of the tutorial, we will be exploring how you can add custom services and endpoints to fit your exact needs.
|
||||
|
||||
@@ -23,10 +23,11 @@
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "git+https://github.com/medusajs/medusa-js.git"
|
||||
"url": "https://github.com/medusajs/medusa",
|
||||
"directory": "packages/medusa-js"
|
||||
},
|
||||
"bugs": {
|
||||
"url": "https://github.com/medusajs/medusa-js/issues"
|
||||
"url": "https://github.com/medusajs/medusa/issues"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/jest": "^26.0.19",
|
||||
|
||||
@@ -204,6 +204,23 @@ module.exports = {
|
||||
type: "doc",
|
||||
id: "guides/carts-in-medusa",
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "advanced/backend/migrations",
|
||||
label: "Migrations"
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: 'Upgrade Guides',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
type: "doc",
|
||||
id: "advanced/backend/upgrade-guides/1-3-1",
|
||||
label: "v1.3.1"
|
||||
},
|
||||
]
|
||||
},
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
Reference in New Issue
Block a user