chore(deps): bump tmpl from 1.0.4 to 1.0.5 in /packages/medusa (#411)
* docs: create-medusa-app article (#401) * fix: temporarily comment out cloud related docs (#387) * Fix typo in registerOptin section (#407) * docs: Carts in Medusa (#406) * chore(deps): bump tmpl from 1.0.4 to 1.0.5 in /packages/medusa Bumps [tmpl](https://github.com/daaku/nodejs-tmpl) from 1.0.4 to 1.0.5. - [Release notes](https://github.com/daaku/nodejs-tmpl/releases) - [Commits](https://github.com/daaku/nodejs-tmpl/commits/v1.0.5) --- updated-dependencies: - dependency-name: tmpl dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Vadim Smirnov <62517920+FuzzyReason@users.noreply.github.com> Co-authored-by: ps-89 <91064940+ps-89@users.noreply.github.com> Co-authored-by: Sebastian Rindom <skrindom@gmail.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
This commit is contained in:
dependabot[bot]
GitHub
163
docs/content/guides/carts-in-medusa.md
Normal file
163
docs/content/guides/carts-in-medusa.md
Normal file
@@ -0,0 +1,163 @@
|
||||
---
|
||||
title: Carts in Medusa
|
||||
---
|
||||
|
||||
# Carts in Medusa
|
||||
|
||||
In Medusa a Cart serves the purpose of collecting the information needed to create an Order, including what products to purchase, what address to send the products to and which payment method the purchase will be processed by.
|
||||
|
||||
To create a cart using the `@medusajs/medusa-js` SDK you can use:
|
||||
|
||||
```javascript
|
||||
const client = new Medusa({ baseUrl: "http://localhost:9000" })
|
||||
const { cart } = await client.carts.create()
|
||||
```
|
||||
|
||||
A Cart will always belong to a Region and you may provide a `region_id` upon Cart creation. If no `region_id` is specified Medusa will assign the Cart to a random Region. Regions specify information about how the Cart should be taxed, what currency the Cart should be paid with and what payment and fulfillment options will be available at checkout. Below are some of the properties that can be found on the Cart response. For a full example of a Cart response [check our fixtures](https://github.com/medusajs/medusa/blob/docs/api/docs/api/fixtures/store/GetCartsCart.json).
|
||||
|
||||
```json
|
||||
"cart": {
|
||||
"id": "cart_01FEWZSRFWT8QWMHJ7ZCPRP3BZ",
|
||||
"email": null,
|
||||
"billing_address": null,
|
||||
"shipping_address": null,
|
||||
"items": [ ... ],
|
||||
"region": {
|
||||
"id": "reg_01FEWZSRD7HVHBSQRC4KYMG5XM",
|
||||
"name": "United States",
|
||||
"currency_code": "usd",
|
||||
"tax_rate": "0",
|
||||
...
|
||||
},
|
||||
"discounts": [],
|
||||
"gift_cards": [],
|
||||
"customer_id": null,
|
||||
"payment_sessions": [],
|
||||
"payment": null,
|
||||
"shipping_methods": [],
|
||||
"type": "default",
|
||||
"metadata": null,
|
||||
"shipping_total": 0,
|
||||
"discount_total": 0,
|
||||
"tax_total": 0,
|
||||
"gift_card_total": 0,
|
||||
"subtotal": 1000,
|
||||
"total": 1000,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## Adding products to the Cart
|
||||
|
||||
Customers can add products to the Cart in order to start gathering the items that will eventually be purchased. In Medusa adding a product to a Cart will result in a _Line Item_ being generated. To add a product using the SDK use:
|
||||
|
||||
```javascript
|
||||
const { cart } = await client.carts.lineItems.create(cartId, {
|
||||
variant_id: "[id-of-variant-to-add]",
|
||||
quantity: 1,
|
||||
})
|
||||
```
|
||||
|
||||
The resulting response will look something like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"cart": {
|
||||
"id": "cart_01FEWZSRFWT8QWMHJ7ZCPRP3BZ",
|
||||
"items": [
|
||||
{
|
||||
"id": "item_01FEWZSRMBAN85SKPCRMM30N6W",
|
||||
"cart_id": "cart_01FEWZSRFWT8QWMHJ7ZCPRP3BZ",
|
||||
"title": "Basic Tee",
|
||||
"description": "Small",
|
||||
"thumbnail": null,
|
||||
"is_giftcard": false,
|
||||
"should_merge": true,
|
||||
"allow_discounts": true,
|
||||
"has_shipping": false,
|
||||
"unit_price": 1000,
|
||||
"variant": {
|
||||
"id": "variant_01FEWZSRDNWABVFZTZ21JWKHRG",
|
||||
"title": "Small",
|
||||
"product_id": "prod_01FEWZSRDHDDSHQV6ATG6MS2MF",
|
||||
"sku": null,
|
||||
"barcode": null,
|
||||
"ean": null,
|
||||
"upc": null,
|
||||
"allow_backorder": false,
|
||||
"hs_code": null,
|
||||
"origin_country": null,
|
||||
"mid_code": null,
|
||||
"material": null,
|
||||
"weight": null,
|
||||
"length": null,
|
||||
"height": null,
|
||||
"width": null,
|
||||
"metadata": null,
|
||||
...
|
||||
},
|
||||
"quantity": 1,
|
||||
"metadata": {},
|
||||
...
|
||||
}
|
||||
],
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The properties stored on a Line Item are useful for explaining and displaying the contents of the Cart. For example, Line Items can have a thumbnail assigned which can be used to display a pack shot of the product that is being purchased, a title to show name the products in the cart and a description to give further details about the product. By default the Line Item will be generated with properties inherited from the Product that is being added to the Cart, but the behaviour can be customized for other purposes as well.
|
||||
|
||||
## Adding Customer information to a Cart
|
||||
|
||||
After adding products to the Cart, you should gather information about where to send the products, this is done using the `update` method in the SDK.
|
||||
|
||||
```javascript
|
||||
const { cart } = await client.carts.update(cartId, {
|
||||
email: "jane.doe@mail.com",
|
||||
shipping_address: {
|
||||
first_name: "Jane",
|
||||
last_name: "Doe",
|
||||
address_1: "4242 Hollywood Dr",
|
||||
postal_code: "12345",
|
||||
country_code: "us",
|
||||
city: "Los Angeles",
|
||||
region: "CA",
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Note that the country code in the shipping address must be the country code for one of the countries in a Region - otherwise this method will fail.
|
||||
|
||||
## Initializing Payment Sessions
|
||||
|
||||
In Medusa payments are handled through the long lived entities called _Payment Sessions_. Payment Sessions cary provider specific data that can later be used to authorize the payments, which is the step required before an order can be created. The SDK provides a `createPaymentSessions` method that can be used to initialize the payment sessions with the Payment Providers available in the Region.
|
||||
|
||||
```javascript
|
||||
const { cart } = await client.carts.createPaymentSessions(cartId)
|
||||
```
|
||||
|
||||
You can read more about Payment Sessions in our [guide to checkouts](https://docs.medusa-commerce.com/guides/checkouts).
|
||||
|
||||
## Changing the Cart region
|
||||
|
||||
To update the Region that the cart belongs to you should also use the `update` method from the SDK.
|
||||
|
||||
```javascript
|
||||
const { cart } = await client.carts.update(cartId, {
|
||||
region_id: "[id-of-region-to-switch-to]",
|
||||
})
|
||||
```
|
||||
|
||||
When changing the Cart region you should be aware of a couple of things:
|
||||
|
||||
- If switching to a Region with a different currency the line item prices and cart totals will change
|
||||
- If switching to a Region with a different tax rate prices and totals will change
|
||||
- If switching to a Region serving only one country the `shipping_address.country_code` will automatically be set to that country
|
||||
- If the Cart already has initialized payment sessions all of these will be canceled and a new call to `createPaymentSessions` will have to be made
|
||||
|
||||
## What's next?
|
||||
|
||||
Carts are at the core of the shopping process in Medusa and provide all the necessary functionality to gather products for purchase. If you want to read a more detailed guide about how to complete checkouts please go to our [Checkout Guide](https://docs.medusa-commerce.com/guides/checkout).
|
||||
|
||||
If you have questions or issues feel free to reach out via our [Discord server](https://discord.gg/xpCwq3Kfn8) for direct access to the Medusa engineering team.
|
||||
117
docs/content/how-to/create-medusa-app.md
Normal file
117
docs/content/how-to/create-medusa-app.md
Normal file
@@ -0,0 +1,117 @@
|
||||
---
|
||||
title: Using create-medusa-app
|
||||
---
|
||||
# Using create-medusa-app
|
||||
With the new `create-medusa-app` tool you will get your [Medusa](https://github.com/medusajs/medusa) development environment ready within a couple of minutes. After completion, you will have a Medusa backend, a Gatsby or Next.js storefront, and an admin dashboard up and running on your local machine.
|
||||
|
||||
Starting a new e-commerce project just got easier, now with one command.
|
||||
|
||||
## Getting started with `create-medusa-app`
|
||||
|
||||
Use `create-medusa-app` with your preferred package manager:
|
||||
|
||||
```bash
|
||||
yarn create medusa-app
|
||||
|
||||
npx create-medusa-app
|
||||
```
|
||||
|
||||
Behind the scenes, `create-medusa-app` is populating your database with some initial set of mock data, which helps to interact with Medusa setup intuitively straight away.
|
||||
|
||||
Right after hitting one of those commands, the multistep installation process will be initiated, so the starter can be shaped right for the specific needs.
|
||||
|
||||
### Destination folder
|
||||
|
||||
Enter the path to the directory that will become the root of your Medusa project:
|
||||
|
||||
```bash
|
||||
? Where should your project be installed? › my-medusa-store
|
||||
```
|
||||
|
||||
### Pick the starter you prefer
|
||||
|
||||
```bash
|
||||
? Which Medusa starter would you like to install? …
|
||||
❯ medusa-starter-default
|
||||
medusa-starter-contentful
|
||||
Other
|
||||
```
|
||||
|
||||
You will be presented with three options:
|
||||
|
||||
- `medusa-starter-default` is the most lightweight version of a Medusa project
|
||||
- `medusa-starter-contentful` almost like the default starter, but with `medusa-plugin-contentful` preinstalled
|
||||
- `Other` if you have a different starter that you would wish to install from `Other` will give you the option of providing a URL to that starter. An additional question will be asked if you choose this option:
|
||||
|
||||
```bash
|
||||
Where is the starter located? (URL or path) › https://github.com/somecoolusername/my-custom-medusa-starter
|
||||
```
|
||||
|
||||
For the walkthrough purposes, we assume that the selected starter is `medusa-starter-default` and proceed to the next step.
|
||||
|
||||
### 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:
|
||||
|
||||
```bash
|
||||
Which storefront starter would you like to install? …
|
||||
❯ Gatsby Starter
|
||||
Next.js Starter
|
||||
None
|
||||
```
|
||||
|
||||
You may also select `None` if the choice is to craft a custom storefront for your product.
|
||||
|
||||
`create-medusa-app` now has all of the info necessary for the installation to begin.
|
||||
|
||||
```bash
|
||||
Creating new project from git: https://github.com/medusajs/medusa-starter-default.git
|
||||
✔ Created starter directory layout
|
||||
Installing packages...
|
||||
```
|
||||
|
||||
Once the installation has been completed you will have a Medusa backend, a demo storefront, and an admin dashboard.
|
||||
|
||||
## What's inside
|
||||
|
||||
Inside the root folder which was specified at the beginning of the installation process the following structure could be found:
|
||||
|
||||
```bash
|
||||
/my-medusa-store
|
||||
/storefront // Medusa storefront starter
|
||||
/backend // Medusa starter as a backend option
|
||||
/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.
|
||||
|
||||
```bash
|
||||
⠴ Installing packages...
|
||||
✔ Packages installed
|
||||
Initialising git in my-medusa-store/admin
|
||||
Create initial git commit in my-medusa-store/admin
|
||||
|
||||
Your project is ready 🚀. The available commands are:
|
||||
|
||||
Medusa API
|
||||
cd my-medusa-store/backend
|
||||
yarn start
|
||||
|
||||
Admin
|
||||
cd my-medusa-store/admin
|
||||
yarn start
|
||||
|
||||
Storefront
|
||||
cd my-medusa-store/storefront
|
||||
yarn start
|
||||
```
|
||||
|
||||
## **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:
|
||||
|
||||
- [Find out how to set up a Medusa project with Gatsby and Contentful](https://docs.medusa-commerce.com/how-to/headless-ecommerce-store-with-gatsby-contentful-medusa)
|
||||
- [Move your Medusa setup to the next level with some custom functionality](https://docs.medusa-commerce.com/tutorial/adding-custom-functionality)
|
||||
- [Create your own Medusa plugin](https://docs.medusa-commerce.com/how-to/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).
|
||||
@@ -32,6 +32,6 @@ We have created two starters for you that can help you lay a foundation for your
|
||||
- [Nextjs Starter](https://github.com/medusajs/nextjs-starter-medusa)
|
||||
- [Gatsby Starter](https://github.com/medusajs/gatsby-starter-medusa)
|
||||
|
||||
### Link you local development to Medusa Cloud (Coming soon!)
|
||||
<!-- ### Link you local development to Medusa Cloud (Coming soon!)
|
||||
|
||||
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. [Get started here](https://docs.medusa-commerce.com/tutorial/linking-your-local-project-with-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. [Get started here](https://docs.medusa-commerce.com/tutorial/linking-your-local-project-with-medusa-cloud). -->
|
||||
|
||||
@@ -10,7 +10,7 @@ Welcome to Medusa - we are so excited to get you on board!
|
||||
|
||||
This tutorial will walk you through the steps to take to set up your local development environment. You will familiarize yourself with some of the core parts that make Medusa work and learn how to configure your development environment. Furthermore you will be introduced to how the plugin architecture works and how to customize your commerce functionalities with custom logic and endpoints.
|
||||
|
||||
As a final part of the tutorial you will be linking your local project to Medusa Cloud where you can leverage advanced tools that make it easy to develop, test and deploy your Medusa project.
|
||||
<!-- As a final part of the tutorial you will be linking your local project to Medusa Cloud where you can leverage advanced tools that make it easy to develop, test and deploy your Medusa project. -->
|
||||
|
||||
## Background Knowledge and Prerequisites
|
||||
|
||||
@@ -107,11 +107,11 @@ If you don't already have a text editor of choice you should find one you like -
|
||||
|
||||
It is not important which editor you use as long as you feel comfortable working with it.
|
||||
|
||||
## Medusa Cloud account
|
||||
<!-- ## Medusa Cloud account
|
||||
|
||||
As the final step in this part of the tutorial you should create a Medusa Cloud account. Medusa Cloud is the platform that works with Medusa; the platform is where you view and manage your store, but is also a key part of the development process as you will be linking your local project to the platform so that you can manage your store while in development.
|
||||
|
||||
[Sign up for Medusa Cloud](https://app.medusa-commerce.com)
|
||||
[Sign up for Medusa Cloud](https://app.medusa-commerce.com) -->
|
||||
|
||||
## Summary
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@ In the constructor we specify that our `WelcomeService` will depend upon the `ca
|
||||
|
||||
### `registerOptin`
|
||||
|
||||
The `registerOption` function will take to arguments: `cartId` and `optin`, where `cartId` holds the id of the cart that we wish to register optin for and `optin` is a boolean to indicate if the customer has accepted or optin or not. We will save the `optin` preferences in the cart's `metadata` field, so that it can be persisted for the future when we need to evaluate if we should send the welcome or not.
|
||||
The `registerOption` function will take two arguments: `cartId` and `optin`, where `cartId` holds the id of the cart that we wish to register optin for and `optin` is a boolean to indicate if the customer has accepted or optin or not. We will save the `optin` preferences in the cart's `metadata` field, so that it can be persisted for the future when we need to evaluate if we should send the welcome or not.
|
||||
|
||||
```javascript
|
||||
async registerOptin(cartId, optin) {
|
||||
@@ -252,4 +252,4 @@ You have now learned how to add custom functionality to your Medusa server, whic
|
||||
|
||||
You have now been introduced to many of the key parts of Medusa and with your knowledge of customization you can now begin creating some really powerful commerce experiences. If you have an idea for a cool customization go ahead and make it right now! If you are not completely ready yet you can browse the reference docs further.
|
||||
|
||||
In the next part of this tutorial we will look into linking your local project with Medusa Cloud to make develpment smoother while leveraging the powerful management tools that merchants use to manage their Medusa store.
|
||||
<!-- In the next part of this tutorial we will look into linking your local project with Medusa Cloud to make develpment smoother while leveraging the powerful management tools that merchants use to manage their Medusa store. -->
|
||||
|
||||
Reference in New Issue
Block a user