0
# Plugin Integration
1

2
Core plugin functionality for integrating @medusajs/admin with Medusa server instances. Provides Express routes, static file serving, and automatic build management.
3

4
## Capabilities
5

6
### Webpack Configuration
7

8
Provides custom webpack configuration integration with @medusajs/admin-ui.
9

10
```typescript { .api }
11
/**
12
 * Custom webpack configuration function
13
 * Re-exported from @medusajs/admin-ui
14
 */
15
function withCustomWebpackConfig(): any;
16
```
17

18
### API Route Handler
19

20
Creates Express router for serving the admin dashboard and handling production/development modes.
21

22
```typescript { .api }
23
/**
24
 * Creates Express routes for admin dashboard
25
 * @param rootDirectory - Application root directory
26
 * @param options - Plugin configuration options
27
 * @returns Express Router instance
28
 */
29
function createAdminRoutes(
30
  rootDirectory: string, 
31
  options: PluginOptions
32
): Router;
33
```
34

35
**Implementation details:**
36
- Serves static files in production mode
37
- Returns development message in develop mode
38
- Handles missing build files with helpful error messages
39
- Sets appropriate caching headers for static assets
40

41
### Setup Function
42

43
Automatic setup and build management for admin dashboard during server startup.
44

45
```typescript { .api }
46
/**
47
 * Setup admin dashboard during server startup
48
 * Automatically builds if autoRebuild is enabled and changes detected
49
 */
50
function setupAdmin(): Promise<void>;
51
```
52

53
**Setup process:**
54
1. Checks if running in development mode (skips if true)
55
2. Validates serve and autoRebuild options
56
3. Determines if rebuild is needed using build manifest
57
4. Executes clean and build process if required
58
5. Creates new build manifest with current state
59

60
### Configuration Loading
61

62
Loads plugin configuration from Medusa config file.
63

64
```typescript { .api }
65
/**
66
 * Load plugin configuration from medusa-config.js
67
 * @param isDev - Whether running in development mode
68
 * @returns Plugin options or null if not configured
69
 */
70
function loadConfig(isDev?: boolean): PluginOptions | null;
71
```
72

73
**Configuration resolution:**
74
- Searches for @medusajs/admin in plugins array
75
- Merges default options with user-provided options
76
- Applies development-specific defaults when isDev=true
77
- Returns null if plugin not found in configuration
78

79
### Plugin Path Discovery
80

81
Discovers other plugins with admin UI extensions enabled.
82

83
```typescript { .api }
84
/**
85
 * Get paths of plugins with admin UI enabled
86
 * @returns Array of plugin paths with UI extensions
87
 */
88
function getPluginPaths(): Promise<string[]>;
89
```
90

91
**Discovery process:**
92
- Reads medusa-config.js for plugin configuration
93
- Filters plugins with enableUI: true option
94
- Returns array of plugin resolve paths for bundling
95

96
## Configuration Options
97

98
### Plugin Options
99

100
```typescript { .api }
101
interface PluginOptions extends AdminOptions {
102
  /** Whether to serve the admin dashboard */
103
  serve?: boolean;
104
  /** 
105
   * Re-build admin automatically when options change
106
   * Memory intensive - use carefully in production
107
   */
108
  autoRebuild?: boolean;
109
}
110

111
interface AdminOptions {
112
  /** Path to serve admin dashboard (default: "/app") */
113
  path?: string;
114
  /** Output directory for build files (default: "build") */
115
  outDir?: string;
116
  /** Backend URL for API calls (default: "/") */
117
  backend?: string;
118
  /** Development server configuration */
119
  develop?: DevelopmentOptions;
120
}
121

122
interface DevelopmentOptions {
123
  /** Development server port (default: 7001) */
124
  port?: number;
125
  /** Development server host (default: "localhost") */
126
  host?: string;
127
  /** Auto-open browser (default: true) */
128
  open?: boolean;
129
  /** Allowed hosts configuration (default: "auto") */
130
  allowedHosts?: string;
131
  /** WebSocket URL for hot reload */
132
  webSocketURL?: string;
133
}
134
```
135

136
## Usage Examples
137

138
### Basic Plugin Configuration
139

140
```javascript
141
// medusa-config.js
142
module.exports = {
143
  plugins: [
144
    {
145
      resolve: "@medusajs/admin",
146
      options: {
147
        serve: true,
148
        path: "/admin",
149
        autoRebuild: false
150
      }
151
    }
152
  ]
153
};
154
```
155

156
### Development Configuration
157

158
```javascript
159
// medusa-config.js
160
module.exports = {
161
  plugins: [
162
    {
163
      resolve: "@medusajs/admin",
164
      options: {
165
        serve: true,
166
        autoRebuild: true,
167
        develop: {
168
          port: 3001,
169
          open: false
170
        }
171
      }
172
    }
173
  ]
174
};
175
```
176

177
### Production Configuration
178

179
```javascript
180
// medusa-config.js
181
module.exports = {
182
  plugins: [
183
    {
184
      resolve: "@medusajs/admin",
185
      options: {
186
        serve: true,
187
        path: "/dashboard",
188
        outDir: "admin-build",
189
        backend: "https://api.mystore.com",
190
        autoRebuild: false
191
      }
192
    }
193
  ]
194
};
195
```
196

197
## Build Manifest System
198

199
The plugin uses a build manifest system to determine when rebuilds are necessary:
200

201
### Manifest Location
202
- Stored at `.cache/admin-build-manifest.json`
203
- Contains build metadata for change detection
204

205
### Change Detection
206
Rebuilds are triggered when:
207
- Plugin options have changed
208
- Package dependencies have changed  
209
- Admin extension files have been modified
210
- Plugin list with UI extensions has changed
211
- Build manifest is missing or corrupted
212

213
### Manifest Contents
214
- **dependencies**: Package.json dependencies snapshot
215
- **modifiedAt**: Most recent modification time of admin files
216
- **plugins**: List of plugins with admin UI enabled
217
- **options**: Plugin configuration used for build
218

219
## Error Handling
220

221
### Missing Build Files
222
When admin build files are missing in production:
223
```
224
Could not find the admin UI build files. Please run "medusa-admin build" or enable "autoRebuild" in the plugin options.
225
```
226

227
### Configuration Errors
228
- Invalid medusa-config.js files are handled gracefully
229
- Missing plugin configuration returns null from loadConfig
230
- Malformed plugin options use sensible defaults
231

232
### Development Mode Detection
233
- Uses `process.env.COMMAND_INITIATED_BY === "develop"` to detect development mode
234
- Serves different responses for development vs production modes