OpenParable
Skip to content
← Back to skills

Om Eject And Customize

Development
om-eject-and-customize

Om Eject And Customize is an Agent Skill for development published in the open-mercato/open-mercato repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guide for safely ejecting and customizing core modules. Use when a developer needs to modify a core module's behavior beyond what UMES extensions support, wants to eject a module, or is considering whether to eject vs extend. Triggers on "eject", "customize module", "modify core module", "override module", "fork module", "change built-in", "should I eject".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/open-mercato/open-mercato/blob/HEAD/packages/create-app/agentic/shared/ai/skills/om-eject-and-customize/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/om-eject-and-customize, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

What You Want to DoUse UMES ExtensionEject Required
Add fields to a formField Injection (system-extension skill)No
Add columns to a tableColumn Injection (system-extension skill)No
Add data to API responsesResponse EnricherNo
Validate/block mutationsMutation Guard or API InterceptorNo
Change how a component looksComponent Replacement (wrapper)No
Add menu itemsMenu InjectionNo
React to domain eventsEvent SubscribersNo
Change entity schema (add/remove columns)Not possible via UMESYes
Change core business logic (pricing, auth flow)Not possible via UMESYes
Remove built-in fields from formsNot possible via UMESYes
Change API route validation rulesPartially (interceptors), but deep changes need ejectMaybe
Change database relationshipsNot possible via UMESYes

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:

File/AreaSafe ChangesRisk Level
backend/*.tsxUI layout, field order, page structureLow
data/validators.tsValidation rules, field constraintsLow
api/*/ handlersBusiness logic within existing routesMedium
commands/Command execute/undo logicMedium
entities/Adding new columns (with migration)Medium
subscribers/Event handler logicLow
workers/Job processing logicLow
widgets/Widget componentsLow

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:

File/AreaDangerWhy
index.ts metadataChanging name/idOther modules reference this ID
acl.ts feature IDsRenaming featuresFeature IDs are stored in DB, referenced by roles
events.ts event IDsRenaming eventsOther modules subscribe to these event IDs
Entity table/column renameDatabase references breakFKs in other modules, stored data
di.ts service namesRenaming DI keysOther modules resolve by name
Removing API routesExternal consumers breakOther modules/integrations call these
setup.ts structureChanging tenant initAffects new tenant provisioning

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