From 2637b82933b86d5e5cd9da5db78633afaa4f21f9 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 5 Jun 2023 13:25:44 +0300 Subject: [PATCH] docs: general fixes across documentation (#4248) * docs: added details about the migration revert command * added a note about running postgres before the backend * added a link to typeorm's documentation * fix broken links * fixed section title * fixed admonitions --- docs/content/development/backend/install.mdx | 22 ++++++++++++++----- docs/content/development/entities/create.md | 6 +++++ .../development/entities/extend-entity.md | 6 +++++ .../development/entities/migrations/create.md | 2 +- .../entities/migrations/overview.mdx | 22 ++++++++++++++----- docs/content/development/plugins/create.md | 2 +- docs/content/plugins/cms/contentful/index.md | 2 +- docs/content/plugins/cms/strapi.md | 6 ++--- 8 files changed, 50 insertions(+), 18 deletions(-) diff --git a/docs/content/development/backend/install.mdx b/docs/content/development/backend/install.mdx index 520b4e7016..961f8cc40b 100644 --- a/docs/content/development/backend/install.mdx +++ b/docs/content/development/backend/install.mdx @@ -13,7 +13,11 @@ This document will guide you through setting up your Medusa backend in a three s ## Prerequisites -Medusa requires Node.js v16+, Git, and PostgreSQL to be installed. If you don't have them installed already, you can check out the [Prepare Environment](./prepare-environment.mdx) documnetation to learn how to install them. +Before you can install and use Medusa, you need the following tools installed on your machine: + +- [Node.js v16+](./prepare-environment.mdx#nodejs) +- [Git](./prepare-environment.mdx#git) +- [PostgreSQL](./prepare-environment.mdx#postgresql) --- @@ -45,14 +49,20 @@ If you run into any errors while installing the CLI tool, check out the [trouble You'll then be asked to specify your PostgreSQL database credentials. You can choose "Continue" to use the default credentials shown in the terminal, choose "Change credentials" to specify your PostgreSQL credentails, or choose "Skip database setup" to create the database later. - :::warning - - If you choose "Skip database setup" you will need to [set the database configurations](./configurations.md#database-configuration) and [run migrations](../entities/migrations/overview.mdx#migrate-command) later. - - ::: +:::warning + +If you choose "Skip database setup" you will need to [set the database configurations](./configurations.md#database-configuration) and [run migrations](../entities/migrations/overview.mdx#migrate-command) later. + +::: ### 3. Start your Medusa backend +:::note + +Make sure your PostgreSQL server is running before you run the Medusa backend. + +::: + ```bash noReport cd my-medusa-store medusa develop diff --git a/docs/content/development/entities/create.md b/docs/content/development/entities/create.md index 4d0b08ffa5..fc5d084cfe 100644 --- a/docs/content/development/entities/create.md +++ b/docs/content/development/entities/create.md @@ -177,6 +177,12 @@ await postRepository.softDelete(post.id) --- +## Advanced Entity Definitions + +With entities, you can create relationships, index keys, and more. As Medusa uses Typeorm, you can learn about using these functionalities through [Typeorm's documentation](https://typeorm.io/). + +--- + ## See Also - [Extend Entity](./extend-entity.md) diff --git a/docs/content/development/entities/extend-entity.md b/docs/content/development/entities/extend-entity.md index d335502460..06c4472f76 100644 --- a/docs/content/development/entities/extend-entity.md +++ b/docs/content/development/entities/extend-entity.md @@ -202,3 +202,9 @@ You can also add custom relations by changing the following defined variables: - `defaultStoreProductsRelations`: The relations of a product that are retrieved and returned by default in the product's store endpoints. If you want to apply this example for a different entity or set of endpoints, you would need to change the import path `@medusajs/medusa/dist/api/routes/store/products/index` to the path of the endpoints you're targeting. You also need to change `allowedStoreProductsFields` and `defaultStoreProductsFields` to the names of the variables in that file, and the same goes for relations. Typically, these names would be of the format `(allowed|default)(Store|Admin)(Entity)(Fields|Relation)`. + +--- + +## Advanced Entity Definitions + +With entities, you can create relationships, index keys, and more. As Medusa uses Typeorm, you can learn about using these functionalities through [Typeorm's documentation](https://typeorm.io/). diff --git a/docs/content/development/entities/migrations/create.md b/docs/content/development/entities/migrations/create.md index 49a33d439a..992f957cbd 100644 --- a/docs/content/development/entities/migrations/create.md +++ b/docs/content/development/entities/migrations/create.md @@ -90,7 +90,7 @@ npm run build The last step is to run the migration with the command detailed earlier ```bash -medusa migrations run +npx @medusajs/medusa-cli migrations run ``` If you check your database now you should see that the change defined by the migration has been applied successfully. diff --git a/docs/content/development/entities/migrations/overview.mdx b/docs/content/development/entities/migrations/overview.mdx index 8a20ce1c16..03ec1e1def 100644 --- a/docs/content/development/entities/migrations/overview.mdx +++ b/docs/content/development/entities/migrations/overview.mdx @@ -25,16 +25,14 @@ Migrations are used to apply changes to the database schema. However, there are --- -## How to Run Migrations - -Migrations in Medusa can be done in one of two ways: +## Migration Commands ### Migrate Command Using the Medusa CLI tool, you can run migrations with the following command: ```bash -medusa migrations run +npx @medusajs/medusa-cli 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 backend. @@ -46,10 +44,22 @@ Seeding is the process of filling your database with data that is either essenti You can use the following command to seed your database: ```bash npm2yarn -npm run seed +npx @medusajs/medusa-cli@latest seed -f ./data/seed.json ``` -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 backend. +This assumes that you have the file `data/seed.json` in your Medusa backend, which is available by default. It includes the demo data to seed into your database. + +### Revert Migrations + +To revert the last migration you ran, run the following command: + +```bash +npx @medusajs/medusa-cli@latest migrations revert +``` + +### Other Migrations Commands + +You can learn about migration commands available in the Medusa CLI tool by referring to the [Medusa CLI reference](../../../cli/reference.md#migrations) --- diff --git a/docs/content/development/plugins/create.md b/docs/content/development/plugins/create.md index edca0c77fe..2c3aa3b3c0 100644 --- a/docs/content/development/plugins/create.md +++ b/docs/content/development/plugins/create.md @@ -28,7 +28,7 @@ If you run into any errors while installing the CLI tool, check out the [trouble The recommended way to create a plugin is using the Medusa CLI. Run the following command to create a new Medusa project: ```bash -medusa new medusa-plugin-custom +npx @medusajs/medusa-cli@latest new medusa-plugin-custom ``` Where `medusa-plugin-custom` is the name of the plugin you’re creating. In Medusa, plugins are named based on their functionalities. diff --git a/docs/content/plugins/cms/contentful/index.md b/docs/content/plugins/cms/contentful/index.md index 811f92d744..b88f2ce490 100644 --- a/docs/content/plugins/cms/contentful/index.md +++ b/docs/content/plugins/cms/contentful/index.md @@ -38,7 +38,7 @@ Instead of using the default Medusa backend starter, you must use the [Contentfu In your terminal, run the following command to install the backend: ```bash -medusa new medusa-contentful https://github.com/medusajs/medusa-starter-contentful +npx @medusajs/medusa-cli@latest new medusa-contentful https://github.com/medusajs/medusa-starter-contentful ``` This installs a new Medusa backend in the directory `medusa-contentful`. diff --git a/docs/content/plugins/cms/strapi.md b/docs/content/plugins/cms/strapi.md index b9da746415..e4eeb6775d 100644 --- a/docs/content/plugins/cms/strapi.md +++ b/docs/content/plugins/cms/strapi.md @@ -86,7 +86,7 @@ You can use the Strapi plugin on an existing Medusa backend, however, existing d To create your Medusa backend, run the following command: ```bash -medusa new medusa-backend +npx @medusajs/medusa-cli@latest new medusa-backend ``` ### Configure your Backend @@ -107,13 +107,13 @@ You must then configure your backend to: After configuring the connection to the database, you must run migrations to add the necessary database schema definitions in your database. To do that, run the following command in the `medusa-backend` directory: ```bash -medusa migrations run +npx @medusajs/medusa-cli@latest migrations run ``` You can optionally seed your database with demo data by running the `seed` command: ```bash -medusa seed --seed-file=data/seed.json +npx @medusajs/medusa-cli@latest seed --seed-file=data/seed.json ``` ---