From 2363a5324e03e386d8946b78d1ebeb894a4c51a7 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Thu, 10 Aug 2023 11:44:20 +0300 Subject: [PATCH] docs: general fixes across docs (#4737) * docs: general fixes across docs * added deploy button to railway * fix eslint errors * fixes --- .../server/deploying-on-railway.md | 56 +++++++++++++++---- .../storefront/deploying-next-on-vercel.mdx | 6 ++ docs/content/development/cache/create.md | 14 +++-- .../development/events/create-subscriber.md | 10 ++-- docs/content/development/events/index.mdx | 6 ++ docs/content/development/modules/create.mdx | 26 +++++---- .../products/admin/import-products.mdx | 13 +++-- docs/content/plugins/file-service/minio.md | 10 ++-- docs/content/plugins/file-service/s3.mdx | 2 +- 9 files changed, 99 insertions(+), 44 deletions(-) diff --git a/docs/content/deployments/server/deploying-on-railway.md b/docs/content/deployments/server/deploying-on-railway.md index bff8324ec4..c9ecd023b5 100644 --- a/docs/content/deployments/server/deploying-on-railway.md +++ b/docs/content/deployments/server/deploying-on-railway.md @@ -19,6 +19,13 @@ If you're deploying the admin plugin along with the backend, you'll need at leas ::: +If you also don't have a Medusa project, you can deploy to Railway instantly with this button: + + + Deploy with Railway + + --- ## Prerequisites @@ -29,6 +36,13 @@ It is assumed that you already have a Medusa backend installed locally. If you d Furthermore, your Medusa backend should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Backend documentation](./../../development/backend/configurations.md) to learn how to do that. +### Production Modules + +If you're using development modules for events and caching, it's highly recommended to install production modules instead. These can be: + +- [Redis Event Module](../../development/events/modules/redis.md) +- [Redis Cache Module](../../development/cache/modules/redis.md) + ### Needed Accounts - A [Railway](https://railway.app/) account. @@ -40,15 +54,23 @@ Furthermore, your Medusa backend should be configured to work with PostgreSQL an --- -## Changes to Medusa Backend Codebase +## (Optional) Step 1: Add Nixpacks Configurations -By default, Railway looks for a Dockerfile in the root of the codebase. If there is one, it will try to deploy your backend using it. +If you've created your project using `create-medusa-app`, you might receive errors during the deployment process as Railway uses NPM by default. To avoid that, you need to configure Nixpacks to either use `yarn` or add the `--legacy-peer-deps` option to `npm install`. -As this guide doesn't use Docker, make sure to delete `Dockerfile` from the root of your Medusa backend. +In the root of your Medusa project, add the `nixpacks.toml` file with the following content: + +```toml +[phases.setup] +nixPkgs = ['nodejs', 'yarn'] + +[phases.install] +cmds=['yarn install'] +``` --- -## Create GitHub Repository +## Step 2: Create GitHub Repository Before you can deploy your Medusa backend you need to create a GitHub repository and push the code base to it. @@ -83,7 +105,7 @@ After pushing the changes, you can find the files in your GitHub repository. --- -## Deploy to Railway +## Step 3: Deploy to Railway In this section, you’ll create the PostgreSQL and Redis databases first, then deploy the backend from the GitHub repository. @@ -102,7 +124,7 @@ In the same project view: 1. Click on the New button. 2. Choose the Database option. -3. Choose Add Redis**.** +3. Choose Add Redis. A new Redis database will be added to the project view in a few seconds. Click on it to open the database sidebar. @@ -117,7 +139,7 @@ In the same project view: 1. Click on the New button. 2. Choose the ”GitHub Repo” option. -3. Choose the ”Configure GitHub App” option to give Railway permission to read and pull your code from GitHub. +3. If you still haven't given GitHub permissions to Railway, choose the ”Configure GitHub App” option to do that. 4. Choose the repository from the GitHub Repo dropdown. :::tip @@ -126,7 +148,7 @@ If the GitHub repositories in the dropdown are stuck on loading and aren't showi ::: -It will take the backend a few minutes to deploy successfully. +It will take the backend a few minutes for the deployment to finish. It may fail since you haven't added the environment variables yet. ### Configure Environment Variables @@ -162,7 +184,7 @@ The start command is the command used to run the backend. You’ll change it to To change the start command of your Medusa backend: 1. Click on the GitHub repository’s card. -2. Click on the Settings tab and scroll down to the Service section. +2. Click on the Settings tab and scroll down to the Deploy section. 3. Paste the following in the Start Command field: ```bash @@ -174,12 +196,12 @@ medusa migrations run && medusa start The last step is to add a domain name to your Medusa backend. To do that: 1. Click on the GitHub repository’s card. -2. Click on the Settings tab and scroll down to the Domains section. +2. Click on the Settings tab and scroll down to the Environment section. 3. Either click on the Custom Domain button to enter your own domain or the Generate Domain button to generate a random domain. --- -## Test the Backend +## Step 4: Test the Backend Every change you make to the settings redeploys the backend. You can check the Deployments of the backend by clicking on the GitHub repository’s card and choosing the Deployments tab. @@ -215,6 +237,10 @@ If you run into any issues or a problem with your deployed backend, you can chec 2. Click on the Deployments tab. 3. Click on the View Logs button. +### Error: connect ENOENT + +This error may be thrown by a module that uses Redis. If you see it in your build or deploy logs, make sure that your Redis configurations are correct. + --- ## Run Commands on the Backend @@ -223,6 +249,14 @@ To run commands on your backend, you can use [Railway’s CLI tool to run a loca For example, you can run commands on the backend to seed the database or create a new user using [Medusa’s CLI tool](../../cli/reference.mdx). +### Create Admin User + +You can create an admin user by running the following command in the root of your Medusa project: + +```bash +railway run npx medusa user --email admin@medusa-test.com --password supersecret +``` + --- ## See Also diff --git a/docs/content/deployments/storefront/deploying-next-on-vercel.mdx b/docs/content/deployments/storefront/deploying-next-on-vercel.mdx index 7dd86772c0..b83a1d99c4 100644 --- a/docs/content/deployments/storefront/deploying-next-on-vercel.mdx +++ b/docs/content/deployments/storefront/deploying-next-on-vercel.mdx @@ -17,6 +17,12 @@ Alternatively, you can directly deploy the Next.js Starter Template to Vercel wi Deploy with Vercel +:::note + +After the deployment with this button, make sure to [configure CORS in your backend](#step-3-configure-cors-on-the-medusa-backend). + +::: + ## Prerequisites ### Medusa Components diff --git a/docs/content/development/cache/create.md b/docs/content/development/cache/create.md index 54b06591c9..17bf58a12d 100644 --- a/docs/content/development/cache/create.md +++ b/docs/content/development/cache/create.md @@ -30,11 +30,11 @@ You can refer to the [Project Preparation step in the Create Module documentatio ## Step 1: Create the Service -Create the file `services/memcached-cache.ts` which will hold your cache service. Note that the name of the file is recommended to be in the format `-cache`. So, if you’re not integrating `memcached`, you should replace the name with what’s relevant for your module. +Create the file `src/services/memcached-cache.ts` which will hold your cache service. Note that the name of the file is recommended to be in the format `-cache`. So, if you’re not integrating `memcached`, you should replace the name with what’s relevant for your module. Add the following content to the file: -```ts title=services/memcached-cache.ts +```ts title=src/services/memcached-cache.ts import { ICacheService } from "@medusajs/types" class MemcachedCacheService implements ICacheService { @@ -201,12 +201,14 @@ class MemcachedCacheService implements ICacheService { After implementing the cache service, you must export it so that the Medusa backend can use it. -Create the file `index.ts` with the following content: +Create the file `src/index.ts` with the following content: -```ts title=index.ts +```ts title=src/index.ts import { ModuleExports } from "@medusajs/modules-sdk" -import { MemcachedCacheService } from "./services" +import { + MemcachedCacheService, +} from "./services/memcached-cache" const service = MemcachedCacheService @@ -235,7 +237,7 @@ module.exports = { modules: { // ... cacheService: { - resolve: "path/to/custom-module", + resolve: "path/to/custom-module/src/index.ts", options: { // any necessary options ttl: 30, diff --git a/docs/content/development/events/create-subscriber.md b/docs/content/development/events/create-subscriber.md index 885b4e8ef0..2e9032ff16 100644 --- a/docs/content/development/events/create-subscriber.md +++ b/docs/content/development/events/create-subscriber.md @@ -15,9 +15,9 @@ After creating the file under `src/subscribers`, in the constructor of your subs The `eventBusService.subscribe` method receives the name of the event as a first parameter and as a second parameter a method in your subscriber that will handle this event. -For example, here is the `OrderNotifierSubscriber` class created in `src/subscribers/orderNotifier.ts`: +For example, here is the `OrderNotifierSubscriber` class created in `src/subscribers/order-notifier.ts`: -```ts title=src/subscribers/orderNotifier.ts +```ts title=src/subscribers/order-notifier.ts class OrderNotifierSubscriber { constructor({ eventBusService }) { eventBusService.subscribe("order.placed", this.handleOrder) @@ -93,7 +93,7 @@ You can access any service through the dependencies injected to your subscriber For example: -```ts title=src/subscribers/orderNotifier.ts +```ts title=src/subscribers/order-notifier.ts class OrderNotifierSubscriber { constructor({ productService, eventBusService }) { this.productService = productService @@ -109,7 +109,7 @@ class OrderNotifierSubscriber { You can then use `this.productService` anywhere in your subscriber’s methods. For example: -```ts title=src/subscribers/orderNotifier.ts +```ts title=src/subscribers/order-notifier.ts class OrderNotifierSubscriber { // ... handleOrder = async (data) => { @@ -129,4 +129,6 @@ When using attributes defined in the subscriber, such as the `productService` in ## See Also +- [Example: send order confirmation email](../../modules/orders/backend/send-order-confirmation.md) +- [Example: send registration confirmation email](../../modules/customers/backend/send-confirmation.md) - [Create a Plugin](../plugins/create.mdx) \ No newline at end of file diff --git a/docs/content/development/events/index.mdx b/docs/content/development/events/index.mdx index 993ecc5971..74498f4b55 100644 --- a/docs/content/development/events/index.mdx +++ b/docs/content/development/events/index.mdx @@ -13,6 +13,12 @@ In this document, you’ll learn what events are and why they’re useful in Med Events are used in Medusa to inform different parts of the commerce ecosystem that this event occurred. For example, when an order is placed, the `order.placed` event is triggered, which informs notification services like SendGrid to send a confirmation email to the customer. +:::tip + +If you want to implement order confirmation emails, you can check this [step-by-step guide](../../modules/orders/backend/send-order-confirmation.md). + +::: + The events system in Medusa is built on a publish/subscribe architecture. The Medusa core publish an event when an action takes place, and modules, plugins, or other forms of customizations can subscribe to that event. [Subscribers](./subscribers.mdx) can then perform a task asynchronously when the event is triggered. Although the core implements the main logic behind the events system, you’ll need to use an event module that takes care of the publish/subscribe functionality such as subscribing and emitting events. Medusa provides modules that you can use both for development and production, including Redis and Local modules. diff --git a/docs/content/development/modules/create.mdx b/docs/content/development/modules/create.mdx index 6642971498..c2fc55ab90 100644 --- a/docs/content/development/modules/create.mdx +++ b/docs/content/development/modules/create.mdx @@ -20,9 +20,11 @@ Before you start implementing the custom functionality in your module, it's reco ``` custom-module | -|___ index.ts -| -|___ services // directory +|___ src + | + |___ index.ts + | + |___ services // directory ``` The directory can be an NPM project, but that is optional. `index.ts` acts as an entry point to your Module. You'll learn about its content in a later step. The `service` directory will hold your custom services. If you're adding other resources you can add other directories for them. For example, if you're adding an entity you can add a `models` directory. @@ -219,12 +221,14 @@ For example, consider you have the following file structure: | |___ custom-module | | -| |___ index.ts -| | -| |___ services -| | | -| | |___ custom-service.ts -| |___ // more files +| |___ src +| | +| |___ index.ts +| | +| |___ services +| | | +| | |___ custom-service.ts +| |___ // more files | | |___ medusa-backend @@ -240,7 +244,7 @@ module.exports = { modules: { // ... moduleType: { - resolve: "../custom-module", + resolve: "../custom-module/src", // ... }, }, @@ -255,7 +259,7 @@ module.exports = { modules: { // ... moduleType: { - resolve: "../custom-module/index.ts", + resolve: "../custom-module/src/index.ts", // ... }, }, diff --git a/docs/content/modules/products/admin/import-products.mdx b/docs/content/modules/products/admin/import-products.mdx index e61c68378c..f5d5b2bdc1 100644 --- a/docs/content/modules/products/admin/import-products.mdx +++ b/docs/content/modules/products/admin/import-products.mdx @@ -29,16 +29,16 @@ Part of the process of importing products is uploading a CSV file. This requires - [MinIO](../../../plugins/file-service/minio.md) (At least version `1.1.0`) - [Spaces](../../../plugins/file-service/spaces.md) -### CSV File - -You must have a CSV file that you will use to import products into your Medusa backend. You can check [this CSV example file](https://medusa-doc-files.s3.amazonaws.com/product-import-1.3.8.csv) to see which format is required for your import. - :::note -If you have Sales Channels enabled on your backend, you must use [this CSV example file](https://medusa-doc-files.s3.amazonaws.com/product-import-sales-channels.csv) instead. +The local file service can't be used for product import. ::: +### CSV File + +You must have a CSV file that you will use to import products into your Medusa backend. You can check [this CSV example file](https://medusa-doc-files.s3.amazonaws.com/product-import-sales-channels.csv) to see which format is required for your import. + ### JS Client This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods. @@ -122,7 +122,6 @@ fetch(`/admin/uploads`, { ```bash curl -L -X POST '/admin/uploads' \ -H 'Authorization: Bearer ' \ - -H 'Content-Type: text/csv' \ -F 'files=@""' ``` @@ -131,6 +130,8 @@ curl -L -X POST '/admin/uploads' \ This request returns an array of uploads. Each item in the array is an object that includes the properties `url` and `key`. You’ll need the `key` to import the products next. +Where `` is a full path to the file. For example, `/Users/medusa/product-import-sales-channels.csv` + --- ## 2. Create a Batch Job for Product Import diff --git a/docs/content/plugins/file-service/minio.md b/docs/content/plugins/file-service/minio.md index e6f73794bd..3d1f25c01b 100644 --- a/docs/content/plugins/file-service/minio.md +++ b/docs/content/plugins/file-service/minio.md @@ -41,11 +41,11 @@ minio server ~/minio --console-address :9090 --address :9001 After installing MinIO and logging into the Console, you can create a bucket that will store the files of your Medusa backend by following these steps: -1. Click on the “Create Bucket” button -2. For the Bucket Name field, enter a name for the bucket. By MinIO’s requirement, the name can only consist of lower case characters, numbers, dots (`.`), and hyphens (`-`). -3. Click on the Create Bucket button. -4. On the bucket's page, click on the cog icon at the top right to configure the bucket. -5. Click on the edit icon next to Access Policy. +1. Go to the Buckets page from the sidebar. +2. Click on the “Create Bucket” button. +3. For the Bucket Name field, enter a name for the bucket. By MinIO’s requirement, the name can only consist of lower case characters, numbers, dots (`.`), and hyphens (`-`). +4. Click on the Create Bucket button. +5. On the bucket's page, click on the edit icon next to Access Policy. 6. In the pop-up that opens, change the selected value to “public” and click Set. :::warning diff --git a/docs/content/plugins/file-service/s3.mdx b/docs/content/plugins/file-service/s3.mdx index 2c554ac394..d8298dd3c8 100644 --- a/docs/content/plugins/file-service/s3.mdx +++ b/docs/content/plugins/file-service/s3.mdx @@ -220,7 +220,7 @@ module.exports = withStoreConfig({ Where: - `` is the name of the S3 bucket you’re using -- `` is the region of the S3 bucket (for example, `eu-west-1`) +- `` is the region of the S3 bucket (for example, `eu-west-1`). If your S3 URL doesn't use region in it, you may omit it to be instead `.s3.amazonaws.com`. ---