asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: publish restructure (#3496)

Browse Source 
* docs: added features and guides overview page

* added image

* added version 2

* added version 3

* added version 4

* docs: implemented new color scheme

* docs: redesigned sidebar (#3193)

* docs: redesigned navbar for restructure (#3199)

* docs: redesigned footer (#3209)

* docs: redesigned cards (#3230)

* docs: redesigned admonitions (#3231)

* docs: redesign announcement bar (#3236)

* docs: redesigned large cards (#3239)

* docs: redesigned code blocks (#3253)

* docs: redesigned search modal and page (#3264)

* docs: redesigned doc footer (#3268)

* docs: added new sidebars + refactored css and assets (#3279)

* docs: redesigned api reference sidebar

* docs: refactored css

* docs: added code tabs transition

* docs: added new sidebars

* removed unused assets

* remove unusued assets

* Fix deploy errors

* fix incorrect link

* docs: fixed code responsivity + missing icons (#3283)

* docs: changed icons (#3296)

* docs: design fixes to the sidebar (#3297)

* redesign fixes

* docs: small design fixes

* docs: several design fixes after restructure (#3299)

* docs: bordered icon fixes

* docs: desgin fixes

* fixes to code blocks and sidebar scroll

* design adjustments

* docs: restructured homepage (#3305)

* docs: restructured homepage

* design fixes

* fixed core concepts icon

* docs: added core concepts page (#3318)

* docs: restructured homepage

* design fixes

* docs: added core concepts page

* changed text of different components

* docs: added architecture link

* added missing prop for user guide

* docs: added regions overview page (#3327)

* docs: added regions overview

* moved region pages to new structure

* docs: fixed description of regions architecture page

* small changes

* small fix

* docs: added customers overview page (#3331)

* docs: added regions overview

* moved region pages to new structure

* docs: fixed description of regions architecture page

* small changes

* small fix

* docs: added customers overview page

* fix link

* resolve link issues

* docs: updated regions architecture image

* docs: second-iteration fixes (#3347)

* docs: redesigned document

* design fixes

* docs: added products overview page (#3354)

* docs: added carts overview page (#3363)

* docs: added orders overview (#3364)

* docs: added orders overview

* added links in overview

* docs: added vercel redirects

* docs: added soon badge for cards (#3389)

* docs: resolved feedback changes + organized troubleshooting pages (#3409)

* docs: resolved feedback changes

* added extra line

* docs: changed icons for restructure (#3421)

* docs: added taxes overview page (#3422)

* docs: added taxes overview page

* docs: fix sidebar label

* added link to taxes overview page

* fixed link

* docs: fixed sidebar scroll (#3429)

* docs: added discounts overview (#3432)

* docs: added discounts overview

* fixed links

* docs: added gift cards overview (#3433)

* docs: added price lists overview page (#3440)

* docs: added price lists overview page

* fixed links

* docs: added sales channels overview page (#3441)

* docs: added sales overview page

* fixed links

* docs: added users overview (#3443)

* docs: fixed sidebar border height (#3444)

* docs: fixed sidebar border height

* fixed svg markup

* docs: added possible solutions to feedback component (#3449)

* docs: added several overview pages + restructured files (#3463)

* docs: added several overview pages

* fixed links

* docs: added feature flags + PAK overview pages (#3464)

* docs: added feature flags + PAK overview pages

* fixed links

* fix link

* fix link

* fixed links colors

* docs: added strategies overview page (#3468)

* docs: automated upgrade guide (#3470)

* docs: automated upgrade guide

* fixed vercel redirect

* docs: restructured files in docs codebase (#3475)

* docs: restructured files

* docs: fixed eslint exception

* docs: finished restructure loose-ends (#3493)

* fixed uses of backend

* docs: finished loose ends

* eslint fixes

* fixed links

* merged master

* added update instructions for v1.7.12
This commit is contained in:
Shahed Nasser
2023-03-16 17:03:10 +02:00
committed by GitHub
parent f312ce1e0f
commit 1decaa27c7
415 changed files with 12422 additions and 5098 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
docs/content/development/entities/create.md Normal file
View File

@@ -0,0 +1,146 @@
---
description: 'Learn how to create an entity in Medusa. This guide also explains how to create a repository and access and delete the entity.'
addHowToData: true
---
# Create an Entity
In this document, you’ll learn how you can create an [Entity](./overview.mdx).
## Create the Entity
To create an entity, create a TypeScript file in `src/models`. For example, here’s a `Post` entity defined in the file `src/models/post.ts`:
```ts title=src/models/post.ts
import {
BeforeInsert,
Column,
Entity,
PrimaryColumn,
} from "typeorm"
import { BaseEntity } from "@medusajs/medusa"
import { generateEntityId } from "@medusajs/medusa/dist/utils"
@Entity()
export class Post extends BaseEntity {
@Column({ type: "varchar" })
title: string | null
@BeforeInsert()
private beforeInsert(): void {
this.id = generateEntityId(this.id, "post")
}
}
```
This entity has one column `title` defined. However, since it extends `BaseEntity` it will also have the `id`, `created_at`, and `updated_at` columns.
Medusa’s core entities all have the following format for IDs: `<PREFIX>_<RANDOM>`. For example, an order might have the ID `order_01G35WVGY4D1JCA4TPGVXPGCQM`.
To generate an ID for your entity that matches the IDs generated for Medusa’s core entities, you should add a `BeforeInsert` event handler. Then, inside that handler use Medusa’s utility function `generateEntityId` to generate the ID. It accepts the ID as a first parameter and the prefix as a second parameter. The `Post` entity IDs will be of the format `post_<RANDOM>`.
If you want the entity to also be soft deletable then it should extend `SoftDeletableEntity` instead:
```ts
import { SoftDeletableEntity } from "@medusajs/medusa"
@Entity()
export class Post extends SoftDeletableEntity {
// ...
}
```
You can learn more about what decorators and column types you can use in [Typeorm’s documentation](https://typeorm.io/entities).
### Create a Migration
Additionally, you must create a migration for your entity. Migrations are used to update the database schema with new tables or changes to existing tables.
You can learn more about Migrations, how to create them, and how to run them in the [Migration documentation](./migrations/overview.mdx).
### Create a Repository
Entities data can be easily accessed and modified using Typeorm [Repositories](https://typeorm.io/working-with-repository). To create a repository, create a file in `src/repositories`. For example, here’s a repository `PostRepository` created in `src/repositories/post.ts`:
```ts title=src/repositories/post.ts
import { EntityRepository, Repository } from "typeorm"
import { Post } from "../models/post"
@EntityRepository(Post)
export class PostRepository extends Repository<Post> { }
```
This repository is created for the `Post` and that is indicated using the decorator `@EntityRepository`.
:::tip
Be careful with your file names as it can cause unclear errors in Typeorm. Make sure all your file names are small letters for both entities and repositories to avoid any issues with file names.
:::
---
## Access a Custom Entity
:::note
Before trying this step make sure that you’ve created and run your migrations. You also need to re-build your code using:
```bash npm2yarn
npm run build
```
:::
You can access your custom entity data in the database in services or subscribers using the repository. For example, here’s a service that lists all posts:
```ts
import { TransactionBaseService } from "@medusajs/medusa"
class PostService extends TransactionBaseService {
constructor({ postRepository, manager }) {
super({ postRepository, manager })
this.postRepository = postRepository
this.manager_ = manager
}
async list() {
const postRepository = this.manager_
.getCustomRepository(this.postRepository)
return await postRepository.find()
}
}
export default PostService
```
In the constructor, you can use dependency injection to get access to instances of services and repositories. Here, you initialize class fields `postRepository` and `manager`. The `manager` is a [Typeorm Entity Manager](https://typeorm.io/working-with-entity-manager).
Then, in the method `list`, you can obtain an instance of the `PostRepository` using `this.manager_.getCustomRepository` passing it `this.postRepository` as a parameter. This lets you use [Custom Repositories with Typeorm](https://typeorm.io/custom-repository) to create custom methods in your repository that work with the data in your database.
After getting an instance of the repository, you can then use [Typeorm’s Repository methods](https://typeorm.io/repository-api) to perform Create, Read, Update, and Delete (CRUD) operations on your entity.
If you need access to your entity in endpoints, you can then use the methods you define in the service.
:::note
This same usage of repositories can be done in subscribers as well.
:::
### Delete a Soft-Deletable Entity
To delete soft-deletable entities that extend the `SoftDeletableEntity` class, you can use the repository method `softDelete` method:
```ts
await postRepository.softDelete(post.id)
```
---
## See Also
- [Migrations Overview](./migrations/overview.mdx)
- [Create a Plugin](../plugins/create.md)

109
docs/content/development/entities/migrations/create.md Normal file
View File

@@ -0,0 +1,109 @@
---
description: 'Learn how to create a migration in Medusa. This guide explains how to write and run migrations.'
addHowToData: true
---
# How to Create Migrations
In this document, you’ll learn how to create a [Migration](./overview.mdx) using [Typeorm](https://typeorm.io) in Medusa.
## Step 1: Create Migration File
To create a migration that makes changes to your Medusa schema, run the following command:
```bash
npx typeorm migration:create -n UserChanged --dir src/migrations
```
This will create the migration file in the path you specify. You can use this without the need to install Typeorm's CLI tool. You can then go ahead and make changes to it as necessary.
The migration file must be inside the `src/migrations` directory. When you run the build command, it will be transpiled into the directory `dist/migrations`. The `migrations run` command can only pick up migrations under the `dist/migrations` directory on a Medusa backend. This applies to migrations created in a Medusa backend, and not in a Medusa plugin. For plugins, check out the [Plugin's Structure section](../../plugins/create.md).
<details>
<summary>Generating Migrations for Entities</summary>
You can alternatively use Typeorm's `generate` command to generate a Migration file from existing entity classes. As Medusa uses v0.2.45 of Typeorm, you have to create a `ormconfig.json` first before using the `generate` command.
:::note
Typeorm will be updated to the latest version in v1.8.0 of Medusa.
:::
For example, create the file `ormconfig.json` in the root of your Medusa server with the following content:
```json
{
"type": "postgres",
"host": "localhost",
"port": 5432,
"username": "<YOUR_DB_USERNAME>",
"password": "<YOUR_DB_PASSWORD>",
"database": "<YOUR_DB_NAME>",
"synchronize": true,
"logging": false,
"entities": [
"dist/models/**/*.js"
],
"migrations": [
"dist/migrations/**/*.js"
],
"cli": {
"entitiesDir": "src/models",
"migrationsDir": "src/migrations"
}
}
```
Make sure to replace `<YOUR_DB_USERNAME>`, `<YOUR_DB_PASSWORD>`, and `<YOUR_DB_NAME>` with the necessary values for your database connection.
Then, after creating your entity, run the `build` command:
```bash npm2yarn
npm run build
```
Finally, run the following command to generate a Migration for your new entity:
```bash
npx typeorm@0.2.45 migration:generate -n PostCreate
```
Where `PostCreate` is just an example of the name of the migration to generate. The migration will then be generated in `src/migrations/<TIMESTAMP>-PostCreate.ts`. You can then skip to step 3 of this guide.
</details>
---
## Step 2: Write Migration File
The migration file contains the necessary commands to create the database columns, foreign keys, and more.
You can learn more about writing the migration file in You can learn more about writing migrations in [Typeorm’s Documentation](https://typeorm.io/migrations).
---
## Step 3: Build Files
Before you can run the migrations you need to run the build command to transpile the TypeScript files to JavaScript files:
```bash npm2yarn
npm run build
```
---
## Step 4: Run Migration
The last step is to run the migration with the command detailed earlier
```bash
medusa migrations run
```
If you check your database now you should see that the change defined by the migration has been applied successfully.
---
## See Also
- [Create a Plugin](../../plugins/create.md)

85
docs/content/development/entities/migrations/overview.mdx Normal file
View File

@@ -0,0 +1,85 @@
---
description: 'Learn what Migrations are in Medusa and how to run them. Migrations are used to make changes to the database schema that Medusa is linked to.'
---
import DocCardList from '@theme/DocCardList';
import Icons from '@theme/Icon';
# Migrations
In this document, you'll learn what Migrations are in Medusa.
:::note
Medusa’s Migrations do not work with SQLite databases. They are intended to be used with PostgreSQL databases, which is the recommended database for using Medusa in production.
:::
## What are Migrations
Migrations are scripts that are used to make additions or changes to your database schema. In Medusa, they are essential for both when you first install your backend and for subsequent backend upgrades later on.
When you first create your Medusa backend, the database schema used must have all the tables necessary for the backend to run.
When a new Medusa version introduces changes to the database schema, you'll have to run migrations to apply them to your own database.
:::tip
Migrations are used to apply changes to the database schema. However, there are some version updates of Medusa that require updating the data in your database to fit the new schema. Those are specific to each version and you should check out the version under Upgrade Guides for details on the steps.
:::
---
## How to Run Migrations
Migrations in Medusa can be done in one of two ways:
### Migrate Command
Using the Medusa CLI tool, you can run migrations with the following command:
```bash
medusa 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.
### Seed Command
Seeding is the process of filling your database with data that is either essential or for testing and demo purposes. In Medusa, the `seed` command will run the migrations to your database if necessary before it seeds your database with dummy data.
You can use the following command to seed your database:
```bash npm2yarn
npm run seed
```
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.
---
## Custom Development
Developers can create custom entities in the Medusa backend, a plugin, or in a Commerce Module, then ensure it reflects in the database using a migration.
<DocCardList colSize={6} items={[
{
type: 'link',
href: '/development/entities/migrations/create',
label: 'Create a Migration',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to create migrations in Medusa.'
}
},
{
type: 'link',
href: '/development/entities/create',
label: 'Create an Endpoint',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to create endpoints in Medusa.'
}
},
]} />

94
docs/content/development/entities/overview.mdx Normal file
View File

@@ -0,0 +1,94 @@
---
description: 'Learn what entities are in Medusa. There are entities defined in the Medusa backend, and developers can create custom entities.'
---
import DocCardList from '@theme/DocCardList';
import Icons from '@theme/Icon';
# Entities
In this document, you'll learn what Entities are in Medusa.
## What are Entities
Entities in medusa represent tables in the database as classes. An example of this would be the `Order` entity which represents the `order` table in the database. Entities provide a uniform way of defining and interacting with data retrieved from the database.
Aside from the entities in the Medusa core package, you can also create your own entities to use in your Medusa backend. Custom entities are TypeScript or JavaScript files located in the `src/models` directory of your Medusa backend. These entities are then transpiled to the `dist/models` directory to be used during the backend's runtime.
Entities are TypeScript files and they are based on [Typeorm’s Entities](https://typeorm.io/entities) and use Typeorm decorators.
---
## Base Entities
All entities must extend either the `BaseEntity` or `SoftDeletableEntity` classes. The `BaseEntity` class holds common columns including the `id`, `created_at`, and `updated_at` columns.
The `SoftDeletableEntity` class extends the `BaseEntity` class and adds another column `deleted_at`. If an entity can be soft deleted, meaning that a row in it can appear to the user as deleted but still be available in the database, it should extend `SoftDeletableEntity`.
---
## metadata Attribute
Most entities in Medusa have a `metadata` attribute. This attribute is an object that can be used to store custom data related to that entity. In the database, this attribute is stored as a [JSON Binary (JSONB)](https://www.postgresql.org/docs/current/datatype-json.html#JSON-CONTAINMENT) column. On retrieval, the attribute is parsed into an object.
Some example use cases for the `metadata` attribute include:
- Store an external ID of an entity related to a third-party integartion.
- Store product customization such as personalization options.
### Add and Update Metadata
You can add or update metadata entities either through the REST APIs or through create and update methods in the entity's respective service.
In the [admin REST APIs](/api/admin), you'll find that in create or update requests of some entities you can also set the `metadata`.
In services, there are typically `create` or `update` methods that allow you to set or update the metadata.
If you want to add a property to the `metadata` object or update a property in the `metadata` object, you can pass the `metadata` object with the properties you want to add or update in it. For example:
```json
{
// other data
"metadata": {
"is_b2b": true
}
}
```
If you want to remove a property from the `metadata` object, you can pass the `metadata` object with the property you want to delete. The property should have an empty string value. For example:
```json
{
// other data
"metadata": {
"is_b2b": "" // this deletes the `is_b2b` property from `metadata`
}
}
```
---
## Custom Development
Developers can create custom entities in the Medusa backend, a plugin, or in a Commerce Module, then ensure it reflects in the database using a migration.
<DocCardList colSize={6} items={[
{
type: 'link',
href: '/development/entities/create',
label: 'Create an Endpoint',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to create endpoints in Medusa.'
}
},
{
type: 'link',
href: '/development/entities/migrations/create',
label: 'Create a Migration',
customProps: {
icon: Icons['academic-cap-solid'],
description: 'Learn how to create migrations in Medusa.'
}
},
]} />