docs: add section on type aliases in admin + note for removing items from orders (#12996)

2025-07-18 18:35:58 +03:00
parent b46bbfae12
commit ed92aaf02b
6 changed files with 277 additions and 30 deletions
@@ -4,17 +4,30 @@ export const metadata = {

 # {metadata.title}

-By default, Medusa doesn't support TypeScript aliases in production.
+In this chapter, you'll learn how to use TypeScript aliases in your Medusa application.

-If you prefer using TypeScript aliases, install following development dependencies:
+## Support for TypeScript Aliases
+
+By default, Medusa doesn't support TypeScript aliases in production. That means you may get build errors in production if you use them in your development.
+
+If you prefer using TypeScript aliases, this section will guide you through the steps to enable them in your Medusa application.
+
+### Step 1: Install Required Dependencies
+
+Start by installing the following development dependencies:

 ```bash npm2yarn
 npm install --save-dev tsc-alias rimraf
 ```

-Where `tsc-alias` is a package that resolves TypeScript aliases, and `rimraf` is a package that removes files and directories.
+Where:

-Then, add a new `resolve:aliases` script to your `package.json` and update the `build` script:
+- `tsc-alias` resolves TypeScript aliases.
+- `rimraf` removes files and directories.
+
+### Step 2: Update `package.json`
+
+Then, add a new `resolve:aliases` script to your `package.json` and update the existing `build` script:

 ```json title="package.json"
 {
@@ -26,7 +39,11 @@ Then, add a new `resolve:aliases` script to your `package.json` and update the `
 }
 ```

-You can now use TypeScript aliases in your Medusa application. For example, add the following in `tsconfig.json`:
+### Step 3: Update `tsconfig.json`
+
+Next, configure the TypeScript aliases you want to use in your `tsconfig.json` file by adding a `paths` property under `compilerOptions`.
+
+For example, to import anything under the `src` directory using type aliases, add the following in `tsconfig.json`:

 ```json title="tsconfig.json"
 {
@@ -39,8 +56,110 @@ You can now use TypeScript aliases in your Medusa application. For example, add
 }
 ```

-Now, you can import modules, for example, using TypeScript aliases:
+### Step 4: Use TypeScript Aliases
+
+Then, you can use the `@` alias in your application code.
+
+For example, if you have a service in `src/modules/brand/service.ts`, you can import it like this:

 ```ts
 import { BrandModuleService } from "@/modules/brand/service"
 ```
+
+---
+
+## Support TypeScript Aliases for Admin Customizations
+
+Medusa also doesn't support TypeScript aliases in the admin customizations by default. However, you can also configure your Medusa application to use TypeScript aliases in your admin customizations.
+
+### Step 1: Update `src/admin/tsconfig.json`
+
+Update `src/admin/tsconfig.json` to include `baseUrl` and `paths` configuration:
+
+```json title="src/admin/tsconfig.json"
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"] 
+    }
+
+    // other options...
+  }
+}
+```
+
+The `baseUrl` option sets the base directory to `src/admin`, and the `paths` option defines the `@` alias to allow importing files from the `src/admin` directory using aliases.
+
+### Step 2: Update `medusa-config.ts`
+
+Next, update the `vite` configuration in `medusa-config.ts` to include the `resolve.alias` configuration:
+
+```ts title="medusa-config.ts"
+import path from 'path'
+
+module.exports = defineConfig({
+  // ...
+  admin: {
+    vite: () => ({
+      resolve: {
+        alias: {
+          "@": path.resolve(__dirname, "./src/admin"),
+        },
+      },
+    }),
+  },
+})
+```
+
+<Note title="Tip">
+
+Learn more about the `vite` configuration in the [Medusa configuration](../medusa-config/page.mdx) chapter.
+
+</Note>
+
+### Step 3: Use TypeScript Aliases in Admin Customizations
+
+You can now use the `@` alias in your admin customizations, just like you do in your main application code.
+
+For example, if you have a component in `src/admin/components/Container.tsx`, you can import it in a widget like this:
+
+```ts
+import Container from "@/components/Container"
+```
+
+### Match TSConfig and Vite Alias Configuration
+
+Make sure that the `@` alias points to the same path as in your `src/admin/tsconfig.json`.
+
+For example, if you set the `@/*` alias to point to `./components/*`:
+
+```json title="src/admin/tsconfig.json"
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./components/*"]
+    }
+  }
+}
+```
+
+Then, the `vite` alias configuration would be:
+
+```ts title="medusa-config.ts"
+import path from 'path'
+
+module.exports = defineConfig({
+  // ...
+  admin: {
+    vite: () => ({
+      resolve: {
+        alias: {
+          "@": path.resolve(__dirname, "./src/admin/components"),
+        },
+      },
+    }),
+  },
+})
+```