docs: added directory structure documentation (#4612)

* docs: added directory structure documentation

* improvements
This commit is contained in:
Shahed Nasser
2023-07-27 12:18:31 +03:00
committed by GitHub
parent 30e8bb2757
commit 5fcb0d5281
15 changed files with 323 additions and 77 deletions

View File

@@ -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.
<DocCard item={{
type: 'link',
href: '/recipes',
label: 'Recipes',
customProps: {
icon: Icons['map'],
description: "Find learning paths based on what you're building"
}
}} />
<DocCardList colSize={4} items={[
{
type: 'link',
href: '/recipes',
label: 'Recipes',
customProps: {
icon: Icons['map'],
description: "Find learning paths based on what you're building"
}
},
{
type: 'link',
href: '/development/overview',
label: 'Medusa Backend Basics',
customProps: {
icon: Icons['server-stack-solid'],
description: 'Learn all the basics of developing with the Medusa backend.'
}
},
{
type: 'link',
href: '/modules/overview',
label: 'Commerce Modules',
customProps: {
icon: Icons['puzzle-solid'],
description: 'Learn about the available commerce modules and features in the Medusa backend.'
}
},
]} />
---

View File

@@ -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)

View File

@@ -0,0 +1,183 @@
---
description: "In this document, youll learn about the directory structure of a Medusa backend. Itll help you understand the purpose of each file and folder in your Medusa backend project."
---
# Medusa Backend Directory Structure
In this document, youll learn about the directory structure of a Medusa backend. Itll 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 Babels 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 shouldnt 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 backends 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, itll 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 youve 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 youve 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. Itll 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 youre 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. Its only used if youre 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 backends 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 backends 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)

View File

@@ -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 <command>`.
```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
<DocCardList colSize={6} items={[
<DocCardList colSize={4} items={[
{
type: 'link',
href: '/development/fundamentals/architecture-overview',
label: 'Backend Architecture',
href: '/development/backend/directory-structure',
label: 'Directory Structure',
customProps: {
icon: Icons['circle-stack-solid'],
description: 'Learn about the different resources that your Medusa backend is made of.'
icon: Icons['document-text-solid'],
description: 'Learn about the purpose of each file and directory in the Medusa backend.'
}
},
{
@@ -149,5 +152,14 @@ You can access `/health` to get health status of your backend.
icon: Icons['tools-solid'],
description: 'Learn about configuring your backend and loading environment variables.'
}
},
{
type: 'link',
href: '/development/fundamentals/architecture-overview',
label: 'Backend Architecture',
customProps: {
icon: Icons['circle-stack-solid'],
description: 'Learn about the different resources that your Medusa backend is made of.'
}
}
]} />

View File

@@ -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
</TabItem>
</Tabs>
### 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.
<Tabs groupId="operating-systems" queryString="os">
<TabItem value="windows" label="Windows" default>
@@ -121,36 +117,10 @@ You can also check out [gits guide](https://git-scm.com/download/mac) for mor
</TabItem>
</Tabs>
### 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 Medusas 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
<MedusaCliTroubleshootingSection />
### 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.
:::
<Tabs groupId="operating-systems" queryString="os">
<TabItem value="windows" label="Windows">
@@ -180,13 +150,28 @@ You can download PostgreSQL on your macOS using [the installer on their website]
</TabItem>
</Tabs>
## (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 Medusas 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
<MedusaCliTroubleshootingSection />
---
## 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.

View File

@@ -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).

View File

@@ -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:

View File

@@ -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.

View File

@@ -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.

View File

@@ -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.

View File

@@ -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.'
}
},
{

View File

@@ -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
```
</details>
@@ -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
```
</details>

View File

@@ -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",

View File

@@ -0,0 +1,37 @@
import React from "react"
import { IconProps } from ".."
const IconDocumentTextSolid: React.FC<IconProps> = ({
iconColorClassName,
...props
}) => {
return (
<svg
width={props.width || 20}
height={props.height || 20}
viewBox="0 0 20 20"
fill="none"
xmlns="http://www.w3.org/2000/svg"
{...props}
>
<path
fillRule="evenodd"
clipRule="evenodd"
d="M4.91521 1.625C4.08888 1.625 3.41968 2.295 3.41968 3.12054V16.8795C3.41968 17.705 4.08968 18.375 4.91521 18.375H15.0849C15.9104 18.375 16.5804 17.705 16.5804 16.8795V10.5982C16.5804 9.80493 16.2653 9.04414 15.7043 8.48321C15.1434 7.92227 14.3826 7.60714 13.5893 7.60714H12.0938C11.6971 7.60714 11.3167 7.44958 11.0363 7.16911C10.7558 6.88864 10.5982 6.50825 10.5982 6.11161V4.61607C10.5982 3.82279 10.2831 3.062 9.72218 2.50106C9.16125 1.94013 8.40046 1.625 7.60718 1.625H4.91521ZM6.41075 12.3929C6.41075 12.2342 6.47378 12.082 6.58596 11.9699C6.69815 11.8577 6.85031 11.7946 7.00896 11.7946H12.9911C13.1498 11.7946 13.3019 11.8577 13.4141 11.9699C13.5263 12.082 13.5893 12.2342 13.5893 12.3929C13.5893 12.5515 13.5263 12.7037 13.4141 12.8159C13.3019 12.928 13.1498 12.9911 12.9911 12.9911H7.00896C6.85031 12.9911 6.69815 12.928 6.58596 12.8159C6.47378 12.7037 6.41075 12.5515 6.41075 12.3929ZM7.00896 14.1875C6.85031 14.1875 6.69815 14.2505 6.58596 14.3627C6.47378 14.4749 6.41075 14.6271 6.41075 14.7857C6.41075 14.9444 6.47378 15.0965 6.58596 15.2087C6.69815 15.3209 6.85031 15.3839 7.00896 15.3839H10C10.1587 15.3839 10.3108 15.3209 10.423 15.2087C10.5352 15.0965 10.5982 14.9444 10.5982 14.7857C10.5982 14.6271 10.5352 14.4749 10.423 14.3627C10.3108 14.2505 10.1587 14.1875 10 14.1875H7.00896Z"
className={
iconColorClassName ||
"tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle"
}
/>
<path
d="M10.7745 1.8772C11.4338 2.6373 11.7961 3.61006 11.7947 4.61622V6.11176C11.7947 6.27686 11.9287 6.41086 12.0938 6.41086H13.5893C14.5955 6.40947 15.5683 6.77177 16.3284 7.43102C15.9774 6.09637 15.2783 4.87888 14.3025 3.90306C13.3267 2.92724 12.1092 2.22812 10.7745 1.8772Z"
className={
iconColorClassName ||
"tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle"
}
/>
</svg>
)
}
export default IconDocumentTextSolid

View File

@@ -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,