diff --git a/docs/content/create-medusa-app.mdx b/docs/content/create-medusa-app.mdx
index 714fdb2319..1fe9b900f2 100644
--- a/docs/content/create-medusa-app.mdx
+++ b/docs/content/create-medusa-app.mdx
@@ -7,6 +7,7 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Feedback from '@site/src/components/Feedback';
import DocCard from '@theme/DocCard';
+import DocCardList from '@theme/DocCardList';
import Icons from '@theme/Icon';
import Troubleshooting from '@site/src/components/Troubleshooting'
import TypeErrorSection from "./troubleshooting/create-medusa-app-errors/_typeerror.md"
@@ -134,15 +135,35 @@ Once you're logged in, you can start using Medusa! Try following the setup guide
Based on what you're building, you can find a development path for you in the Recipes page.
-
+
---
diff --git a/docs/content/development/backend/configurations.md b/docs/content/development/backend/configurations.md
index a6e4161c63..07d71e3835 100644
--- a/docs/content/development/backend/configurations.md
+++ b/docs/content/development/backend/configurations.md
@@ -463,6 +463,5 @@ The Medusa core package uses the [compression package provided by Express](https
## See Also
+- [Medusa backend directory structure](./directory-structure.md)
- [Medusa architecture overview](../fundamentals/architecture-overview.md)
-- [Plugins](../plugins/overview.mdx)
-- [Modules](../modules/overview.mdx)
diff --git a/docs/content/development/backend/directory-structure.md b/docs/content/development/backend/directory-structure.md
new file mode 100644
index 0000000000..bcb229bcc8
--- /dev/null
+++ b/docs/content/development/backend/directory-structure.md
@@ -0,0 +1,183 @@
+---
+description: "In this document, you’ll learn about the directory structure of a Medusa backend. It’ll help you understand the purpose of each file and folder in your Medusa backend project."
+---
+
+# Medusa Backend Directory Structure
+
+In this document, you’ll learn about the directory structure of a Medusa backend. It’ll help you understand the purpose of each file and folder in your Medusa backend project.
+
+## Note about Beta
+
+Files that have the beta label are only available if you installed the Medusa backend using the `create-medusa-app` command.
+
+---
+
+## Root Files
+
+These are files present at the root of your Medusa backend.
+
+### .babelrc.js
+
+Defines Babel’s configurations, which are used when running the `build` command that transpiles files from the `src` directory to the `dist` directory.
+
+### .env
+
+Includes the values of environment variables. This is typically only used in development. In production you should define environment variables based on your hosting provider.
+
+### .env.template
+
+Gives an example of what variables may be included in `.env`.
+
+### .gitignore
+
+Specifies files that shouldn’t be committed to a Git repository.
+
+### .yarnrc.yml
+
+Ensures dependencies are always installed in `node-modules`. This ensures compatibility with pnpm.
+
+### index.js
+
+Defines an entry file, which is useful when starting the Medusa backend with a process manager like pm2.
+
+### medusa-config.js
+
+Defines the Medusa backend’s configurations, including the database configurations, plugins used, modules used, and more.
+
+**Read more:** [Medusa backend configurations](./configurations.md).
+
+### package.json
+
+Since the Medusa backend is an NPM package, this file defines its information as well as its dependencies. It will also include any new dependencies you install.
+
+### README.md
+
+Provides general information about the Medusa backend.
+
+### tsconfig.admin.json (beta)
+
+Defines the TypeScript configurations that are used to transpile admin customization files. So, it only works for files under the [src/admin directory](#admin-beta).
+
+### tsconfig.json
+
+Defines the general TypeScript configurations used to transpile files from the `src` directory to the `dist` directory.
+
+If you have the beta configuration files, they will extend the configurations in this file along with the configurations they each define.
+
+### tsconfig.server.json (beta)
+
+Defines the TypeScript configurations that are used to transpile Medusa backend customization files. It works for all files except for the files under the `src/admin` directory.
+
+### tsconfig.spec.json
+
+Defines TypeScript configurations for test files. These are files that either reside under a `__tests__` directory under `src`, or that have a file name ending with one of the following:
+
+- `.test.ts` or `.test.js`
+- `.spec.ts` or `.test.js`
+
+### yarn.lock or package-lock.json
+
+An automatically generated file by `yarn` or `npm` that holds the current versions of all dependencies installed to ensure the correct versions are always installed.
+
+If you used the `create-medusa-app` command to install the Medusa backend, it’ll attempt to use `yarn` by default to install the dependencies. If `yarn` is not installed on your machine, it will then fall back to using `npm`.
+
+Based on the package manager used to install the dependencies, either `yarn.lock` or `package-lock.json` will be available, or both.
+
+---
+
+## Root Directories
+
+These are the directories present at the root of your Medusa backend.
+
+### .cache
+
+This directory will only be available if you have the Medusa admin installed and you’ve already started your Medusa backend at least once before. It holds all cached files related to building the Medusa admin assets.
+
+### build
+
+This directory will only be available if you have the Medusa admin installed and you’ve either built your admin files or ran the Medusa backend at least once before. It holds the built files that are used to serve the admin in your browser.
+
+### data
+
+This directory holds a JSON file used to seed your Medusa backend with dummy data which can be useful for demo purposes. The data is seeded automatically if you include the `--seed` option when using either the `create-medusa-app` or `medusa new` commands.
+
+You can also seed the data by running the following command:
+
+```bash npm2yarn
+npm run seed
+```
+
+### dist
+
+This directory holds the transpiled Medusa backend customizations. This directory may not be available when you first install the Medusa backend. It’ll be available when you run the `build` command or start your Medusa backend with the `dev` command.
+
+The files under this directory are the files that are used in your Medusa backend. So, when you make any changes under `src`, make sure the changes are transpiled into the `dist` directory. If you’re using the `dev` or `@medusajs/medusa-cli develop` commands, this is handled automatically whenever changes occur under the `src` directory.
+
+### node_modules
+
+This directory holds all installed dependencies in your project.
+
+### src
+
+This directory holds all Medusa backend and admin customizations. More details about each subdirectory are included in [this section](#src-subdirectories).
+
+### uploads
+
+This directory holds all file uploads to the Medusa backend. It’s only used if you’re using the [Local File Service plugin](../../plugins/file-service/local.md), which is installed by default.
+
+---
+
+## src Subdirectories
+
+Files under the `src` directory hold the Medusa backend and admin customizations. These files should later be transpiled into the `dist` directory for them to be used during the backend’s runtime.
+
+If any of these directories are not available, you can create them yourself.
+
+### admin (beta)
+
+This directory holds all Medusa admin customizations. The main subdirectories of this directory are:
+
+- `widgets`: Holds all [Medusa admin widgets](../../admin/widgets.md).
+- `routes`: Holds all [Medusa admin UI routes](../../admin/routes.md).
+
+### api
+
+This directory holds all custom endpoints. You can create as many subdirectories and files that hold endpoint definitions, but only endpoints exported by the `index.ts` file are registered in the Medusa backend.
+
+**Read more:** [Endpoints](../endpoints/overview.mdx)
+
+### loaders
+
+This directory holds scripts that run when the Medusa backend starts. For example, the scripts can define a scheduled job.
+
+**Read more:** [Loaders](../loaders/overview.mdx)
+
+### migrations
+
+This directory holds all migration scripts that reflect changes on the database the Medusa backend is connected to.
+
+**Read more:** [Migrations](../entities/migrations/overview.mdx)
+
+### models
+
+This directory holds all custom entities, which represent tables in your database. You can create a new entity, or customize a Medusa entity.
+
+**Read more:** [Entities](../entities/overview.mdx)
+
+### repositories
+
+This directory holds all custom repositories which provide utility methods to access and modify data related to an entity.
+
+**Read more:** [Repositories](../entities/overview.mdx#what-are-repositories)
+
+### services
+
+This directory holds all custom services. Services define utility methods related to an entity or feature that can be used across the Medusa backend’s resources.
+
+**Read more**: [Services](../services/overview.mdx)
+
+### subscribers
+
+This directory holds all custom subscribers. Subscribers listen to emitted events and registers method to handle them.
+
+**Read more:** [Subscribers](../events/subscribers.mdx)
diff --git a/docs/content/development/backend/install.mdx b/docs/content/development/backend/install.mdx
index bf4249aba6..940df9b94f 100644
--- a/docs/content/development/backend/install.mdx
+++ b/docs/content/development/backend/install.mdx
@@ -36,6 +36,8 @@ It is recommended to use [Yarn](https://yarnpkg.com/getting-started/install) for
### 1. Install Medusa CLI
+ To install the Medusa backend, you need Medusa's CLI tool. You can install it globally or, alternatively, use it through npx with `npx @medusajs/medusa-cli `.
+
```bash npm2yarn
npm install @medusajs/medusa-cli -g
```
@@ -49,7 +51,7 @@ If you run into any errors while installing the CLI tool, check out the [trouble
### 2. Create a new Medusa project
```bash noReport
- medusa new my-medusa-store
+ medusa new my-medusa-store # or npx @medusajs/medusa-cli new
```
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.
@@ -70,7 +72,7 @@ Make sure your PostgreSQL server is running before you run the Medusa backend.
```bash noReport
cd my-medusa-store
- medusa develop
+ medusa develop # or npx @medusajs/medusa-cli develop
```
After these three steps and in only a couple of minutes, you now have a complete commerce engine running locally. You can test it out by sending a request using a tool like Postman or through the command line:
@@ -119,6 +121,7 @@ For better testing, you can add demo data to your Medusa backend by running the
```bash
medusa seed --seed-file=data/seed.json
+# or npx @medusajs/medusa-cli seed --seed-file=data/seed.json
```
---
@@ -131,14 +134,14 @@ You can access `/health` to get health status of your backend.
## Next Steps
-
diff --git a/docs/content/development/backend/prepare-environment.mdx b/docs/content/development/backend/prepare-environment.mdx
index 52ea55639a..96e117cc94 100644
--- a/docs/content/development/backend/prepare-environment.mdx
+++ b/docs/content/development/backend/prepare-environment.mdx
@@ -8,15 +8,11 @@ import MedusaCliTroubleshootingSection from '../../troubleshooting/cli-installat
# Prepare Development Environment
-This document will guide you to prepare your development environment to efficiently and properly use Medusa.
+This document includes the installation instructions for the tools required to use and run Medusa.
-## Required Tools
+## Node.js
-To get your development environment ready you need to install the following tools:
-
-### Node.js
-
-Node.js is the environment that makes it possible for Medusa to run, so you must install Node.js on your computer to start Medusa development.
+Node.js is the environment that makes it possible for Medusa to run, so you must install Node.js on your machine to start Medusa development.
:::caution
@@ -85,9 +81,9 @@ Make sure that you have Xcode command line tools installed; if not, run the fol
-### Git
+## Git
-Medusa uses Git behind the scenes when you create a new project so you'll have to install it on your computer to get started.
+Medusa uses Git behind the scenes when you create a new project. So, you'll have to install it on your machine to get started.
@@ -121,36 +117,10 @@ You can also check out [git’s guide](https://git-scm.com/download/mac) for mor
-### Medusa CLI
-
-The final installation required to get started with Medusa is the Medusa CLI. It is an NPM package you can install globally on your machine to get instant access to commands that help you manage and run your Medusa project.
-
-You can install Medusa’s CLI with the following command:
-
-```bash npm2yarn
-npm install @medusajs/medusa-cli -g
-```
-
-You can check that Medusa was installed by running the following command:
-
-```bash noReport
-medusa -v
-```
-
-#### Troubleshooting Installation
-
-
-
-### PostgreSQL
+## PostgreSQL
The Medusa backend uses PostgreSQL to store data of your commerce system.
-:::tip
-
-After installing PostgreSQL, check out the [Configure your Backend documentation](./configurations.md#postgresql-configurations) to learn how to configure PostgreSQL to work with Medusa.
-
-:::
-
@@ -180,13 +150,28 @@ You can download PostgreSQL on your macOS using [the installer on their website]
+## (Optional) Medusa CLI
+
+Medusa provides a CLI tool that can aid your through your Medusa development. You can install it globally, or you can use it through `npx`.
+
+You can install Medusa’s CLI with the following command:
+
+```bash npm2yarn
+npm install @medusajs/medusa-cli -g
+```
+
+To confirm that the CLI tool was installed successfully, run the following command:
+
+```bash noReport
+medusa -v
+```
+
+### Troubleshooting Installation
+
+
+
---
## Install Medusa Backend
-If you're not interested in installing the optional tools and want to get started with Medusa quickly, check out the [Medusa Backend Quickstart](./install.mdx).
-
-## See Also
-
-- [Install Medusa backend](./install.mdx)
-- [Configure the Medusa backend](./configurations.md)
+Once you're done installing the necessary tools in your environment, check out the [Medusa Backend Quickstart](./install.mdx) to install your Medusa backend.
diff --git a/docs/content/development/batch-jobs/create.mdx b/docs/content/development/batch-jobs/create.mdx
index 96c4b81fe6..86ee79d7cc 100644
--- a/docs/content/development/batch-jobs/create.mdx
+++ b/docs/content/development/batch-jobs/create.mdx
@@ -282,12 +282,6 @@ This section covers how to test and use your batch job strategy. Make sure to st
npx @medusajs/medusa-cli develop
```
-:::info
-
-If your `start` script uses the `medusa develop` command, whenever you make changes in the `src` directory the `build` command will automatically run and the backend will restart.
-
-:::
-
You must also use an authenticated user to send batch job requests. You can refer to the [authentication guide in the API reference](/api/admin/#section/Authentication) for more details.
If you follow along with the JS Client code snippets, make sure to [install and set it up first](../../js-client/overview.md).
diff --git a/docs/content/development/endpoints/create.md b/docs/content/development/endpoints/create.md
index fe792ac6eb..b89d110871 100644
--- a/docs/content/development/endpoints/create.md
+++ b/docs/content/development/endpoints/create.md
@@ -360,7 +360,7 @@ The `productService` has a `count` method that returns a Promise. This Promi
## Building Files
-Custom endpoints must be transpiled and moved to the `dist` directory before you can start consuming them. When you run your backend using the `medusa develop` command, it watches the files under `src` for any changes, then triggers the `build` command and restarts the server.
+Custom endpoints must be transpiled and moved to the `dist` directory before you can start consuming them. When you run your backend using either the `medusa develop` or `npx @medusajs/medusa-cli develop` commands, it watches the files under `src` for any changes, then triggers the `build` command and restarts the server.
The build isn't triggered though when the backend first starts running. So, make sure to run the `build` command before starting the backend:
diff --git a/docs/content/development/entities/create.md b/docs/content/development/entities/create.md
index a432a4b2a0..76ec5dca98 100644
--- a/docs/content/development/entities/create.md
+++ b/docs/content/development/entities/create.md
@@ -122,8 +122,8 @@ npm run build
Then, run the `migration` command:
-```bash npm2yarn
-medusa migrations run
+```bash
+npx @medusajs/medusa-cli migrations run
```
You should see that your migration have executed.
diff --git a/docs/content/development/entities/extend-entity.md b/docs/content/development/entities/extend-entity.md
index cb630ea885..9f847f7240 100644
--- a/docs/content/development/entities/extend-entity.md
+++ b/docs/content/development/entities/extend-entity.md
@@ -108,8 +108,8 @@ npm run build
Then, run the following command to migrate your changes to the database:
-```bash npm2yarn
-medusa migrations run
+```bash
+npx @medusajs/medusa-cli migrations run
```
You should see that your migration was executed, which means your changes were reflected in the database schema.
diff --git a/docs/content/development/entities/overview.mdx b/docs/content/development/entities/overview.mdx
index c278155f68..67c1e66be5 100644
--- a/docs/content/development/entities/overview.mdx
+++ b/docs/content/development/entities/overview.mdx
@@ -68,6 +68,14 @@ If you want to remove a property from the `metadata` object, you can pass the `m
---
+## What are Repositories
+
+Repositories provide generic helper methods for entities. For example, a `list` method to retrieve all entities with pagination, or `retrieve` to retrieve a single entity record.
+
+Repostories are [Typeorm repositories](https://typeorm.io/working-with-repository), so you can refer to Typeorm's documentation on all available methods.
+
+---
+
## Custom Development
Developers can create custom entities in the Medusa backend, a plugin, or in a module, then ensure it reflects in the database using a migration.
diff --git a/docs/content/development/overview.mdx b/docs/content/development/overview.mdx
index 9e927c4f2e..4f015b4d9b 100644
--- a/docs/content/development/overview.mdx
+++ b/docs/content/development/overview.mdx
@@ -79,7 +79,7 @@ The core package also holds the logic that allows developers to extend and add c
label: 'Prepare Environment',
customProps: {
icon: Icons['tools-solid'],
- description: 'Install tools that supercharge development with Medusa.'
+ description: 'Learn how to install the necessary tools to use Medusa.'
}
},
{
diff --git a/docs/content/recipes/marketplace.mdx b/docs/content/recipes/marketplace.mdx
index 69a43c0a7b..52fed038c0 100644
--- a/docs/content/recipes/marketplace.mdx
+++ b/docs/content/recipes/marketplace.mdx
@@ -130,7 +130,7 @@ To associate these entities with the `Store` entity, you need to extend and cust
```bash npm2yarn
npm run build
- npx @medusajs/medusa migrations run
+ npx @medusajs/medusa-cli migrations run
```
You can extend other entities in a similar manner to associate them with a store.
@@ -241,7 +241,7 @@ You can also extend services if you need to customize a functionality implemente
```bash
npm run build
- npx @medusajs/medusa develop
+ npx @medusajs/medusa-cli develop
```
@@ -288,7 +288,7 @@ To listen to events, you need to create Subscribers that subscribe a handler met
```bash
npm run build
- npx @medusajs/medusa develop
+ npx @medusajs/medusa-cli develop
```
diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js
index 147daf4d88..bd2e827831 100644
--- a/www/docs/sidebars.js
+++ b/www/docs/sidebars.js
@@ -1157,6 +1157,11 @@ module.exports = {
sidebar_is_group_headline: true,
},
items: [
+ {
+ type: "doc",
+ id: "development/backend/prepare-environment",
+ label: "Prepare Environment",
+ },
{
type: "doc",
id: "development/backend/install",
@@ -1164,8 +1169,8 @@ module.exports = {
},
{
type: "doc",
- id: "development/backend/prepare-environment",
- label: "Prepare Environment",
+ id: "development/backend/directory-structure",
+ label: "Directory Structure",
},
{
type: "doc",
diff --git a/www/docs/src/theme/Icon/DocumentTextSolid/index.tsx b/www/docs/src/theme/Icon/DocumentTextSolid/index.tsx
new file mode 100644
index 0000000000..494e3a935c
--- /dev/null
+++ b/www/docs/src/theme/Icon/DocumentTextSolid/index.tsx
@@ -0,0 +1,37 @@
+import React from "react"
+import { IconProps } from ".."
+
+const IconDocumentTextSolid: React.FC = ({
+ iconColorClassName,
+ ...props
+}) => {
+ return (
+
+ )
+}
+
+export default IconDocumentTextSolid
diff --git a/www/docs/src/theme/Icon/index.ts b/www/docs/src/theme/Icon/index.ts
index c0ac36af17..b344e09fa5 100644
--- a/www/docs/src/theme/Icon/index.ts
+++ b/www/docs/src/theme/Icon/index.ts
@@ -42,6 +42,7 @@ import IconCurrencyDollarSolid from "./CurrencyDollarSolid"
import IconDarkMode from "./DarkMode"
import IconDiscord from "./Discord"
import IconDocumentText from "./DocumentText"
+import IconDocumentTextSolid from "./DocumentTextSolid"
import IconExclamationCircleSolid from "./ExclamationCircleSolid"
import IconExternalLink from "./ExternalLink"
import IconFlyingBox from "./FlyingBox"
@@ -144,6 +145,7 @@ export default {
"dark-mode": IconDarkMode,
discord: IconDiscord,
"document-text": IconDocumentText,
+ "document-text-solid": IconDocumentTextSolid,
"exclamation-circle-solid": IconExclamationCircleSolid,
"external-link": IconExternalLink,
"flying-box": IconFlyingBox,