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

docs: document auto-generated types (#13050)

Browse Source
This commit is contained in:
Shahed Nasser
2025-07-25 17:48:18 +03:00
committed by GitHub
parent 5a01ef89ea
commit 0d8c2c4056
6 changed files with 205 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
www/apps/book/app/learn/fundamentals/generated-types/page.mdx Normal file
View File

@@ -0,0 +1,88 @@
import { CodeTabs, CodeTab } from "docs-ui"
export const metadata = {
title: `${pageNumber} Automatically Generated Types`,
}
# {metadata.title}
In this chapter, you'll learn about the types Medusa automatically generates under the `.medusa` directory and how you should use them.
## What are Automatically Generated Types?
Medusa automatically generates TypeScript types for:
1. Data models collected in the [Query's graph](../module-links/query/page.mdx#querying-the-graph). These types provide you with auto-completion and type checking when using Query.
- Generated data model types are located in the `.medusa/types/query-entry-points.d.ts` file.
2. Modules registered in the [Medusa container](../medusa-container/page.mdx). These types provide you with auto-completion and type checking when resolving modules from the container.
- Generated module registration names are located in the `.medusa/types/modules-bindings.d.ts` file.
![Diagram showcasing the directory structure of the `.medusa` directory, highlighting the `types` folder and its contents.](https://res.cloudinary.com/dza7lstvk/image/upload/v1753448927/Medusa%20Book/generated-types-dir_bmvdts.jpg)
---
## How to Trigger Type Generation?
The Medusa application generates these types automatically when you run the application with the `dev` command:
```bash npm2yarn
npm run dev
```
So, if you add a new data model or module and you don't find it in auto-completion or type checking, you can run the `dev` command to regenerate the types.
---
## How to Use the Generated Types?
The generated types are only meant for auto-completion and type checking.
For example, consider you have a Brand Module with a `Brand` data model. Due to the auto-generated types, you can do the following:
<CodeTabs group="auto-generated-types">
<CodeTab value="query" label="Query">
```ts
const { data: [brand] } = await query.graph({
entity: "brand",
fields: ["*"],
filters: {
id: "brand_123",
},
})
// brands has the correct type, so you can access its properties with auto-completion and type checking
console.log(brand.name)
```
</CodeTab>
<CodeTab value="container" label="Container">
```ts
const brandModuleService = req.scope.resolve("brand")
// brandModuleService has the correct type, so you can access its methods with auto-completion and type checking
const brand = await brandModuleService.retrieveBrand("brand_123")
```
</CodeTab>
</CodeTabs>
### Don't Import the Generated Types
The generated types are only meant to help you in your development process by providing auto-completion and type checking. You should not import them directly in your code.
Since you don't commit the `.medusa` directory to your version control system or your production environment, importing these types may lead to build errors.
Instead, if you need to use a data model's type in your customizations, you can use the [InferTypeOf](../data-models/infer-type/page.mdx) utility function, which infers the type of a data model based on its properties.
For example, if you want to use the `Brand` data model's type in your customizations, you can do the following:
```ts
import { InferTypeOf } from "@medusajs/framework/types"
import { Brand } from "../modules/brand/models/brand" // relative path to the model
export type BrandType = InferTypeOf<typeof Brand>
```
You can then use the `BrandType` type in your customizations, such as in workflow inputs or service method outputs.

10
www/apps/book/app/learn/fundamentals/medusa-container/page.mdx
View File

@@ -178,3 +178,13 @@ const step1 = createStep("step-1", async (_, { container }) => {
A [module](../../fundamentals/modules/page.mdx), which is a package of functionalities for a single feature or domain, has its own container, so it can't resolve resources from the Medusa container.
Learn more about the module's container in [this chapter](../../fundamentals/modules/container/page.mdx).
---
## Container Registration Keys Auto-Completion
When you resolve a resource from the Medusa container, you can use auto-completion to find the registration key of the resource.
This is possible due to Medusa's auto-generated types, which are generated in the `.medusa` directory when you run the `dev` command.
Learn more in the [Auto-Generated Types](../generated-types/page.mdx) chapter.

5
www/apps/book/generated/edit-dates.mjs
View File

@@ -12,7 +12,7 @@ export const generatedEditDates = {
"app/learn/fundamentals/admin-customizations/page.mdx": "2024-10-07T12:41:39.218Z",
"app/learn/fundamentals/workflows/workflow-timeout/page.mdx": "2025-04-24T13:15:14.472Z",
"app/learn/fundamentals/workflows/parallel-steps/page.mdx": "2025-03-24T06:53:36.918Z",
"app/learn/fundamentals/medusa-container/page.mdx": "2024-12-09T11:02:38.225Z",
"app/learn/fundamentals/medusa-container/page.mdx": "2025-07-25T13:18:36.859Z",
"app/learn/fundamentals/api-routes/page.mdx": "2024-12-04T11:02:57.134Z",
"app/learn/fundamentals/modules/modules-directory-structure/page.mdx": "2024-12-09T10:32:46.839Z",
"app/learn/fundamentals/events-and-subscribers/page.mdx": "2025-05-16T13:40:16.111Z",
@@ -123,5 +123,6 @@ export const generatedEditDates = {
"app/learn/fundamentals/module-links/index/page.mdx": "2025-05-23T07:57:58.958Z",
"app/learn/fundamentals/module-links/index-module/page.mdx": "2025-06-19T16:02:05.665Z",
"app/learn/introduction/build-with-llms-ai/page.mdx": "2025-07-22T16:19:11.668Z",
"app/learn/installation/docker/page.mdx": "2025-07-23T15:34:18.530Z"
"app/learn/installation/docker/page.mdx": "2025-07-23T15:34:18.530Z",
"app/learn/fundamentals/generated-types/page.mdx": "2025-07-25T13:17:35.319Z"
}

10
www/apps/book/generated/sidebar.mjs
View File

@@ -932,6 +932,16 @@ export const generatedSidebars = [
],
"chapterTitle": "3.11. Custom CLI Scripts",
"number": "3.11."
},
{
"loaded": true,
"isPathHref": true,
"type": "link",
"path": "/learn/fundamentals/generated-types",
"title": "Auto-Generated Types",
"children": [],
"chapterTitle": "3.12. Auto-Generated Types",
"number": "3.12."
}
],
"chapterTitle": "3. Framework",

89
www/apps/book/public/llms-full.txt
View File

@@ -11132,6 +11132,85 @@ To learn more about the different concepts useful for building plugins, check ou
- [Plugins](https://docs.medusajs.com/learn/fundamentals/plugins/index.html.md)
# Automatically Generated Types
In this chapter, you'll learn about the types Medusa automatically generates under the `.medusa` directory and how you should use them.
## What are Automatically Generated Types?
Medusa automatically generates TypeScript types for:
![Diagram showcasing the directory structure of the .medusa directory, highlighting the types folder and its contents.](https://res.cloudinary.com/dza7lstvk/image/upload/v1753448927/Medusa%20Book/generated-types-dir_bmvdts.jpg)
1. Data models collected in the [Query's graph](https://docs.medusajs.com/learn/fundamentals/module-links/query#querying-the-graph/index.html.md). These types provide you with auto-completion and type checking when using Query.
- Generated data model types are located in the `.medusa/types/query-entry-points.d.ts` file.
2. Modules registered in the [Medusa container](https://docs.medusajs.com/learn/fundamentals/medusa-container/index.html.md). These types provide you with auto-completion and type checking when resolving modules from the container.
- Generated module registration names are located in the `.medusa/types/modules-bindings.d.ts` file.
***
## How to Trigger Type Generation?
The Medusa application generates these types automatically when you run the application with the `dev` command:
```bash npm2yarn
npm run dev
```
So, if you add a new data model or module and you don't find it in auto-completion or type checking, you can run the `dev` command to regenerate the types.
***
## How to Use the Generated Types?
The generated types are only meant for auto-completion and type checking.
For example, consider you have a Brand Module with a `Brand` data model. Due to the auto-generated types, you can do the following:
### Query
```ts
const { data: [brand] } = await query.graph({
entity: "brand",
fields: ["*"],
filters: {
id: "brand_123",
},
})
// brands has the correct type, so you can access its properties with auto-completion and type checking
console.log(brand.name)
```
### Container
```ts
const brandModuleService = req.scope.resolve("brand")
// brandModuleService has the correct type, so you can access its methods with auto-completion and type checking
const brand = await brandModuleService.retrieveBrand("brand_123")
```
### Don't Import the Generated Types
The generated types are only meant to help you in your development process by providing auto-completion and type checking. You should not import them directly in your code.
Since you don't commit the `.medusa` directory to your version control system or your production environment, importing these types may lead to build errors.
Instead, if you need to use a data model's type in your customizations, you can use the [InferTypeOf](https://docs.medusajs.com/learn/fundamentals/data-models/infer-type/index.html.md) utility function, which infers the type of a data model based on its properties.
For example, if you want to use the `Brand` data model's type in your customizations, you can do the following:
```ts
import { InferTypeOf } from "@medusajs/framework/types"
import { Brand } from "../modules/brand/models/brand" // relative path to the model
export type BrandType = InferTypeOf<typeof Brand>
```
You can then use the `BrandType` type in your customizations, such as in workflow inputs or service method outputs.
# Medusa Container
In this chapter, you’ll learn about the Medusa container and how to use it.
@@ -11281,6 +11360,16 @@ A [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md),
Learn more about the module's container in [this chapter](https://docs.medusajs.com/learn/fundamentals/modules/container/index.html.md).
***
## Container Registration Keys Auto-Completion
When you resolve a resource from the Medusa container, you can use auto-completion to find the registration key of the resource.
This is possible due to Medusa's auto-generated types, which are generated in the `.medusa` directory when you run the `dev` command.
Learn more in the [Auto-Generated Types](https://docs.medusajs.com/learn/fundamentals/generated-types/index.html.md) chapter.
# Add Columns to a Link Table

5
www/apps/book/sidebar.mjs
View File

@@ -493,6 +493,11 @@ export const sidebars = [
},
],
},
{
type: "link",
path: "/learn/fundamentals/generated-types",
title: "Auto-Generated Types",
},
],
},
{