From 6566bc1cf6183bc57326be1b21953639fec9504e Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 27 Jun 2022 16:22:46 +0300 Subject: [PATCH] docs: improved create-medusa-app doc (#1737) --- docs/content/admin/quickstart.md | 2 +- docs/content/how-to/create-medusa-app.md | 121 ------------------ .../how-to/deploying-admin-on-netlify.md | 2 +- .../how-to/deploying-gatsby-on-netlify.md | 2 +- .../how-to/deploying-on-digital-ocean.md | 2 +- docs/content/how-to/deploying-on-qovery.md | 2 +- docs/content/usage/create-medusa-app.mdx | 121 ++++++++++++++++++ www/docs/sidebars.js | 2 +- 8 files changed, 127 insertions(+), 127 deletions(-) delete mode 100644 docs/content/how-to/create-medusa-app.md create mode 100644 docs/content/usage/create-medusa-app.mdx diff --git a/docs/content/admin/quickstart.md b/docs/content/admin/quickstart.md index eba14beb8b..dd3927331d 100644 --- a/docs/content/admin/quickstart.md +++ b/docs/content/admin/quickstart.md @@ -154,4 +154,4 @@ In the Medusa admin, you can manage your store’s overall settings. These inclu ## What’s Next 🚀 - Install the [Next.js](../starters/nextjs-medusa-starter.md) or [Gatsby](../starters/gatsby-medusa-starter.md) storefront starters. -- [Learn how you can use `create-medusa-app` to install all of Medusa’s 3 components.](../how-to/create-medusa-app.md) +- [Learn how you can use `create-medusa-app` to install all of Medusa’s 3 components.](../usage/create-medusa-app.mdx) diff --git a/docs/content/how-to/create-medusa-app.md b/docs/content/how-to/create-medusa-app.md deleted file mode 100644 index bd4a208aca..0000000000 --- a/docs/content/how-to/create-medusa-app.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -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 npx: - -```bash -npx create-medusa-app -``` - -Or Yarn: - -```bash -yarn 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, 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](../advanced/backend/payment/overview.md) - -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). diff --git a/docs/content/how-to/deploying-admin-on-netlify.md b/docs/content/how-to/deploying-admin-on-netlify.md index c956b08c65..bcb78f39fb 100644 --- a/docs/content/how-to/deploying-admin-on-netlify.md +++ b/docs/content/how-to/deploying-admin-on-netlify.md @@ -8,7 +8,7 @@ This is a guide for deploying Medusa Admin on Netlify. Netlify is a platform tha :::note -At this point, you should have a running instance of Medusa Admin. If not, check out [these steps](https://github.com/medusajs/admin#-setting-up-admin) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough. +At this point, you should have a running instance of Medusa Admin. If not, check out [these steps](https://github.com/medusajs/admin#-setting-up-admin) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](../usage/create-medusa-app.mdx) for a small walkthrough. ::: diff --git a/docs/content/how-to/deploying-gatsby-on-netlify.md b/docs/content/how-to/deploying-gatsby-on-netlify.md index fbc8cbac86..76e8ea06e5 100644 --- a/docs/content/how-to/deploying-gatsby-on-netlify.md +++ b/docs/content/how-to/deploying-gatsby-on-netlify.md @@ -6,7 +6,7 @@ title: "Deploying your Gatsby storefront on Netlify" This is a guide for deploying our [Gatsby storefront starter](https://github.com/medusajs/gatsby-starter-medusa) on Netlify. Netlify is a platform that offers hosting and backend services for applications and static websites. The steps in this guide will work for most Gatsby projects. -> At this point, you should have a local Gatsby storefront project running. If not, check out [our starter](https://github.com/medusajs/gatsby-starter-medusa) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough. +> At this point, you should have a local Gatsby storefront project running. If not, check out [our starter](https://github.com/medusajs/gatsby-starter-medusa) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](../usage/create-medusa-app.mdx) for a small walkthrough. ### 1. Install the Netlify CLI diff --git a/docs/content/how-to/deploying-on-digital-ocean.md b/docs/content/how-to/deploying-on-digital-ocean.md index ecfb8a120e..0957e60af0 100644 --- a/docs/content/how-to/deploying-on-digital-ocean.md +++ b/docs/content/how-to/deploying-on-digital-ocean.md @@ -4,7 +4,7 @@ This is a guide for deploying a Medusa project on DigitalOcean App Platform. :::note -It is assumed, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough. +It is assumed, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](../usage/create-medusa-app.mdx) for a small walkthrough. ::: diff --git a/docs/content/how-to/deploying-on-qovery.md b/docs/content/how-to/deploying-on-qovery.md index 811691a983..59f18803cb 100644 --- a/docs/content/how-to/deploying-on-qovery.md +++ b/docs/content/how-to/deploying-on-qovery.md @@ -4,7 +4,7 @@ This is a guide for deploying a Medusa project to Qovery. Qovery is a Continuous :::note -We assume, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough. +We assume, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](../usage/create-medusa-app.mdx) for a small walkthrough. ::: diff --git a/docs/content/usage/create-medusa-app.mdx b/docs/content/usage/create-medusa-app.mdx new file mode 100644 index 0000000000..fc549d2c81 --- /dev/null +++ b/docs/content/usage/create-medusa-app.mdx @@ -0,0 +1,121 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Use create-medusa-app + +In this document, you’ll learn how to use `create-medusa-app` to create a Medusa project with the 3 main components of Medusa. + +## Overview + +As explained in the [Introduction guide](../introduction.md), Medusa is composed of 3 different components: the headless server, the storefront, and the admin dashboard. + +Medusa provides the necessary tools and resources to set up the 3 components separately. This ensures that developers have full freedom to choose their tech stack, as they can choose any framework for the storefront and admin dashboard. + +However, if you’re interested in using Medusa’s starters for the 3 components, you can easily make use of the `create-medusa-app` command instead of creating each separately. + +When you run the `create-medusa-app` command, you’ll install a Medusa server, a Medusa admin, and optionally a storefront at the same time. + +## How to Create a Medusa Project + +In your terminal, run the following command: + + + + + ```bash + npx create-medusa-app + ``` + + + + + ```bash + yarn create medusa-app + ``` + + + + +### Project Directory Name + +You’ll then be asked to enter the name of the directory you want the project to be installed in. You can either leave the default value `my-medusa-store` or enter a new name. + +### Choose Medusa Starter + +Next, you’ll be asked to choose the Medusa starter used to install the Medusa server. You can either pick the default Medusa starter, the Contentful starter or enter a starter URL by choosing `Other`: + +```bash +? Which Medusa starter would you like to install? … +❯ medusa-starter-default + medusa-starter-contentful + Other +``` + +The server will be installed under the `backend` directory under the project directory. An SQLite database will be created inside that directory as well with demo data seeded into it. + +:::tip + +You can learn more about the Contentful starter in the [Contentful Integration documentation](../add-plugins/contentful.md). + +::: + +### Choose Storefront Starter + +After choosing the Medusa starter, you’ll be asked to choose the storefront starter. You can choose one of the starters in the list included or choose `None` to skip installing a storefront: + +```bash +? Which storefront starter would you like to install? +❯ Gatsby Starter +Next.js Starter +medusa.express (Next.js) +medusa.express (Gatsby) +Gatsby Starter (Simple) +None +``` + +If you choose an option other than `None`, a storefront will be installed under the `storefront` directory. + +:::tip + +Learn more about the [Next.js](../starters/nextjs-medusa-starter.md) and [Gatsby](../starters/gatsby-medusa-starter.md) starter storefronts. + +::: + +### Dependency Installation + +After choosing the above starters, the installation of each component will begin along with its dependencies. Once the installation is done, you’ll see instructions related to how to start each component. + +```bash +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 +``` + +The commands will differ based on your choices in previous prompts. + +## Project Directory Structure + +Inside the root project directory which was specified at the beginning of the installation process you’ll find the following directory structure: + +```bash +/my-medusa-store + /storefront // Medusa storefront starter + /backend // Medusa starter as a backend option + /admin // Medusa admin panel +``` + +## What’s Next 🚀 + +- Learn how to [deploy the Medusa server on Heroku](../how-to/deploying-on-heroku.mdx). +- Learn how to [deploy the Medusa admin on Netlify](../how-to/deploying-admin-on-netlify.md). +- Learn how to [deploy the Gatsby storefront on Netlify](../how-to/deploying-gatsby-on-netlify.md). \ No newline at end of file diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index 4d440e9297..5e10273670 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -68,7 +68,7 @@ module.exports = { }, { type: "doc", - id: "how-to/create-medusa-app", + id: "usage/create-medusa-app", }, { type: "category",