om-eject-and-customize

Eject & Customize

Guide for safely ejecting core modules and making targeted customizations. Ejecting is a one-way door — always consider UMES extensions first.

Table of Contents

1. Should You Eject?
2. Pre-Ejection Analysis
3. Performing the Ejection
4. What Gets Ejected
5. Safe Modification Zones
6. Dangerous Modification Zones
7. Tracking Customizations
8. Upgrade Strategy
9. Common Ejection Scenarios

---

1. Should You Eject?

Ejection is the last resort. Before recommending ejection, verify that UMES extensions cannot solve the problem.

Decision Matrix

Before Ejecting — Try These First

1. Response Enricher — Add computed data to any API response
2. API Interceptor — Validate, transform, or enrich requests/responses
3. Mutation Guard — Block or modify mutations before persistence
4. Component Replacement — Swap, wrap, or transform any registered component
5. Widget Injection — Add UI elements to any registered spot
6. Event Subscriber — React to domain events with side effects

If UMES truly cannot solve the problem, proceed with ejection.

---

2. Pre-Ejection Analysis

Before ejecting, understand what you're taking ownership of.

Step 1: Identify the Module

# List available core modules
ls node_modules/@open-mercato/core/dist/modules/

Step 2: Check Module Size

Look at the module's file count and complexity. Larger modules mean more upgrade burden.

Step 3: Identify the Specific Change

Be precise about what you need to change. Often only 1-2 files need modification, but ejection copies the entire module.

Step 4: Check Dependencies

Does the module depend on other core modules? Does anything depend on it? Cross-module dependencies increase risk.

Step 5: Document the Reason

Before ejecting, record why:

## Ejection: <module_id>
- **Date**: YYYY-MM-DD
- **Reason**: <why UMES extensions were insufficient>
- **Files to modify**: <specific files that need changes>
- **UMES alternatives considered**: <what was tried first>

Save this in .ai/specs/ or a project README for future reference.

---

3. Performing the Ejection

Run the Eject Command

yarn mercato module eject <module-id>

This copies the module from node_modules/@open-mercato/core/dist/modules/<module-id>/ to src/modules/<module-id>/.

The legacy alias yarn mercato eject <module-id> remains supported.

Post-Ejection Steps

# 1. The module is automatically re-registered as '@app' source
# Verify in src/modules.ts:
grep '<module-id>' src/modules.ts
# Should show: { id: '<module-id>', from: '@app' }

# 2. Regenerate discovery files
yarn generate

# 3. Verify the app starts
yarn dev

# 4. Verify module functionality
# Test CRUD operations in the admin panel

---

4. What Gets Ejected

The eject command copies all module files to your src/modules/ directory:

src/modules/<module-id>/
├── index.ts           # Module metadata
├── acl.ts             # ACL features
├── setup.ts           # Tenant init, role defaults
├── di.ts              # DI registrations
├── events.ts          # Event declarations
├── entities/          # MikroORM entities
├── data/
│   ├── validators.ts  # Zod schemas
│   ├── enrichers.ts   # Response enrichers (if any)
│   └── extensions.ts  # Entity extensions (if any)
├── api/               # API route handlers
├── backend/           # Admin UI pages
├── frontend/          # Public pages (if any)
├── subscribers/       # Event handlers
├── workers/           # Background jobs
├── widgets/           # UI widgets
├── commands/          # Command pattern implementations
└── migrations/        # Database migrations

Important: After ejection, the npm package version of this module is no longer used. Your local copy takes precedence.

---

5. Safe Modification Zones

These files can be modified with low risk:

Safe Modification Example: Add a Column

// 1. Add field to entity
@Property({ type: 'varchar', length: 100, nullable: true })
custom_field: string | null = null

// 2. Update validator
export const createSchema = z.object({
  // ... existing fields
  customField: z.string().max(100).optional(),
})

// 3. Generate migration
// yarn db:generate

// 4. Update form fields in backend pages

---

6. Dangerous Modification Zones

These changes have high upgrade risk or can break other modules:

Rules for Dangerous Zones

• NEVER rename entity table names or column names — other modules may reference them
• NEVER rename event IDs — subscribers in other modules depend on exact IDs
• NEVER rename ACL feature IDs — stored in database with role assignments
• NEVER remove API routes — other modules or external systems may call them
• NEVER rename DI service registration keys — other modules resolve by key name
• Adding is safe; renaming/removing is dangerous

---

7. Tracking Customizations

Keep a record of every change made to ejected modules. This is critical for upgrades.

Create a Customization Log

Create .ai/specs/EJECTED-MODULES.md:

# Ejected Module Customizations

## <module_id>

- **Ejected from version**: 0.4.2 (check package.json at time of ejection)
- **Ejected on**: YYYY-MM-DD
- **Reason**: <why UMES was insufficient>

### Changes Made

| Date | File | Change | Reason |
|------|------|--------|--------|
| YYYY-MM-DD | entities/Entity.ts | Added `custom_field` column | Business requirement X |
| YYYY-MM-DD | backend/page.tsx | Modified list columns | UX improvement |
| YYYY-MM-DD | data/validators.ts | Added custom validation rule | Data quality requirement |

After Every Change

Add a row to the changes table. This makes future upgrades manageable by showing exactly what was customized.

---

8. Upgrade Strategy

When upgrading Open Mercato packages (@open-mercato/*), ejected modules don't update automatically. You must manually merge upstream changes.

Upgrade Workflow

1. Check the changelog for the new version — look for changes to the ejected module
2. Compare your version with the new version:

   # After updating packages
   diff -r src/modules/<module-id>/ node_modules/@open-mercato/core/dist/modules/<module-id>/
   

3. Review each difference — your customizations should be the only differences
4. Merge upstream changes — apply bug fixes and new features from upstream to your local copy
5. Test thoroughly — run yarn typecheck, yarn test, yarn dev

Minimizing Upgrade Burden

• Minimize changes — only modify what's strictly necessary
• Keep changes isolated — prefer adding new files over modifying existing ones
• Document everything — update the customization log
• Consider UMES first — for new customizations, check if UMES can handle it even though the module is ejected

---

9. Common Ejection Scenarios

Scenario: Custom Pricing Logic

Problem: Need to change how product prices are calculated Module: catalog Files to modify: commands/UpdateProductPrice.ts, lib/pricing.ts UMES alternative tried: API Interceptor can't modify internal pricing calculation

Scenario: Custom Auth Flow

Problem: Need SSO integration not supported by built-in auth Module: auth Files to modify: api/post/login.ts, lib/auth-providers.ts UMES alternative tried: None available for core auth flow

Scenario: Custom Order Workflow

Problem: Need non-standard order status transitions Module: sales Files to modify: commands/UpdateOrderStatus.ts, entity status enum UMES alternative tried: Mutation Guard can block transitions but can't add new states

Scenario: Add Column to Core Entity

Problem: Need a column on Customer that doesn't exist Module: customers Files to modify: entities/Person.ts, data/validators.ts, backend/ pages UMES alternative tried: Enricher adds read-only data; need writable field in core schema

---

Rules

• MUST try UMES extensions before ejecting — recommend the om-system-extension skill first
• MUST document the reason for ejection before proceeding
• MUST track all changes in a customization log
• MUST run yarn generate after ejection
• MUST verify the app starts and module works after ejection
• MUST NOT rename entity tables, columns, event IDs, feature IDs, or DI keys
• MUST NOT remove API routes or event definitions
• MUST NOT modify files outside the ejected module's directory
• Treat ejected modules as owned code — you are responsible for updates and bug fixes
• When in doubt, extend rather than eject