From 825dfa116aa56c6b849d06b4053d360564bb33c9 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 11 Nov 2024 13:20:55 +0300 Subject: [PATCH 1/3] docs: improve getting started chapters --- www/apps/book/app/learn/installation/page.mdx | 118 ++++++++++++++++++ www/apps/book/app/learn/page.mdx | 26 ---- www/apps/book/components/Feedback/index.tsx | 2 +- .../book/components/MDXComponents/index.tsx | 2 + www/apps/book/sidebar.mjs | 19 ++- .../_sections/other/cors-errors.mdx | 10 +- 6 files changed, 139 insertions(+), 38 deletions(-) create mode 100644 www/apps/book/app/learn/installation/page.mdx diff --git a/www/apps/book/app/learn/installation/page.mdx b/www/apps/book/app/learn/installation/page.mdx new file mode 100644 index 0000000000000..afde8da56d4a1 --- /dev/null +++ b/www/apps/book/app/learn/installation/page.mdx @@ -0,0 +1,118 @@ +import { Prerequisites } from "docs-ui" + +export const metadata = { + title: `${pageNumber} Install Medusa`, +} + +# {metadata.title} + +In this documentation, you'll learn how to install and run a Medusa application. + +## Create Medusa Application + + + +To create a Medusa application, use the `create-medusa-app` command: + +```bash +npx create-medusa-app@latest +``` + +When you run the command, you'll be asked for the project's name and whether you want to install the Next.js storefront. + +After answering the prompts, the command installs the Medusa application in a directory with your project name, and prepares a PostgreSQL database that the application connects to. + + + +Since the Medusa server is headless, the storefront is optional to install and you can install it later by following [this guide](../storefront-development/nextjs-starter/page.mdx). If you choose to install it with the Medusa application, the storefront is installed in a separate directory named `{project-name}-storefront`. + + + +### Successful Installation Result + +Once the Medusa application installation finishes successfully, the Medusa application will run at `http://localhost:9000`. + +The Medusa Admin dashboard also runs at `http://localhost:9000/app`. The installation process opens the Medusa Admin dashboard in your default browser to create a user. You can later log in with that user. + +If you also installed the Next.js storefront, it'll be running at `http://localhost:8000`. + +### Troubleshooting Installation Errors + +If you ran into an error during your installation, refer to the following troubleshooting guides for help: + +1. [create-medusa-app troubleshooting guides](!resources!/troubleshooting/create-medusa-app-errors). +2. [CORS errors](!resources!/troubleshooting/cors-errors). +3. [All troubleshooting guides](!resources!/troubleshooting). + +If you can't find your error reported anywhere, please open a [GitHub issue](https://github.com/medusajs/medusa/issues/new/choose). + + + +--- + +## Run Medusa Application in Development + +To run the Medusa application in development, change to your application's directory and run the following command: + +```bash npm2yarn +npm run dev +``` + +This runs your Medusa application at `http://localhost:9000`, and the Medusa Admin dashboard `http://localhost:9000/app`. + + + +For details on starting and configuring the Next.js storefront, refer to [this documentation](../storefront-development/nextjs-starter/page.mdx). + + + +The application will restart if you make any changes to code under the `src` directory, except for admin customizations which are hot reloaded, providing you with a seamless developer experience without having to refresh your browser to see the changes. + +--- + +## Create Medusa Admin User + +Aside from creating an admin user in the admin dashboard, you can create a user with Medusa's CLI tool. + +Run the following command in your Medusa application's directory to create a new admin user: + +```bash +npx medusa user -e admin@medusajs.com -p supersecret +``` + +Replace `admin@medusajs.com` and `supersecret` with the user's email and password respectively. + +You can then use the user's credentials to log into the Medusa Admin application. + +--- + +## Configure Medusa Application + +By default, your Medusa application is equipped with the basic configuration to start your development. + +If you run into issues with configurations, such as CORS configurations, or need to make changes to the default configuration, refer to [this guide on all available configurations](!resources!/medusa-config). + +--- + +## Next Steps + +In the next documentation pages, you'll start customizing your Medusa application, learn about the project's directory structure, and learn about different basic concepts. diff --git a/www/apps/book/app/learn/page.mdx b/www/apps/book/app/learn/page.mdx index 754140e6f6d18..1e33e85f39748 100644 --- a/www/apps/book/app/learn/page.mdx +++ b/www/apps/book/app/learn/page.mdx @@ -1,6 +1,5 @@ import { CheckCircleSolid, BuildingStorefront, BuildingsSolid, ComputerDesktop, FlyingBox } from "@medusajs/icons" import { config } from "@/config" -import { Prerequisites } from "docs-ui" export const metadata = { title: `${pageNumber} Introduction - ${config.titleSuffix}`, @@ -22,31 +21,6 @@ However, unlike other platforms, Medusa is built with customization in mind. You --- -## Get started - - - -Create your first Medusa store by running the following command: - -```bash -npx create-medusa-app@latest -``` - ---- - ## Who should use Medusa Medusa is for businesses with unique requirements that other digital commerce platforms can't easily support. Businesses of any size can use Medusa, from small startups to large enterprises - all it takes is a developer to manage and deploy your project. diff --git a/www/apps/book/components/Feedback/index.tsx b/www/apps/book/components/Feedback/index.tsx index 9a4ca89f131f8..bc7584ea97103 100644 --- a/www/apps/book/components/Feedback/index.tsx +++ b/www/apps/book/components/Feedback/index.tsx @@ -32,7 +32,7 @@ const Feedback = (props: FeedbackProps) => { event="survey" pathName={feedbackPathname} reportLink={reportLink} - question="Was this chapter helpful?" + question={props.question || "Was this chapter helpful?"} {...props} /> ) diff --git a/www/apps/book/components/MDXComponents/index.tsx b/www/apps/book/components/MDXComponents/index.tsx index 2d76a52193ded..3ac0bfa97dfa1 100644 --- a/www/apps/book/components/MDXComponents/index.tsx +++ b/www/apps/book/components/MDXComponents/index.tsx @@ -1,9 +1,11 @@ import type { MDXComponents as MDXComponentsType } from "mdx/types" import { Link, MDXComponents as UiMdxComponents } from "docs-ui" +import Feedback from "../Feedback" const MDXComponents: MDXComponentsType = { ...UiMdxComponents, a: Link, + Feedback } export default MDXComponents diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs index fe8c35acc7ac2..f6bd2ec4e0eda 100644 --- a/www/apps/book/sidebar.mjs +++ b/www/apps/book/sidebar.mjs @@ -8,12 +8,19 @@ export const sidebar = numberSidebarItems( type: "link", path: "/learn", title: "Introduction", - }, - { - type: "link", - path: "/learn/first-customizations", - title: "Your First Customizations", - chapterTitle: "First Customization", + children: [ + { + type: "link", + path: "/learn/installation", + title: "Installation", + }, + { + type: "link", + path: "/learn/first-customizations", + title: "Your First Customizations", + chapterTitle: "First Customization", + }, + ], }, { type: "link", diff --git a/www/apps/resources/app/troubleshooting/_sections/other/cors-errors.mdx b/www/apps/resources/app/troubleshooting/_sections/other/cors-errors.mdx index 274e7d445da24..221aa811fd3ef 100644 --- a/www/apps/resources/app/troubleshooting/_sections/other/cors-errors.mdx +++ b/www/apps/resources/app/troubleshooting/_sections/other/cors-errors.mdx @@ -4,19 +4,19 @@ You might see a log in your browser console, that looks like this: ![CORS error log](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003322/Medusa%20Docs/Other/jnHK115_udgf2n.png) -In your `medusa-config.ts` , you should ensure that you've configured your CORS settings correctly: +In your `medusa-config.ts`, ensure that you've configured your CORS settings correctly: ```ts title="medusa-config.ts" module.exports = defineConfig({ projectConfig: { http: { - storeCors: process.env.STORE_CORS, - adminCors: process.env.ADMIN_CORS, - authCors: process.env.AUTH_CORS, + storeCors: process.env.STORE_CORS || "http://localhost:8000", + adminCors: process.env.ADMIN_CORS || "http://localhost:9000", + authCors: process.env.AUTH_CORS || "http://localhost:8000,http://localhost:9000", }, // ... }, }) ``` -Learn more about these configurations in [this documentation](/references/medusa-config#http) \ No newline at end of file +Learn more about these configurations in [this documentation](/references/medusa-config#http). From f78d9405d8d4b08aabe95a3b18312b0082e41542 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 11 Nov 2024 15:36:40 +0300 Subject: [PATCH 2/3] fixes --- www/apps/book/components/Homepage/LinksSection/index.tsx | 2 +- www/apps/book/components/MDXComponents/index.tsx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/www/apps/book/components/Homepage/LinksSection/index.tsx b/www/apps/book/components/Homepage/LinksSection/index.tsx index 6de53458f81fd..34700fd27e2bc 100644 --- a/www/apps/book/components/Homepage/LinksSection/index.tsx +++ b/www/apps/book/components/Homepage/LinksSection/index.tsx @@ -7,7 +7,7 @@ const HomepageLinksSection = () => { title: "Customize Medusa Application", links: [ { - href: "/learn", + href: "/learn/installation", text: "Create your first application", }, { diff --git a/www/apps/book/components/MDXComponents/index.tsx b/www/apps/book/components/MDXComponents/index.tsx index 3ac0bfa97dfa1..215dde22c24fd 100644 --- a/www/apps/book/components/MDXComponents/index.tsx +++ b/www/apps/book/components/MDXComponents/index.tsx @@ -5,7 +5,7 @@ import Feedback from "../Feedback" const MDXComponents: MDXComponentsType = { ...UiMdxComponents, a: Link, - Feedback + Feedback, } export default MDXComponents From bd9d246205e60b49f1d407ea7cd427dd5130e75e Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 11 Nov 2024 15:37:43 +0300 Subject: [PATCH 3/3] fix links --- www/apps/resources/app/deployment/admin/vercel/page.mdx | 2 +- .../app/deployment/medusa-application/railway/page.mdx | 2 +- www/apps/resources/app/page.mdx | 2 +- www/apps/resources/app/recipes/ecommerce/page.mdx | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/www/apps/resources/app/deployment/admin/vercel/page.mdx b/www/apps/resources/app/deployment/admin/vercel/page.mdx index 7ab29c55fcca1..b756c8bed1eee 100644 --- a/www/apps/resources/app/deployment/admin/vercel/page.mdx +++ b/www/apps/resources/app/deployment/admin/vercel/page.mdx @@ -15,7 +15,7 @@ In this document, you’ll learn how to deploy the Medusa Admin to [Vercel](http diff --git a/www/apps/resources/app/page.mdx b/www/apps/resources/app/page.mdx index 03c82d445b771..c742f3cd35555 100644 --- a/www/apps/resources/app/page.mdx +++ b/www/apps/resources/app/page.mdx @@ -30,7 +30,7 @@ Explore Medusa's commerce modules, SDKs, configurations, recipes, and more. -Follow the [Medusa v2 Docs](!docs!) to become an advanced Medusa developer. +Follow the [Medusa Docs](!docs!/learn) to become an advanced Medusa developer. diff --git a/www/apps/resources/app/recipes/ecommerce/page.mdx b/www/apps/resources/app/recipes/ecommerce/page.mdx index 68a3f70e8b2d5..f7befc492efe7 100644 --- a/www/apps/resources/app/recipes/ecommerce/page.mdx +++ b/www/apps/resources/app/recipes/ecommerce/page.mdx @@ -74,4 +74,4 @@ Our documentation has step-by-step guides to deploy your Medusa application, Med Along with the extensive ecommerce features, Medusa also provides the architecture and tools to customize and add new features. -To learn how to develop customziations with Medusa, refer to the [Medusa documentation](!docs!) +To learn how to develop customziations with Medusa, refer to the [Medusa documentation](!docs!/learn)